APIS behind Registry

Know The Apis responsible o handle Windows Registry.

|| APIs Behind Registry ||

 

 

By Nilesh Gore :- ng411002@rediffmail.com

 

 

Here I’m describing the way of editing the Windows Registry by using APIs, This will go through the entire process of handling so that you can create your own Libraries or ActiveX Components to easily handle Windows Registry.

 

The APIs which will be explained are only selected APIs that can edit registry So lets begin to understand the APIs responsible for handling of Windows Registry

 

 

 


1] To open registry key

 

R

 

 

This API function is used to open the key and function is as follows

 

 

Declare Function RegOpenKeyEx Lib "advapi32.dll" Alias "RegOpenKeyExA" (ByVal hKey As Long, ByVal lpSubKey As String, ByVal ulOptions As Long, ByVal samDesired As Long, phkResult As Long) As Long

 

Now lets understand the parameters in the function

 


Hkey :- This is handle to open a key or currently opening key which may

 

be any on of the following.

 

 

HKEY_CLASSES_ROOT

 

HKEY_CURRENT_USER

 

HKEY_LOCAL_MACHINE

 

HKEY_USERS

 

HKEY_CURRENT_CONFIG

 

HKEY_DYN_DATA

 

HKEY_PERFORMANCE_DATA

 

 

LpSubKey :- This is Pointer to a null-terminated string holding the name of the sub key to open. If this parameter is NULL or a pointer is to an empty string, the function will open a new handle to the key identified by the hKey parameter. In this case, the function will not close the handles previously opened.

 

 

Uloption :- This is always reserved and must be Zero.

 

 

SamDesired :- This is used for security access, Specifies an access mask that describes the desired security access for the new key. This parameter can be a combination of the following values:

 

 

KEY_ALL_ACCESS :- This contains the combination of following keys KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS

 

KEY_NOTIFY, KEY_CREATE_SUB_KEY, KEY_CREATE_LINK

 

KEY_SET_VALUE access.

 

 

KEY_CREATE_LINK :- It is used for the permission to create link.

 

KEY_CREATE_SUBKEY :- Name suggests, Its permission to create sub key.

 

 

KEY_ENUMERATE_SUB_KEYS :- permission to enumerate Sub keys.

 

 

KEY_EXECUTE : - Permission to read access.

 

 

KEY_NOTIFY :- permission to change notification.

 

 

KEY_QUERY_VALUE :- Permission to query sub key data.

 

 

KEY_READ :- It uses the combination of KEY_QUERY_VALUE

 

KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY access.

 


 

KEY_SET_VALUE :- It is used to set the Sub key data.

 

 

KEY_WRITE :- As name suggests, It use the combination of KEY_CREATE_SUB_KEY, KEY_SET_VALUE access. These are the values of SamDesired.

 

 

PhkResult :- Actually PHKEY is pointer to HKEY and PhkResult Pointer to a variable that receives a handle to the opened key. When you no longer need the returned handle, call the RegCloseKey( This key is explained in next topic.) function to close it. Note:- This function can not create the specified key if the key does not exist in the registry.

 

2- For Closing Key

 

R

 

 

This function is used to close the key, The function is as follows.

 


 

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

 


 

There is only one parameter used in this function that is

 


HKEY :- which is handle to the opened key to close. Note :- The handle for a specified key must not be used after it has been closed, because it will no longer be valid. Key handles can’t be left open any longer than necessary. The RegCloseKey function does not necessarily write information to the registry before returning; it can take as much as several seconds for the cache to be written to the hard disk.

 


3] To Create key

 

R

 

 

This function is used for creating keys. The function is as follows.

 

 

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

 

 

Now lets go for parameters, These are quite similar to the RegOpenKey

 

But I will explain it as follows.

 

 

Hkey :- This is handle to open a key or currently opening key which may

 

be any on of the following.

 

HKEY_CLASSES_ROOT, HKEY_CURRENT_USER HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CURRENT_CONFIG, HKEY_DYN_DATA

 

HKEY_PERFORMANCE_DATA

 

The key opened or created by this function is a sub key of the key identified by hKey.

 

 

LpSubKey :- It is a Pointer to a null-terminated string specifying the name of a key that this function opens or creates. This key must be a sub key of the key identified by the HKEY parameter. Suppose HKEY is one of the predefined keys, lpSubKey may be NULL. In that case, the handle returned by using PhkResult (explained below) is the same HKEY handle passed in to the function.

 

 


PhkResult :- It Is a Pointer to a variable that receives a handle to the opened or created key.

 

Note :- When the LpSubKey parameter is the address of an empty string, the function opens and then passes back the key identified by the hKey parameter.

 

 


4] To Delete key

 

R

 

 

This function is used to delete the Sub key and all its dependent or other sub keys. In case of windows NT this function will not delete sub key if it Has other sub keys in this situation you have to remove Z to A order means Form lower sub key to the top. The function is as follows.

 

 

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

 

 

So the parameters are

 

 

Hkey :- This is handle to open a key or currently opening key which may

 

be any on of the following.

 

HKEY_CLASSES_ROOT, HKEY_CURRENT_USER HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CURRENT_CONFIG, HKEY_DYN_DATA

 

HKEY_PERFORMANCE_DATA

 

 

LpSubKey :- It is Pointer to a null-terminated string specifying the name of the key to delete. This parameter cannot be NULL and in case of Windows NT It must not have Sub key.

 

 

 


5] To Get Value

 

R

 

 

This function retrieves the type and data of specific value. The function is

 

 

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

 

 

So here the parameters get changed, lets look them

 


 

Hkey :- It is same as above function, Please refer them.

 

 

LpValueName :- It is a Pointer to a null-terminated string holding the name of the value to query. In case this parameter is NULL or an empty string, "", the function retrieves the type and data for the key's unnamed or default value.

 

 

LpReserved :- As name suggests, It is reserved is always Null.

 

 

LpType :- It is a Pointer to the variable that receives the type of data associated with the specified value. The description of values returned with this Parameter are as follows.

 

 

1] RegBinary :- It is a Binary Data

 

 

2] Reg_Dword :- Doword data type having 32 Bit number.

 

 

3] Reg_Dowrd_Little_Endian :- It is a number in Little Endian format, This is 32Bit number which is equvalent to Reg_Doword.In this format, a multi - byte value is stored in memory from the lowest byte (the "little end") to the highest byte. For example, the value 0x123456 is stored as (0x56 0x34 0x12) in little-endian format.

 

Refer Registry Data type for more details.

 

 

4] Reg_Dowrd_Big_Endian :- The number is in Big_Endian format which is a 32bit number. In this format a multi-byte value is stored in memory from the highest byte ( the "big end") to the lowest byte. For example, the value 0x123456 is stored as (0x12 0x34 0x56 ) in big-endian format.

 

 

5] Reg_Expand_Sz :- It is null terminated string which holds unexpected reference to the environments variables (Eg. “ %System%”). This may be Unicode or ANSI String based on whether you we use Unicode or ANSI function.

 

 

6] Reg_Link :- It is a Unicode symbolic Link.

 

 

7] Reg_Multi_Sz :- An array of null terminated string, terminated by two null characters.

 

 

8] Reg_None :- Defined value type is nothing.

 

 

9] Reg_resource_List :- List of Device Driver resources.

 

 

10] Reg_Sz :- It is a null- terminated string. It will be ANSI or Unicode string depending on whether you use the Unicode or ANSI functions.So lets see the next parameter i.e. LpData.

 

 

LpData :- It is a Pointer to a buffer which have the data of value. This parameter can be NULL if the data is not required. Now lets move to the last parameter i.e. LpcbData.

 

 

LpcbData :- It is a Pointer to a variable that specifies the size of the buffer pointed to by the LpData parameter. When the function returns, this variable contains the size of the data copied to LpData. The size of it is in bytes.

 

Suppose the buffer specified by lpData parameter is not large enough to contain the data, the function returns the value ERROR_MORE_DATA, and stores the required buffer size into the variable pointed to by lpcbData.

 

And in case lpData is NULL, and lpcbData is not-NULL then the function returns ERROR_SUCCESS, and stores the size of the data, in bytes, in the variable pointed to by lpcbData.

 

Remember that suppose value data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, and the ANSI version of this function is used either by explicitly calling RegQueryValueExA or by not defining UNICODE , this function converts the stored Unicode string to an ANSI string before copying it to the buffer pointed to by lpData.

 

Now lets take a look at Windows NT, In case of NT (or NT based System)

 

When hKey specifies HKEY _ PERFORMANCE_DATA and the lpData buffer is small, RegQueryValueEx returns ERROR_MORE_DATA but lpcbData does not return the required buffer size. This is because the size of the performance data can change from one call to the next. In such a case you must increase the buffer size and call RegQueryValueEx again passing the updated buffer size in the lpcbData parameter. Repeat this until the function succeeds. You need to maintain a separate variable to keep track of the buffer size, because the value returned by lpcbData is unpredictable.

 

It is amazing but completely normal that when we called the RegQueryValueEx function with hKey set to the HKEY_PERFORMANCE_DATA handle and a value string of a specified object, the returned data structure sometimes has unrequested objects.

 

 

Note :- The LpType parameter can be NULL if the type is not required.

 

The LpcbData parameter can be NULL only if LpData is NULL.

 


 

 

 


6] To Set Value

 

R

 

 

It is used to set data and type of a specified value in a registry key.

 

The function is as follows.

 

 

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

 

 

So lets get close to the Parameters

 

 

Hkey :- It is same as above function, Please refer them

 

 

LpValueName :- It is a Pointer to a string holding name of the value to set. when a value with this name is not already present in the key, the function adds it to the key. Suppose lpValueName is NULL or an empty string, "", the function sets the type and data for the key's unnamed or default value. The next parameter is Reserved it has nothing explain as name suggests all.

 

 

DwType :- This parameter Specifies the type of stuff to be stored as the value of data. This parameter has same values that we have discussed in the function RegQueryValueEx, So refer all those values.

 

 

LpData :- It is a Pointer to a buffer which contains the data to be stored with the specified value name.

 

 

CbData :- This parameter specifies the size of the data pointed to by the lpData parameter. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, cbData must include the size of the terminating null character. The size of data is in bytes.

 

 


7] To Enumerate Values

 

R

 

This function enumerates the values for the specified open registry key. The function copies one indexed value name and data block for the key each time it is called. Some Function parameters are similar to the RegQueryValueEx, Still we will see that. The function is as follows.

 

 

Declare Function RegEnumValue Lib "advapi32.dll" Alias "RegEnumValueA" (ByVal hkey As Long, ByVal dwIndex As Long, ByVal lpValueName As String, lpcbValueName As Long, ByVal lpReserved As Long, lpType As Long, ByVal lpData As String, lpcbData As Long) As Long

 

 

Now lets understand parameters involved on this function

 


 

Hkey :- This is handle to open a key or currently opening key which may

 

be any on of the following.

 

HKEY_CLASSES_ROOT, HKEY_CURRENT_USER HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CURRENT_CONFIG, HKEY_DYN_DATA

 

HKEY_PERFORMANCE_DATA

 

The enumerated values are associated with the key identified by hKey.

 

 

DwIndex :- This parameter Specifies the index of the value to be retrieve. This parameter should be zero for the first call to the RegEnumValue function and then be incremented for subsequent calls. In case values are not ordered, any new value will have an arbitrary index. This means that the function may return values in any order.

 

 

LpValueName :- This parameter is a pointer to a buffer that receives the name of the value, including the terminating null character.

 

 

LpcbValueName :- This Parameter is a Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the LpValueName parameter. This size should include the terminating null character. When the function returns, the variable pointed to by LpcbValueName contains the number of characters stored in the buffer. The count returned does not include the terminating null character.

 


 

LpReserved :- Reserved; must be NULL

 

LpType :- It is a Pointer to the variable that receives the type of data associated with the specified value. The description of values returned with this Parameter are as follows.

 

 

1] RegBinary :- It is a Binary Data

 

 

2] Reg_Dword :- Doword data type having 32 Bit number.

 

 

3] Reg_Dowrd_Little_Endian :- It is a number in Little Endian format, This is 32Bit number which is equvalent to Reg_Doword.In this format, a multi-byte value is stored in memory from the lowest byte (the "little end") to the highest byte. For example, the value 0x123456 is stored as (0x56 0x34 0x12) in little-endian format.

 

Refer Registry Data type for more details.

 

 

4] Reg_Dowrd_Big_Endian :- The number is in Big_Endian format which is a 32bit number. In this format a multi-byte value is stored in memory from the highest byte ( the "big end" ) to the lowest byte. For example, the value 0x123456 is stored as (0x12 0x34 0x56 ) in

 

big-endian format.

 

 

5] Reg_Expand_Sz :- It is null terminated string which holds unexpected reference to the environments variables (Eg. “ %System%”).

 

This may be Unicode or ANSI String based on whether you we use Unicode or ANSI function.

 

 

6] Reg_Link :- It is a Unicode symbolic Link.

 

 

7] Reg_Multi_Sz :- An array of null terminated string, terminated by two null characters.

 

 

8] Reg_None :- Defined value type is nothing.

 

 

9] Reg_resource_List :- List of Device Driver resources.

 

 

10] Reg_Sz :- It is a null-terminated string. It will be ANSI or Unicode string depending on whether you use the Unicode or ANSI functions.

 

So that was the description of values , now, lets see the next parameter i.e. LpData.

 

 

LpData :- It is a Pointer to a buffer which have the data of value. This parameter can be NULL if the data is not required. Now lets move to the last parameter i.e. LpcbData.

 

 

LpcbData :- It is a Pointer to a variable that specifies the size of the buffer pointed to by the LpData parameter. When the function returns, this variable contains the size of the data copied to LpData. The size of it is in bytes. Suppose the buffer specified by lpData parameter is not large enough to contain the data, the function returns the value ERROR_MORE_DATA, and stores the required buffer size into the variable pointed to by lpcbData. And in case lpData is NULL, and lpcbData is not-NULL then the function returns ERROR_SUCCESS, and stores the size of the data, in bytes, in the variable pointed to by lpcbData.

Note :- When you enumerate values, an application initially call the RegEnumValue function with the DwIndex parameter set to zero. The application then increment DwIndex and call the RegEnumValue function until there are no more values until the function returns ERROR_NO_MORE_ITEMS. The application can also set DwIndex to the index of the last value on the first call to the function and decrement the index until the value with index 0(Zero) is enumerated.

 

When you using RegEnumValue, an application must not call any registration functions that might change the key being queried. The key identified by the HKey parameter must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

 

 


8] To Delete Values

 

R

 

 

To delete registry value of specific key we have to use same previous APIs for opening and closing key along with new API that is RegDeleteValueEx. This function Is used for deletimg Registry Values, It has two prameters only one holds handle and other holds value name to be delete. So the function is as follows

 

 

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

 

 

And the parameters are 'hKey and LpValueName

 


HKey : This is handle to open a key or currently opening key which may

 

be any on of the following.

 

HKEY_CLASSES_ROOT, HKEY_CURRENT_USER HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CURRENT_CONFIG, HKEY_DYN_DATA

 

 

LpValueName : It is a Pointer to a null-terminated string holding the name of the value to query. In case this parameter is NULL or an empty string, "", the function retrieves the type and data for the key's unnamed or default value.

 

 

Note that key identified by the hKey parameter must have been opened with KEY_SET_VALUE access (KEY_WRITE access includes KEY_SET_VALUE access

 

 

Summary

 


So far in this chapter we learnt the ways by which registry can be edited with

 

Programming. The API functions that are used in the editing process.

 

The functions used are as follows

 

1] Opening the Key :- RegOpenKeyEx

 

2] Closing the Key :- RegCloseKey

 

3] Creating the Key :- RegCreateKey

 

4] Deleting the Key :- RegDeleteKey

 

5] Reading the values :- RegQueryValueEx

 

6] Writing the values :- RegSetValueEx

 

7] Enumerating value :- RegEnumValue

 

8] Deleting Values :- RegDeleteValue

 

We have studied the parameters of these functions and their value types

 

as well, The little reference to those parameters are as follows.

 

 

*] Hkey :- Handle to the key.

 

*] LpSubKey :- Pointer to Null terminated string.

 

*] Uloption :- Null reserved value.

 

*] SamDesired :- Specifies access mask to desired security access.

 

*] PhkResult :- Pointer to the variable that receives handle.

 

*] LpValueName :- Pointer to a null-terminated string holding name query

 

*]LpcbValueName:- Specifies size of buffer pointed to by LpValueName

 

*] LpReserved :- Reserved Null value.

 

*] LpType :- Pointer to the variable that receives data.

 

*] LpData :- Pointer to buffer which have data value

 

*] LpcbData :- Specifies size of the buffer pointed to by the LpData

 

*] DwType :- The data to be stored with specific value name

 

*] CbData :- specifies the size of the data pointed to by the lpData

 

*] DwIndex :- Specifies the index of the value to be retrieve

 

 

Nilesh Gore.

 

Share this article!

Follow us!

Find more helpful articles: