Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Download Visual Studio Add-In

RegOpenKeyEx (advapi32)
 
.
Summary
Opens the specified registry key

C# Signature:

  [DllImport("advapi32.dll", CharSet = CharSet.Auto)]
  public static extern int RegOpenKeyEx(
    UIntPtr hKey,
    string subKey,
    int ulOptions,
    int samDesired,
    out UIntPtr hkResult);

VB Signature:

Declare Auto Function RegOpenKeyEx Lib "advapi32.dll"  (
   ByVal hKey As IntPtr,
   ByVal lpSubKey As String,
   ByVal ulOptions As Integer,
   ByVal samDesired As Integer,
   ByRef phkResult As Integer
) As Integer

User-Defined Types:

None.

Change Notes:

- Changed IntPtr to UIntPtr: When invoking with IntPtr for the handles, you will run into an Overflow. UIntPtr is the right choice if you wish this to work correctly on 32 and 64 bit platforms.

Notes:

The current managed versions of OpenSubKey do not support read/writing from the different registry "views" on 64-bit operating systems. So, you're forced to the the APIs to accomplish this feat. See the example below for a "drop in" replacement for OpenSubKey

If the function fails, the return value is a nonzero error code defined in Winerror.h. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

uint options: reserved, must be zero.

int sam: access mask that specifies the desired access rights to the key.

values for hKey (C#):

public static UIntPtr HKEY_LOCAL_MACHINE = new UIntPtr(0x80000002u);
public static UIntPtr HKEY_CURRENT_USER  = new UIntPtr(0x80000001u);

values for sam (VB):

Const KEY_QUERY_VALUE = &H1
Const KEY_SET_VALUE = &H2
Const KEY_CREATE_SUB_KEY = &H4
Const KEY_ENUMERATE_SUB_KEYS = &H8
Const KEY_NOTIFY = &H10
Const KEY_CREATE_LINK = &H20
Const KEY_WOW64_32KEY = &H200
Const KEY_WOW64_64KEY = &H100
Const KEY_WOW64_RES = &H300

For compatibility with 16-bit versions of Windows only 'RegOpenKey' is available.

Tips & Tricks:

Please add some!!

Sample Code (VB):

Public Enum RegWow64Options As Integer
   None = 0
   KEY_WOW64_64KEY = &H100
   KEY_WOW64_32KEY = &H200
End Enum

Public Enum RegistryRights As Integer
   ReadKey = 131097
   WriteKey = 131078
End Enum

' overloaded, see below
Public Function OpenSubKey(ByVal Name As String) As RegistryKey
   Return OpenSubKey(Name, False, RegWow64Options.None)
End Function

' overloaded, see below
Public Function OpenSubKey(ByVal Name As String, ByVal Writeable As Boolean) As RegistryKey
   Return OpenSubKey(Name, Writeable, RegWow64Options.None)
End Function

' open a SubKey
Public Function OpenSubKey(ByVal Name As String, ByVal Writeable As Boolean, ByVal Options As RegWow64Options) As RegistryKey
   Dim ret, Rights As Integer
   Dim hSubKey As IntPtr

   ' quick sanity check
   If hKey.Equals(IntPtr.Zero) Then
     Throw New ApplicationException("Cannot access a closed registry key")
   End If

   Rights = RegistryRights.ReadKey
   If Writeable Then
     Rights = RegistryRights.WriteKey
   End If

   ' Ignore the 64-bit flags when running from <= Win2k
   If CDbl(Environment.OSVersion.Version.Major & "." & Environment.OSVersion.Version.Minor) <= 5.0 Then
     Options = RegWow64Options.None
   End If

   ret = RegOpenKeyEx(hKey, Name, 0, Rights Or Options, hSubKey)
   If ret <> 0 Then
     Return Nothing
   End If

   Dim ans As New RegistryKey
   ans.hKey = hSubKey
   ans.RegKeyName = Name
   ans.IsRootHive = False
   Return ans
End Function

Sample Code (VB) to convert an IntPtr to a RegistryKey

Note that because this uses undocumented private functions, it could break in the future. Apparently .NET 4.0 will include native functionality for reading 64-bit registry from 32-bit processes etc.

Public Shared Function PointerToRegistryKey(ByVal hKey As IntPtr, ByVal writable As Boolean, ByVal ownsHandle As Boolean) As RegistryKey
    ' Create a SafeHandles.SafeRegistryHandle from this pointer - this is a private class
    Dim privateConstructors = Reflection.BindingFlags.Instance Or Reflection.BindingFlags.NonPublic
    Dim safeRegistryHandleType = GetType(SafeHandles.SafeHandleZeroOrMinusOneIsInvalid).Assembly.GetType("Microsoft.Win32.SafeHandles.SafeRegistryHandle")
    Dim safeRegistryHandleConstructorTypes As System.Type() = {GetType(IntPtr), GetType(Boolean)}
    Dim safeRegistryHandleConstructor = safeRegistryHandleType.GetConstructor(privateConstructors, Nothing, safeRegistryHandleConstructorTypes, Nothing)
    Dim safeHandle = safeRegistryHandleConstructor.Invoke(New Object() {hKey, ownsHandle})

    ' Create a new Registry key using the private constructor using the safeHandle - this should then behave like a .NET natively opened handle and disposed of correctly
    Dim registryKeyType = GetType(RegistryKey)
    Dim registryKeyConstructorTypes As System.Type() = {safeRegistryHandleType, GetType(Boolean)}
    Dim registryKeyConstructor = registryKeyType.GetConstructor(privateConstructors, Nothing, registryKeyConstructorTypes, Nothing)
    Dim result = DirectCast(registryKeyConstructor.Invoke(New Object() {safeHandle, writable}), RegistryKey)
    Return result
End Function

Sample Code (C#) to read a string value

string example = ReadRegKey(HKEY_LOCAL_MACHINE, @"Software\SomeCompany\OurProduct", "InstalledVersion");

private static string ReadRegKey(UIntPtr rootKey, string keyPath, string valueName)
{
   if (RegOpenKeyEx(rootKey, keyPath, 0, KEY_READ, out hKey) == 0)
   {
      uint size = 1024;
      uint type;
      string keyValue = null;
      StringBuilder keyBuffer = new StringBuilder();

      if (RegQueryValueEx(hKey, valueName, IntPtr.Zero, out type, keyBuffer, ref size) == 0)
      keyValue = keyBuffer.ToString();

      RegCloseKey(hKey);

      return(keyValue);
  }

  return(null);  // Return null if the value could not be read

}

Alternative Managed API:

Microsoft.Win32.Registry.BaseKeyName.OpenSubKey("[KeyName]")

Documentation

Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

 
Access PInvoke.net directly from VS:
Terms of Use
Find References
Show Printable Version
Revisions