Accessing the Windows Registry with the API

Tuesday Nov 19th 2002 by John Percival
Share:

Accessing the Windows Registry with the API

Last week, we looked at the basic Registry functions provided by VB. I also suggested a simple model by which we could think of the Registry.  I strongly recommend you read the first part of this series before this article, as many of the principles involved in this article are fairly complex.

The Registry originally appeared in Windows 3.x, as a store of OLE types. However, all application and Windows' settings were kept in private initialisation files, spread all over the hard disk. When Windows 95 was introduced, the people at Microsoft had had a good think about this, and decided to put all these settings in one central file, so if the computer crashed, you would lose all of your settings, not just one application's worth.   Well, this wasn't quite what they thought!  They really wanted to have all applications using the Registry to store settings instead of INI files, for reasons of support and adapting to multi-user environments.

Because of this, we recommend that you back up the Registry BEFORE you start playing, rather than after. The files that you need are system.dat and user.dat which are both in the Windows directory. That way, if everything goes wrong, you can replace the damaged ones.

This idea of one central database to store settings has been implemented in all the newest versions of Windows (i.e. Windows 98, Windows NT4, and Windows NT5/2000), and is definitely here to stay.

You can edit the Registry using a program called Regedit.exe. It is found in the Windows directory. It allows you to browse through the Registry, and make changes to it. This provides a very easy way to check that your app is doing what it should be doing in the correct places.

The Registry database model introduced last week was very much simplified. It suggested that the AppName parameter was specifying a 'drive' in the Registry. However, this area that VB writes to is in fact just another key. The real 'drives' are the entries that you see when you first start up Regedit. The two that you are most likely to use are HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE. In fact HKEY_CLASSES_ROOT is equal to HKEY_LOCAL_MACHINE\SOFTWARE\CLASSES, and HKEY_CURRENT_USER is the same as one of the entries in HKEY_USERS. VB in fact uses HKEY_CURRENT_USER\SOFTWARE\VB AND VBA PROGRAM SETTINGS to store the data.

The HKEY_CLASSES_ROOT key stores everything about documents, document readers, and how they relate to each other. It stores the information about extensions, and which applications are associated with the extension. It also stores information about DLLs and OCXs. See the article about the Registry and DLLs for more information. HKEY_LOCAL_MACHINE is where you will store most of your application's settings. The standard is:
HKEY_LOCAL_MACHINE\Software\CompanyName\AppName.

If you have user specific settings, you can store it in similar sub keys in HKEY_CURRENT_USER. You should not really need any of the other keys, although in HKEY_DYN_DATA you can find some information about windows, similar to the things found in the System Monitor (sysmon.exe) utility. You cannot write to this key.

One thing that you must be careful of, if your users could be running NT, is that you have the necessary privileges to read and write to keys in the Registry.

So, as a proficient Windows programmer, you must know how to access and change all parts, not just the parts that VB provides you with. To do this, we must use the API. First, let's have some declarations:

Declarations

Copy the following code into the declarations section of a module.

Public Const HKEY_CLASSES_ROOT = &H80000000
Public Const HKEY_CURRENT_USER = &H80000001
Public Const HKEY_LOCAL_MACHINE = &H80000002
Public Const HKEY_USERS = &H80000003
Public Const HKEY_CURRENT_CONFIG = &H80000005
Public Const HKEY_DYN_DATA = &H80000006
Public Const REG_SZ = 1 ' Unicode nul terminated string
Public Const REG_BINARY = 3 ' Free form binary
Public Const REG_DWORD = 4 ' 32-bit number
Public Const ERROR_SUCCESS = 0&

Public Declare Function RegCloseKey Lib "advapi32.dll" _
(ByVal hKey As Long) As Long

Public Declare Function RegCreateKey Lib "advapi32.dll" _
Alias "RegCreateKeyA" (ByVal hKey As Long, ByVal lpSubKey _
As String, phkResult As Long) As Long

Public Declare Function RegDeleteKey Lib "advapi32.dll" _
Alias "RegDeleteKeyA" (ByVal hKey As Long, ByVal lpSubKey _
As String) As Long

Public Declare Function RegDeleteValue Lib "advapi32.dll" _
Alias "RegDeleteValueA" (ByVal hKey As Long, ByVal _
lpValueName As String) As Long

Public Declare Function RegOpenKey Lib "advapi32.dll" _
Alias "RegOpenKeyA" (ByVal hKey As Long, ByVal lpSubKey _
As String, phkResult As Long) As Long

Public Declare Function RegQueryValueEx Lib "advapi32.dll" _
Alias "RegQueryValueExA" (ByVal hKey As Long, ByVal lpValueName _
As String, ByVal lpReserved As Long, lpType As Long, lpData _
As Any, lpcbData As Long) As Long

Public Declare Function RegSetValueEx Lib "advapi32.dll" _
Alias "RegSetValueExA" (ByVal hKey As Long, ByVal _
lpValueName As String, ByVal Reserved As Long, ByVal _
dwType As Long, lpData As Any, ByVal cbData As Long) As Long

The main idea for reading and writing to the Registry is to find and select a key, read/write a value, and then close the key. This is all based around handles to keys. Handles to keys (a similar idea to window handles and device context handles) are numbers, which Windows uses to reference a file or part of memory; in this case, it is a key in the Registry.

One of the limitations of using the built in functions of VB is that you can only write strings to the Registry. However, with the API, you can write Long type numbers and Byte arrays, as well as several other types of string. We will now take you through how to read and write to anywhere in the Registry.

Copy the following procedure into your project.

Public Sub DeleteValue( _
       ByVal hKey As Long, _
       ByVal strPath As String, _
       ByVal strValue As String)
Dim hCurKey As Long
Dim lRegResult As Long

lRegResult = RegOpenKey(hKey, _
                strPath, hCurKey)

lRegResult = RegDeleteValue(hCurKey, _
                            strValue)

lRegResult = RegCloseKey(hCurKey)

End Sub

The RegOpenKey API function to create takes a handle to a key, and the path that you want to select, and returns a handle to the new key. As was mentioned earlier, a handle to a key is a reference to a key. You must have a key to start with, so the six constants for the six root keys are fixed, and are provided as constants. The handles to these keys are the same on every Win32 system in every session. The other handles that you receive for the sub-keys will be variable, and will change each time you select the key. However, the handle will remain valid until you use the RegCloseKey function. If you don't close the handle to the key when you are finished with it, it will continue using up resources, so you must remember to close it when you are done.

Unusually, the Registry API functions will return 0 on success, and another number for failure. There is the constant ERROR_SUCCESS, which is defined to make code more readable when debugging.

This wrapper function takes a handle to a key, a path to a key, and the name of the value to delete. The handle to the key for most purposes will be one of the constant handles to a root key, and the path will be the path to the key. The path, as with the intrinsic VB functions can include the "" sign to signify sub keys. If you want to delete a value in the root of the key specified pass strPath as vbNullString. If you want to erase the default value, pass strValue as vbNullString.

Deleting Keys

Public Sub DeleteKey(ByVal hKey As Long, ByVal strPath As String)
Dim lRegResult As Long

lRegResult = RegDeleteKey(hKey, strPath)

End Sub

This function, as above, takes a handle to a key and a path to a key. It will find the key specified, and will delete all sub-keys and values, and using the 'drive' model would be equivalent to the 'deltree' DOS command - only without confirmation. Use this carefully, as it can have disastrous effects!

Creating Keys

Public Sub CreateKey(hKey As Long, strPath As String)
Dim hCurKey As Long
Dim lRegResult As Long

lRegResult = RegCreateKey(hKey, strPath, hCurKey)
If lRegResult <> ERROR_SUCCESS Then
' there is a problem
End If

lRegResult = RegCloseKey(hCurKey)

End Sub

Now that we are getting going, this does not need too much explaining. Pass a handle to a key and a path, and it will create all necessary keys to create the specified key. If you want to write an error handler into these functions, the function provides a space for checking whether the function has been a success.

Public Function GetSettingString( _
            hKey As Long, _
            strPath As String, _
            strValue As String, _
            Optional _
      Default As String) As String
Dim hCurKey As Long
Dim lResult As Long
Dim lValueType As Long
Dim strBuffer As String
Dim lDataBufferSize As Long
Dim intZeroPos As Integer
Dim lRegResult As Long

' Set up default value
If Not IsEmpty(Default) Then
GetSettingString = Default
Else
GetSettingString = ""
End If

lRegResult = RegOpenKey(hKey, _
                        strPath, hCurKey)
lRegResult = RegQueryValueEx(hCurKey, _
                    strValue, 0&, _
                    lValueType, ByVal 0&, _
                    lDataBufferSize)

If lRegResult = ERROR_SUCCESS Then

If lValueType = REG_SZ Then

strBuffer = String(lDataBufferSize, " ")
lResult = RegQueryValueEx(hCurKey, _
                          strValue, 0&, 0&, _
                          ByVal strBuffer, _
                          lDataBufferSize)

intZeroPos = InStr(strBuffer, Chr$(0))
If intZeroPos > 0 Then
GetSettingString = Left$(strBuffer, _
                         intZeroPos - 1)
Else
GetSettingString = strBuffer
End If

End If

Else
' there is a problem
End If

lRegResult = RegCloseKey(hCurKey)
End Function
Public Sub SaveSettingString(hKey As Long, strPath _
As String, strValue As String, strData As String)
Dim hCurKey As Long
Dim lRegResult As Long

lRegResult = RegCreateKey(hKey, strPath, hCurKey)

lRegResult = RegSetValueEx(hCurKey, strValue, 0, REG_SZ, _
ByVal strData, Len(strData))

If lRegResult <> ERROR_SUCCESS Then
'there is a problem
End If

lRegResult = RegCloseKey(hCurKey)
End Sub

These Registry functions for strings are quite complicated because of the need to initialise buffers. The function to retrieve strings first sets up the default value. This will be used if the specified key is not valid. The first call to RegQueryValueEx determines the data type in the key and the length if it is a string. The second call retrieves the string. Then the string is processed, removing any trailing nulls.

The function to save the string is much simpler. The RegSetValueEx function is called, passing the type as a string, the string data, and the length of the string.

Public Function GetSettingLong( _
             ByVal hKey As Long, _
             ByVal strPath As String, _
             ByVal strValue As String, _
        Optional Default As Long) As Long

Dim lRegResult As Long
Dim lValueType As Long
Dim lBuffer As Long
Dim lDataBufferSize As Long
Dim hCurKey As Long

' Set up default value
If Not IsEmpty(Default) Then
GetSettingLong = Default
Else
GetSettingLong = 0
End If

lRegResult = RegOpenKey(hKey, _
                strPath, hCurKey)
lDataBufferSize = 4 
          ' 4 bytes = 32 bits = long

lRegResult = RegQueryValueEx(hCurKey, _
                    strValue, 0&, _
                    lValueType, lBuffer, _
                    lDataBufferSize)

If lRegResult = ERROR_SUCCESS Then

If lValueType = REG_DWORD Then
GetSettingLong = lBuffer
End If

Else
'there is a problem
End If

lRegResult = RegCloseKey(hCurKey)
End Function

Public Sub SaveSettingLong(ByVal hKey As Long, ByVal _
strPath As String, ByVal strValue As String, ByVal _
lData As Long)
Dim hCurKey As Long
Dim lRegResult As Long

lRegResult = RegCreateKey(hKey, strPath, hCurKey)

lRegResult = RegSetValueEx(hCurKey, strValue, 0&, _
REG_DWORD, lData, 4)

If lRegResult <> ERROR_SUCCESS Then
'there is a problem
End If

lRegResult = RegCloseKey(hCurKey)
End Sub

These two functions are probably the simplest of the three data types. We know the length of data that we want to retrieve so we don't need any extra calls.

Public Function GetSettingLong(ByVal hKey As Long, _
ByVal strPath As String, ByVal strValue As String, _
Optional Default As Long) As Long

Dim lRegResult As Long
Dim lValueType As Long
Dim lBuffer As Long
Dim lDataBufferSize As Long
Dim hCurKey As Long

' Set up default value
If Not IsEmpty(Default) Then
GetSettingLong = Default
Else
GetSettingLong = 0
End If

lRegResult = RegOpenKey(hKey, strPath, hCurKey)
lDataBufferSize = 4 ' 4 bytes = 32 bits = long

lRegResult = RegQueryValueEx(hCurKey, strValue, 0&, _
lValueType, lBuffer, lDataBufferSize)

If lRegResult = ERROR_SUCCESS Then

If lValueType = REG_DWORD Then
GetSettingLong = lBuffer
End If

Else
'there is a problem
End If

lRegResult = RegCloseKey(hCurKey)
End Function

Public Sub SaveSettingLong(ByVal hKey As Long, ByVal _
strPath As String, ByVal strValue As String, ByVal lData As Long)
Dim hCurKey As Long
Dim lRegResult As Long

lRegResult = RegCreateKey(hKey, strPath, hCurKey)

lRegResult = RegSetValueEx(hCurKey, strValue, 0&, _
REG_DWORD, lData, 4)

If lRegResult <> ERROR_SUCCESS Then
'there is a problem
End If

lRegResult = RegCloseKey(hCurKey)
End Sub
Public Function GetSettingByte( _
          ByVal hKey As Long, _
          ByVal strPath As String, _
          ByVal strValueName As String, _
  Optional Default As Variant) As Variant
Dim lValueType As Long
Dim byBuffer() As Byte
Dim lDataBufferSize As Long
Dim lRegResult As Long
Dim hCurKey As Long

If Not IsEmpty(Default) Then
If VarType(Default) = vbArray + vbByte Then
GetSettingByte = Default
Else
GetSettingByte = 0
End If

Else
GetSettingByte = 0
End If

lRegResult = RegOpenKey(hKey, strPath, hCurKey)

lRegResult = RegQueryValueEx(hCurKey, strValueName, 0&, _
lValueType, ByVal 0&, lDataBufferSize)

If lRegResult = ERROR_SUCCESS Then

If lValueType = REG_BINARY Then

ReDim byBuffer(lDataBufferSize - 1) As Byte
lRegResult = RegQueryValueEx(hCurKey, strValueName, 0&, _
lValueType, byBuffer(0), lDataBufferSize)
GetSettingByte = byBuffer

End If

Else
'there is a problem
End If

lRegResult = RegCloseKey(hCurKey)

End Function

Public Sub SaveSettingByte(ByVal hKey As Long, ByVal _
strPath As String, ByVal strValueName As String, byData() As Byte)
Dim lRegResult As Long
Dim hCurKey As Long

lRegResult = RegCreateKey(hKey, strPath, hCurKey)

lRegResult = RegSetValueEx(hCurKey, strValueName, _
0&, REG_BINARY, byData(0), UBound(byData()) + 1)

lRegResult = RegCloseKey(hCurKey)

End Sub

These are probably the hardest of the functions. This is because you cannot pass arrays to API calls, so you must pass the first array element, and the number of elements. The retrieve function, initialises the default value, and then makes a call to the RegQueryValueEx to determine the length of the array. It then initialises an array of bytes as a buffer to accept the data. The RegQueryValueEx is then called again to collect the data.  The save function is easier, as we just pass the first array element, and the number in the array.

This function returns a variant containing a byte array. To use it:

Dim mybytes As Variant
Dim loopy As Integer
mybytes = GetSettingByte(HKEY_CURRENT_USER, _
    "CompanyMyApp", "MyBinaryData")

If VarType(mybytes) = vbArray + vbByte Then
For loopy = 0 To Ubound(mybytes)
Debug.Print mybytes(loopy)
Next
End If

This will print all of the array onto the Debug window.

Conclusion

Well that's it... a whirlwind tour of the Windows Registry API functions. Hopefully you followed that, but if not you can contact me, and there is always the Q and A forum for more general questions. Next week, we will look at how we can control certain aspects of Windows from the Registry, and what the Registry can be used for in your project. We will also look at creating a GetAllSettings function to mimic the VB one. That's all for this week...

Share:
Home
Mobile Site | Full Site
Copyright 2017 © QuinStreet Inc. All Rights Reserved