| Previous | Main | Site Index | Download | Disclaimer | Privacy |


 

 

 

 

WINDOWS REGISTRY: A SUPPLEMENTARY NOTE

 

 

 

 

This supplementary note provides information for functions and structures used in program examples of the Window Registry 1 and Window Registry 2 tutorials.  The information compiled for NT 5 (Windows 2000 and above).

 

The Page Index:

 

Structures:

  1. VALENT

  2. FILETIME

  3. PDH_COUNTER_PATH_ELEMENTS

  4. OSVERSIONINFO

  5. OSVERSIONINFOEX

 

Functions:

  1. RegEnumKeyEx()

  2. RegQueryInfoKey()

  3. RegEnumValue()

  4. PdhMakeCounterPath()

  5. PdhAddCounter()

  6. PdhCollectQueryData()

  7. PdhGetRawCounterValue()

  8. PdhCloseQuery()

  9. PdhOpenQuery()

  10. PdhRemoveCounter()

  11. PdhOpenQueryH()

  12. RegOpenKey()

  13. RegCloseKey()

  14. RegQueryValueEx()

  15. RegCreateKeyEx()

  16. RegSetValueEx()

  17. RegOpenKeyEx()

  18. RegOpenCurrentUser()

  19. RegOpenUserClassesRoot()

  20. RegQueryMultipleValues()

  21. GetVersionEx()

  22. RegDeleteKey()

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Structures

 

VALENT

 

Item

Description

Structure

VALENT.

Info

Contains information about a registry value.  The RegQueryMultipleValues() function uses this structure.

Definition

typedef struct value_ent {

  LPTSTR ve_valuename;

  DWORD ve_valuelen;

  DWORD_PTR ve_valueptr;

  DWORD ve_type;

} VALENT, *PVALENT;

Members

ve_valuename - Pointer to a null-terminated string.  Before calling RegQueryMultipleValues(), set this member to point to the name of a value to retrieve.

ve_valuelen - Size of the data pointed to by ve_valueptr, in bytes.

ve_valueptr - Pointer to the data for the value entry.  This is a pointer to the value's data returned in the lpValueBuf buffer filled in by RegQueryMultipleValues().

ve_type - Type of data pointed to by ve_valueptr.

Header file

<windows.h>

Remark

Declared as Unicode and ANSI structures.

 

Table 1.

 

FILETIME

 

Item

Description

Structure

FILETIME.

Info

A 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).

Definition

typedef struct _FILETIME {

  DWORD dwLowDateTime;

  DWORD dwHighDateTime;

} FILETIME, *PFILETIME;

Members

dwLowDateTime - Low-order part of the file time.

dwHighDateTime - High-order part of the file time.

Header file

<windows.h>

Remark

See below.

 

Table 2.

 

To convert a FILETIME structure into a time that is easy to display to a user, use the FileTimeToSystemTime() function.  It is not recommended that you add and subtract values from the FILETIME structure to obtain relative times.  Instead, you should:

Not all file systems can record creation and last access time and not all file systems record them in the same manner.  For example, on NT FAT, create time has a resolution of 10 milliseconds, write time has a resolution of 2 seconds, and access time has a resolution of 1 day (really, the access date).  On NTFS, access time has a resolution of 1 hour.  Therefore, the GetFileTime() function may not return the same file time information set using the SetFileTime() function.  Furthermore, FAT records times on disk in local time.  However, NTFS records times on disk in UTC.

 

PDH_COUNTER_PATH_ELEMENTS

 

Item

Description

Structure

PDH_COUNTER_PATH_ELEMENTS.

Info

Contains the parsed elements of a fully qualified counter path.  The main purpose of this structure is to provide formatted text to the calling application for display.

Definition

typedef struct _PDH_COUNTER_PATH_ELEMENTS {

  LPTSTR szMachineName;

  LPTSTR szObjectName;

  LPTSTR szInstanceName;

  LPTSTR szParentInstance;

  DWORD dwInstanceIndex;

  LPTSTR szCounterName;

} PDH_COUNTER_PATH_ELEMENTS, *PPDH_COUNTER_PATH_ELEMENTS;

Members

szMachineName - Pointer to a null-terminated string that specifies the computer name.

szObjectName - Pointer to a null-terminated string that specifies the object name.

szInstanceName - Pointer to a null-terminated string that specifies the instance name.

szParentInstance - Pointer to a null-terminated string that specifies the parent instance name.

dwInstanceIndex - Index of duplicate instance names.

szCounterName - Pointer to a null-terminated string that specifies the counter name.

Header file

<pdh.h>

Remark

Declared as Unicode and ANSI structures.

 

Table 3.

 

OSVERSIONINFO

 

Item

Description

Structure

OSVERSIONINFO.

Info

Contains operating system version information.  The information includes major and minor version numbers, a build number, a platform identifier, and descriptive text about the operating system.  This structure is used with the GetVersionEx() function.  To obtain additional version information, see the OSVERSIONINFOEX structure.

Definition

typedef struct _OSVERSIONINFO {

  DWORD dwOSVersionInfoSize;

  DWORD dwMajorVersion;

  DWORD dwMinorVersion;

  DWORD dwBuildNumber;

  DWORD dwPlatformId;

  TCHAR szCSDVersion[128];

} OSVERSIONINFO;

Members

See below.

Header file

<windows.h>

Remark

Declared as Unicode and ANSI structures.  Relying on version information is not the best way to test for a feature.  Instead, refer to the documentation for the feature of interest.  If you must require a particular operating system, be sure to use it as a minimum supported version, rather than design the test for the one operating system.  This way, your detection code will continue to work on future versions of Windows.

 

Table 4.

 

dwOSVersionInfoSize - Size of this data structure, in bytes.  Set this member to sizeof(OSVERSIONINFO) before calling the GetVersionEx function.

dwMajorVersion - Major version number of the operating system.  This member can be one of the following values.

 

Operating System

Meaning

Windows 95

4

Windows 98

4

Windows Me

4

Windows NT 3.51

3

Windows NT 4.0

4

Windows 2000

5

Windows XP

5

Windows Server 2003 family

5

Next Windows version

...

 

Table 5.

 

dwMinorVersion - Minor version number of the operating system.  This member can be one of the following values.

 

Operating System

Meaning

Windows 95

0

Windows 98

10

Windows Me

90

Windows NT 3.51

51

Windows NT 4.0

0

Windows 2000

0

Windows XP

1

Windows Server 2003 family

2

Next Windows version

...

 

Table 6.

 

dwBuildNumber - Build number of the operating system.  For Windows Me/98/95:  The low-order word contains the build number of the operating system.  The high-order word contains the major and minor version numbers.

dwPlatformId - Operating system platform.  This member can be one of the following values.

 

Value

Meaning

VER_PLATFORM_WIN32s

Win32s on Windows 3.1.

VER_PLATFORM_WIN32_WINDOWS

Windows 95, Windows 98, or Windows Me.

VER_PLATFORM_WIN32_NT

Windows NT, Windows 2000, Windows XP, or Windows Server 2003 family.

 

Table 7.

 

szCSDVersion - Pointer to a null-terminated string, such as "Service Pack 3", that indicates the latest Service Pack installed on the system.  If no Service Pack has been installed, the string is empty.  For Windows Me/98/95:  Pointer to a null-terminated string that indicates additional version information.  For example, " C" indicates Windows 95 OSR2 and " A" indicates Windows 98 Second Edition.

 

OSVERSIONINFOEX

 

Item

Description

Structure

OSVERSIONINFOEX.

Info

Contains operating system version information.  The information includes major and minor version numbers, a build number, a platform identifier, and information about product suites and the latest Service Pack installed on the system.  This structure is used with the GetVersionEx() and VerifyVersionInfo() functions.

Definition

typedef struct _OSVERSIONINFOEX {

  DWORD dwOSVersionInfoSize;

  DWORD dwMajorVersion;

  DWORD dwMinorVersion;

  DWORD dwBuildNumber;

  DWORD dwPlatformId;

  TCHAR szCSDVersion[128];

  WORD wServicePackMajor;

  WORD wServicePackMinor;

  WORD wSuiteMask;

  BYTE wProductType;

  BYTE wReserved;

} OSVERSIONINFOEX,  *POSVERSIONINFOEX, *LPOSVERSIONINFOEX;

Members

See below.

Header file

<windows.h>

Remark

Declared as Unicode and ANSI structures.  Relying on version information is not the best way to test for a feature.  Instead, refer to the documentation for the feature of interest.  If you must require a particular operating system, be sure to use it as a minimum supported version, rather than design the test for the one operating system.  This way, your detection code will continue to work on future versions of Windows.  Note that you should not solely rely upon the VER_SUITE_SMALLBUSINESS flag to determine whether Small Business Server has been installed on the system, as both this flag and the VER_SUITE_SMALLBUSINESS_RESTRICTED flag are set when this product suite is installed.  If you upgrade this installation to Windows Server, Standard Edition, the VER_SUITE_SMALLBUSINESS_RESTRICTED flag will be unset however, the VER_SUITE_SMALLBUSINESS flag will remain set.  In this case, this indicates that Small Business Server was once installed on this system.  If this installation is further upgraded to Windows Server, Enterprise Edition, the VER_SUITE_SMALLBUSINESS key will remain set.  To determine whether a Win32-based application is running on WOW64, call the IsWow64Process() function.

 

Table 8.

 

dwOSVersionInfoSize - Size of this data structure, in bytes.  Set this member to sizeof(OSVERSIONINFOEX) before calling the GetVersionEx() or VerifyVersionInfo() function.

dwMajorVersion - Major version number of the operating system.  This member can be one of the following values.

 

Operating System

Meaning

Windows NT 4.0

4

Windows 2000

5

Windows XP

5

Windows Server 2003 family

5

 

Table 9.

 

dwMinorVersion - Minor version number of the operating system.  This member can be one of the following values.

 

Operating System

Meaning

Windows NT 4.0

0

Windows 2000

0

Windows XP

1

Windows Server 2003 family

2

 

Table 10.

 

dwBuildNumber - Build number of the operating system.

dwPlatformId - Operating system platform.  This member can be VER_PLATFORM_WIN32_NT.

szCSDVersion - Pointer to a null-terminated string, such as "Service Pack 3", that indicates the latest Service Pack installed on the system.  If no Service Pack has been installed, the string is empty.

wServicePackMajor - Major version number of the latest Service Pack installed on the system.  For example, for Service Pack 3, the major version number is 3.  If no Service Pack has been installed, the value is zero.

wServicePackMinor - Minor version number of the latest Service Pack installed on the system.  For example, for Service Pack 3, the minor version number is 0.

wSuiteMask - Bit flags that identify the product suites available on the system.  This member can be a combination of the following values.

 

Value

Meaning

VER_SUITE_BACKOFFICE

Microsoft BackOffice components are installed.

VER_SUITE_BLADE

Windows Server 2003, Web Edition is installed.

VER_SUITE_DATACENTER

Windows 2000 Datacenter Server or Windows Server 2003, Datacenter Edition is installed.

VER_SUITE_ENTERPRISE

Windows NT 4.0 Enterprise Edition, Windows 2000 Advanced Server, or Windows Server 2003, Enterprise Edition is installed. Refer to the Remarks section for more information about this bit flag.

VER_SUITE_PERSONAL

Windows XP Home Edition is installed.

VER_SUITE_SMALLBUSINESS

Microsoft Small Business Server was once installed on the system, but may have been upgraded to another version of Windows.

VER_SUITE_SMALLBUSINESS_RESTRICTED

Microsoft Small Business Server is installed with the restrictive client license in force.

VER_SUITE_TERMINAL

Terminal Services is installed.

VER_SUITE_SINGLEUSERTS

Terminal Services is installed, but only one interactive session is supported.

 

Table 11.

 

wProductType - Additional information about the system.  This member can be one of the following values.

 

Value

Meaning

VER_NT_WORKSTATION

The system is running Windows NT 4.0 Workstation, Windows 2000 Professional, Windows XP Home Edition, or Windows XP Professional.

VER_NT_DOMAIN_CONTROLLER

The system is a domain controller.

VER_NT_SERVER

The system is a server.

 

Table 12.

 

wReserved - Reserved for future use.

 

Functions

 

RegEnumKeyEx()

 

Item

Description

Function

RegEnumKeyEx().

Use

Enumerates subkeys of the specified open registry key.  The function retrieves information about one subkey each time it is called.

Prototype

LONG RegEnumKeyEx(

  HKEY hKey,

  DWORD dwIndex,

  LPTSTR lpName,

  LPDWORD lpcName,

  LPDWORD lpReserved,

  LPTSTR lpClass,

  LPDWORD lpcClass,

  PFILETIME lpftLastWriteTime);

Parameters

hKey - [in] Handle to an open key.  The key must have been opened with the KEY_ENUMERATE_SUB_KEYS access right.  This handle is returned by the RegCreateKeyEx() or RegOpenKeyEx() function or it can be one of the following predefined keys:

  1. HKEY_CLASSES_ROOT

  2. HKEY_CURRENT_CONFIG

  3. HKEY_CURRENT_USER

  4. HKEY_LOCAL_MACHINE

  5. HKEY_PERFORMANCE_DATA

  6. HKEY_USERS

 

Windows Me/98/95:  This parameter can also be the following value:  HKEY_DYN_DATA

 

dwIndex - [in] Index of the subkey to retrieve.  This parameter should be zero for the first call to the RegEnumKeyEx() function and then incremented for subsequent calls.  Because subkeys are not ordered, any new subkey will have an arbitrary index.  This means that the function may return subkeys in any order.

lpName - [out] Pointer to a buffer that receives the name of the subkey, including the terminating null character.  The function copies only the name of the subkey, not the full key hierarchy, to the buffer.

lpcName - [in, out] Pointer to a variable that specifies the size of the buffer specified by the lpName parameter, in TCHARs.  This size should include the terminating null character.  When the function returns, the variable pointed to by lpcName contains the number of characters stored in the buffer.  The count returned does not include the terminating null character.

lpReserved - Reserved; must be NULL.

lpClass - [in, out] Pointer to a buffer that receives the null-terminated class string of the enumerated subkey.  This parameter can be NULL.

lpcClass - [in, out] Pointer to a variable that specifies the size of the buffer specified by the lpClass parameter, in TCHARs.  The size should include the terminating null character.  When the function returns, lpcClass contains the number of characters stored in the buffer.  The count returned does not include the terminating null character.  This parameter can be NULL only if lpClass is NULL.

lpftLastWriteTime - [out] Pointer to a variable that receives the time at which the enumerated subkey was last written.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  If the function fails, the return value is a system error code.  If there are no more subkeys available, the function returns ERROR_NO_MORE_ITEMS.

Windows Server 2003, Windows NT/2000/XP:  If the lpName buffer is too small to receive the name of the key, the function returns ERROR_MORE_DATA.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.  To enumerate subkeys, an application should initially call the RegEnumKeyEx() function with the dwIndex parameter set to zero.  The application should then increment the dwIndex parameter and call RegEnumKeyEx() until there are no more subkeys (meaning the function returns ERROR_NO_MORE_ITEMS).  The application can also set dwIndex to the index of the last subkey on the first call to the function and decrement the index until the subkey with the index 0 is enumerated.  To retrieve the index of the last subkey, use the RegQueryInfoKey() function.  While an application is using the RegEnumKeyEx() function, it should not make calls to any registration functions that might change the key being enumerated.

 

Table 13.

 

RegQueryInfoKey()

 

Item

Description

Function

RegQueryInfoKey().

Use

Retrieves information about the specified registry key.

Prototype

LONG RegQueryInfoKey(

  HKEY hKey,

  LPTSTR lpClass,

  LPDWORD lpcClass,

  LPDWORD lpReserved,

  LPDWORD lpcSubKeys,

  LPDWORD lpcMaxSubKeyLen,

  LPDWORD lpcMaxClassLen,

  LPDWORD lpcValues,

  LPDWORD lpcMaxValueNameLen,

  LPDWORD lpcMaxValueLen,

  LPDWORD lpcbSecurityDescriptor,

  PFILETIME lpftLastWriteTime);

Parameters

hKey - [in] Handle to an open key.  The key must have been opened with the KEY_QUERY_VALUE access right.  This handle is returned by the RegCreateKeyEx() or RegOpenKeyEx() function or it can be one of the following predefined keys:

  1.      HKEY_CLASSES_ROOT

  2.      HKEY_CURRENT_CONFIG

  3.      HKEY_CURRENT_USER

  4.      HKEY_LOCAL_MACHINE

  5.      HKEY_PERFORMANCE_DATA

  6.      HKEY_USERS

 

Windows Me/98/95:  This parameter can also be the following key: HKEY_DYN_DATA

 

lpClass - [out] Pointer to a buffer that receives the null-terminated class string of the key.  This parameter may be ignored.  This parameter can be NULL.

lpcClass - [in, out] Pointer to a variable that specifies the size of the buffer pointed to by the lpClass parameter, in TCHARs.  This size should include the terminating null character.  When the function returns, this variable contains the size of the class string stored in the buffer.  The count returned does not include the terminating null character.  If the buffer is not big enough, the function returns ERROR_MORE_DATA, and the variable contains the size of the string, in characters, without counting the null character. If lpClass is NULL, lpcClass can be NULL.  Windows NT/2000/XP:  If the lpClass parameter is a valid address, but the lpcClass parameter is not (for example, it is NULL), the function returns ERROR_INVALID_PARAMETER. Windows Me/98/95:  If the lpClass parameter is a valid address, but the lpcClass parameter is not (for example, it is NULL), the function returns ERROR_SUCCESS instead of ERROR_INVALID_PARAMETER. To ensure compatibility with other platforms, verify that lpcClass is valid before calling the function.

lpReserved - Reserved; must be NULL.

lpcSubKeys - [out] Pointer to a variable that receives the number of subkeys contained by the specified key.  This parameter can be NULL.

lpcMaxSubKeyLen - [out] Pointer to a variable that receives the size of the key's subkey with the longest name, in TCHARs.  This parameter can be NULL. Windows NT/2000/XP:  The size does not include the terminating null character. Windows Me/98/95:  The size includes the terminating null character.

lpcMaxClassLen - [out] Pointer to a variable that receives the size of the longest string specifying a subkey class, in TCHARs.  The count returned does not include the terminating null character.  This parameter can be NULL.

lpcValues - [out] Pointer to a variable that receives the number of values associated with the key.  This parameter can be NULL.

lpcMaxValueNameLen - [out] Pointer to a variable that receives the size of the key's longest value name, in TCHARs.  The size does not include the terminating null character.  This parameter can be NULL.

lpcMaxValueLen - [out] Pointer to a variable that receives the size of the longest data component among the key's values, in bytes.  This parameter can be NULL.

lpcbSecurityDescriptor - [out] Pointer to a variable that receives the size of the key's security descriptor, in bytes.  This parameter can be NULL.

lpftLastWriteTime - [out] Pointer to a FILETIME structure that receives the last write time. This parameter can be NULL. Windows NT/2000/XP:  The function sets the members of the FILETIME structure to indicate the last time that the key or any of its value entries was modified. Windows Me/98/95:  The function sets the members of the FILETIME structure to zero.  This is because the system does not keep track of registry key last write time information.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  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.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.

 

Table 14.

 

RegEnumValue()

 

Item

Description

Function

RegEnumValue().

Use

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.

Prototype

LONG RegEnumValue(

  HKEY hKey,

  DWORD dwIndex,

  LPTSTR lpValueName,

  LPDWORD lpcValueName,

  LPDWORD lpReserved,

  LPDWORD lpType,

  LPBYTE lpData,

  LPDWORD lpcbData);

Parameters

hKey

[in] Handle to an open key.  The key must have been opened with the KEY_QUERY_VALUE access right.  This handle is returned by the RegCreateKeyEx() or RegOpenKeyEx() function or it can be one of the following predefined keys:

  1. HKEY_CLASSES_ROOT

  2. HKEY_CURRENT_CONFIG

  3. HKEY_CURRENT_USER

  4. HKEY_LOCAL_MACHINE

  5. HKEY_PERFORMANCE_DATA

  6. HKEY_USERS

 

Windows Me/98/95:  This parameter can also be the following value: HKEY_DYN_DATA.

dwIndex

[in] Index of the value to be retrieved.  This parameter should be zero for the first call to the RegEnumValue() function and then be incremented for subsequent calls.  Because values are not ordered, any new value will have an arbitrary index.  This means that the function may return values in any order.

lpValueName - [out] Pointer to a buffer that receives the name of the value, including the terminating null character.

lpcValueName - [in, out] Pointer to a variable that specifies the size of the buffer pointed to by the lpValueName parameter, in TCHARs.  This size should include the terminating null character.  When the function returns, the variable pointed to by lpcValueName 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 - [out] Pointer to a variable that receives a code indicating the type of data stored in the specified value.  The lpType parameter can be NULL if the type code is not required.

lpData - [out] Pointer to a buffer that receives the data for the value entry.  This parameter can be NULL if the data is not required.  If lpData is NULL and lpcbData is non-NULL, the function stores the size of the data, in bytes, in the variable pointed to by lpcbData.  This enables an application to determine the best way to allocate a buffer for the data.

lpcbData - [in, out] Pointer to a variable that specifies the size of the buffer pointed to by the lpData parameter, in bytes.  When the function returns, the variable pointed to by the lpcbData parameter contains the number of bytes stored in the buffer.  This parameter can be NULL only if lpData is NULL.  If the buffer specified by lpData is not large enough to hold the data, the function returns ERROR_MORE_DATA and stores the required buffer size in the variable pointed to by lpcbData.  In this case, the contents of lpData are undefined.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  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.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.  To enumerate values, an application should initially call the RegEnumValue() function with the dwIndex parameter set to zero.  The application should then increment dwIndex and calls 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 is enumerated.  To retrieve the index of the last value, use the RegQueryInfoKey() function.  While using RegEnumValue(), an application should not call any registry functions that might change the key being queried.  To determine the maximum size of the name and data buffers, use the RegQueryInfoKey() function.

 

Table 15.

 

PdhMakeCounterPath()

 

Item

Description

Function

PdhMakeCounterPath().

Use

Creates a full counter path using the members specified in the structure passed in the parameter list.

Prototype

PDH_STATUS PdhMakeCounterPath(

  PDH_COUNTER_PATH_ELEMENTS* pCounterPathElements,

  LPTSTR szFullPathBuffer,

  LPDWORD pcchBufferSize,

  DWORD dwFlags);

Parameters

See below.

Return value

See below.

Include file

<pdh.h>

Remark

Implemented as Unicode and ANSI versions.  The maximum length of a counter path is PDH_MAX_COUNTER_PATH, or 2,048 characters. PDH_MAX_COUNTER_PATH is defined in pdh.h.

 

Table 16.

 

pCounterPathElements - [in] Pointer to a PDH_COUNTER_PATH_ELEMENTS structure that contains the individual members those are to make up the path.  The following table indicates which members are required and which are optional.

 

 

Member

Meaning

szMachineName

optional

szObjectName

required

szInstanceName

optional

szParentInstance

optional

dwInstanceIndex

optional ((DWORD)–1 if no index)

szCounterName

required

 

Table 17.

 

If a required member is not present, then no path string will be constructed.  If the szMachineName member is NULL, then no computer name will be included in the path (a generic path will be created).  If the instance name argument is NULL, then no instance reference will be inserted into the path string and the szParentInstance and the dwInstanceIndex members will be ignored.

szFullPathBuffer - [out] Pointer to a buffer that receives a null-terminated string that specifies the full path.

pcchBufferSize - [in, out] Pointer to a variable that specifies the size of the available buffer, in TCHARs.  If the function succeeds, this parameter receives the size of the buffer used.  If the buffer is too small, the function fails with PDH_MORE_DATA and this parameter receives the required buffer size.  If the buffer size is zero on input, no data is returned in the buffer, and the size of the buffer required is returned in pcchBufferSize.  The size returned includes the terminating null character.

dwFlags - [in] Format of the input and output counter values.  This parameter can be one of the following values.

 

Value

Meaning

PDH_PATH_WBEM_RESULT

The path is returned as in WMI format. Windows NT 4.0:  This value is not supported.

PDH_PATH_WBEM_INPUT

The input is assumed to be in WMI format. Windows NT 4.0:  This value is not supported.

0

The path is returned as a list of registry path items.

 

Table 18.

 

Return Values

 

If the function succeeds, it returns ERROR_SUCCESS.  If the function fails, the return value is a system error code or a PDH error code.  The following are possible values.

 

Return code

Description

PDH_MORE_DATA

The buffer is not large enough to contain any data.

PDH_INVALID_ARGUMENT

An argument is not correct or is incorrectly formatted.

 

Table 19.

 

PdhAddCounter()

 

Item

Description

Function

PdhAddCounter().

Use

Creates the specified counter and adds it to the specified query.

Prototype

PDH_STATUS PdhAddCounter(

  PDH_HQUERY hQuery,

  LPCTSTR szFullCounterPath,

  DWORD_PTR dwUserData,

  PDH_HCOUNTER* phCounter);

Parameters

hQuery - [in] Handle to the query to which the new counter is to be added.  This handle is returned by the PdhOpenQuery() function.

szFullCounterPath - [in] Pointer to the fully-qualified and resolved path of the counter to create.  This path can contain wildcard characters.

dwUserData - [in] User-defined value (typically, a pointer or index to the user's counter structure).

phCounter - [out] Pointer to a variable that receives a handle to the created counter.

Return value

See below.

Include file

<pdh.h>

Remark

Implemented as Unicode and ANSI versions.  If a wildcard character is specified in the szFullCounterPath parameter, all counter names matching the wildcard character are added to the query.

If a counter instance is specified that does not yet exist, PdhAddCounter does not report an error condition.  Instead, it returns ERROR_SUCCESS.  The reason for this behavior is that it is not known if a nonexistent counter instance has been specified or one that will exist but has not yet been created.

To remove the counter from the query, use the PdhRemoveCounter() function.  The maximum length of a counter path is PDH_MAX_COUNTER_PATH, or 2,048 characters.  PDH_MAX_COUNTER_PATH is defined in pdh.h.

 

Table 20.

 

Return Values

 

If the function succeeds, it returns ERROR_SUCCESS, creates a new counter, and returns a handle to the counter in the buffer pointed to by phCounter.  If the function fails, the return value is a system error code or a PDH error code. The following are possible values.

 

Return code

Description

PDH_CSTATUS_BAD_COUNTERNAME

The counter name path string could not be parsed or interpreted.

PDH_CSTATUS_NO_COUNTER

The specified counter was not found.

PDH_CSTATUS_NO_COUNTERNAME

An empty counter name path string was passed in.

PDH_CSTATUS_NO_MACHINE

A computer entry could not be created.

PDH_CSTATUS_NO_OBJECT

The specified object could not be found.

PDH_FUNCTION_NOT_FOUND

The calculation function for this counter could not be determined.

PDH_INVALID_ARGUMENT

One or more arguments are invalid.

PDH_INVALID_HANDLE

The query handle is not valid.

PDH_MEMORY_ALLOCATION_FAILURE

A memory buffer could not be allocated.

 

Table 21.

 

PdhCollectQueryData()

 

Item

Description

Function

PdhCollectQueryData().

Use

Collects the current raw data value for all counters in the specified query and updates the status code of each counter.

Prototype

void PDH_STATUS PdhCollectQuery(PDH_HQUERY hQuery);

Parameters

hQuery - [in] Handle to the query from which data is to be collected.  This handle is returned by the PdhOpenQuery() function.

Return value

If the function succeeds, it returns ERROR_SUCCESS.  Otherwise, the function returns a system error code or a PDH error code.  The following are possible values.

  1. PDH_INVALID_HANDLE - The query handle is not valid.

  2. PDH_NO_DATA - The query does not currently have any counters.

Include file

<pdh.h>

Remark

When PdhCollectQueryData() is called for data from one counter instance only, and the counter instance does not exist, the PDH_NO_DATA or ERROR_SUCCESS error is reported.  However, if data from more than one counter is queried, PdhCollectQueryData() may still return ERROR_SUCCESS even if one of the counter instances does not yet exist.  This is because it is not known if a nonexistent counter instance has been specified, or one that will exist but has not yet been created has been specified.  In this case, call PdhGetRawCounterValue() and PdhGetFormattedCounterValue() for each of the counter instances of interest to determine whether they exist.

 

Table 22.

 

PdhGetRawCounterValue()

 

Item

Description

Function

PdhGetRawCounterValue().

Use

Returns the current raw value of the counter.

Prototype

PDH_STATUS PdhGetRawCounterValue(

  PDH_HCOUNTER hCounter,

  LPDWORD lpdwType,

  PPDH_RAW_COUNTER pValue);

Parameters

hCounter - [in] Handle to the counter from which to retrieve the current raw value.  This handle is returned by the PdhAddCounter() function, which adds the counter to a query.

lpdwType - [out] Pointer to a variable that receives the counter type.  For a list of values, see the CounterType member of the PERF_COUNTER_DEFINITION structure.  This parameter is optional.

pValue - [out] Pointer to a PDH_RAW_COUNTER structure that receives the counter value.

Return value

If the function succeeds, it returns ERROR_SUCCESS.  If the function fails, the return value is a system error code or a PDH error code.  The following are possible values.

  1. PDH_INVALID_ARGUMENT - An argument is not correct or is incorrectly formatted.

  2. PDH_INVALID_HANDLE - The counter handle is not valid.

Include file

<pdh.h>

Remark

The data for the counter is locked (protected) for the duration of the call to PdhGetRawCounterValue() to prevent any changes during processing of the call.  Obtaining the value of rate counters such as Page faults/sec requires that PdhCollectQueryData() be called twice, with a specific time interval between the two calls, before calling PdhGetRawCounterValue(). Call sleep() to implement the waiting period between the two calls to PdhCollectQueryData(). If PdhGetRawCounterValue() determines that the specified counter instance does not exist, it will return ERROR_SUCCESS and the PDH_STATUS_NO_INSTANCE error is reported in the CStatus member of the PDH_RAW_COUNTER structure passed in the pValue parameter.

 

Table 23.

 

PdhCloseQuery()

 

Item

Description

Function

PdhCloseQuery().

Use

Closes all counters contained in the specified query, closes all handles related to the query, and frees all memory associated with the query.

Prototype

void PDH_STATUS PdhCloseQuery(PDH_HQUERY hQuery);

Parameters

hQuery - [in] Handle to the query to be closed and deleted.  This handle is returned by the PdhOpenQuery() function.

Return value

If the function succeeds, it returns ERROR_SUCCESS and closes and deletes the query.  Otherwise, the function returns a system error code or a PDH error code.  The following is a possible value.

PDH_INVALID_HANDLE - The query handle is not valid.

Include file

<pdh.h>

Remark

The handles added to this query should be deleted or zeroed and not used after the query they belong to is deleted.

 

Table 24.

 

PdhOpenQuery()

 

Item

Description

Function

PdhOpenQuery().

Use

Creates and initializes a unique query structure that is used to manage the collection of performance data.  To use handles to data sources, use the PdhOpenQueryH() function.

Prototype

PDH_STATUS PdhOpenQuery( LPCTSTR szDataSource, DWORD_PTR dwUserData, PDH_HQUERY* phQuery);

Parameters

szDataSource - [in] Pointer to a null-terminated string that specifies the name of the log file from which performance data is to be taken.  If this parameter is NULL, performance data will be collected from a real-time data source. Windows NT 4.0:  Reserved. Must be NULL.

dwUserData - [in] User-defined value that is to be associated with this query.

phQuery - [out] Pointer to a buffer that receives a handle to the query that is created.

Return value

If the function succeeds, it returns ERROR_SUCCESS, creates a new query, and returns a handle to the query in the buffer pointed to by phQuery.  If the function fails, the return value is a system error code or a PDH error code.  The following are possible values.

 

PDH_INVALID_ARGUMENT - One or more arguments are invalid.

PDH_MEMORY_ALLOCATION_FAILURE - A memory buffer could not be allocated.

Include file

<pdh.h>

Remark

You can call PdhGetCounterInfo() to retrieve the user data value set by dwUserData.

 

Table 25.

 

PdhRemoveCounter()

 

Item

Description

Function

PdhRemoveCounter().

Use

Removes a counter from a query.

Prototype

void PDH_STATUS PdhRemoveCounter(PDH_HCOUNTER hCounter);

Parameters

hCounter - [in] Handle to the counter to be removed from its query.  This handle is returned by the PdhAddCounter() function, which adds the counter to a query.

Return value

If the function succeeds, it returns ERROR_SUCCESS and removes the specified counter from its query.  If the function fails, the return value is a system error code or a PDH error code.  The following is a possible value.

PDH_INVALID_HANDLE - The counter handle is not valid.

Include file

<pdh.h>

Remark

After you remove a counter, any references to it using a handle passed in hCounter will be invalid and will return an error.

 

Table 26.

 

PdhOpenQueryH()

 

Item

Description

Function

PdhOpenQueryH().

Use

Creates and initializes a unique query structure that is used to manage the collection of performance data.  This function is identical to PdhOpenQuery(), except that it supports the use of handles to data sources.

Prototype

PDH_STATUS PdhOpenQueryH( PDH_HLOG hDataSource, DWORD_PTR dwUserData, PDH_HQUERY* phQuery);

Parameters

hDataSource - [in] Handle to a data source returned by the PdhBindInputDataSource() function.  The handle can represent a counter log as an input data source, or it can be one of the following values.

  1. H_REALTIME_DATASOURCE - Real-time data source.

  2. H_WBEM_DATASOURCE - WBEM data source.

 

dwUserData - [in] User-defined value to be associated with this query.

phQuery - [out] Pointer to a buffer that receives a handle to the query that is created.

Return value

If the function succeeds, it returns ERROR_SUCCESS, creates a new query, and returns a handle to the query in the buffer pointed to by phQuery.  If the function fails, the return value is a system error code or a PDH error code.  The following are possible values.

  1. PDH_INVALID_ARGUMENT - One or more arguments are invalid.

  2. PDH_MEMORY_ALLOCATION_FAILURE - A memory buffer could not be allocated.

Include file

<pdh.h>

Remark

You can call PdhGetCounterInfo() to retrieve the user data value set by dwUserData.

 

Table 27.

 

RegOpenKey()

 

Item

Description

Function

RegOpenKey().

Use

Opens the specified registry key.  This function is provided only for compatibility with 16-bit versions of Windows.  Applications should use the RegOpenKeyEx() function.

Prototype

LONG RegOpenKey( HKEY hKey, LPCTSTR lpSubKey, PHKEY phkResult);

Parameters

hKey - [in] Handle to an open key.  This handle is returned by the RegCreateKeyEx() or RegOpenKeyEx() function or it can be one of the following predefined keys:

  1. HKEY_CLASSES_ROOT

  2. HKEY_CURRENT_CONFIG

  3. HKEY_CURRENT_USER

  4. HKEY_LOCAL_MACHINE

  5. HKEY_USERS

 

Windows Me/98/95:  This parameter can also be the following key:  HKEY_DYN_DATA

lpSubKey - [in] Pointer to a null-terminated string containing the name of the key to open.  This key must be a subkey of the key identified by the hKey parameter.  If this parameter is NULL or a pointer to an empty string, the function returns the same handle that was passed in.

phkResult - [out] Pointer to a variable that receives a handle to the opened key.  When you no longer need the returned handle, call the RegCloseKey() function to close it.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  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.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.  The RegOpenKey() function uses the default security access mask to open a key.  If opening the key requires a different access right, the function fails, returning ERROR_ACCESS_DENIED. An application should use the RegOpenKeyEx() function to specify an access mask in this situation.  RegOpenKey() does not create the specified key if the key does not exist in the database.  If your service or application impersonates different users, do not use this function with HKEY_CURRENT_USER. Instead, call the RegOpenCurrentUser() function.

 

Table 28.

 

RegCloseKey()

 

Item

Description

Function

RegCloseKey().

Use

Releases a handle to the specified registry key.

Prototype

LONG RegCloseKey(HKEY hKey);

Parameters

hKey - [in] Handle to the open key to be closed.  The handle must have been opened by the RegCreateKeyEx(), RegOpenKeyEx(), or RegConnectRegistry() function.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  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.

Include file

<windows.h>

Remark

The handle for a specified key should not be used after it has been closed, because it will no longer be valid.  Key handles should not 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 flushed to the hard disk.  If an application must explicitly write registry information to the hard disk, it can use the RegFlushKey() function.  However RegFlushKey() uses many system resources and should be called only when necessary.

 

Table 29.

 

RegQueryValueEx()

 

Item

Description

Function

RegQueryValueEx().

Use

To retrieve the type and data for a specified value name associated with an open registry key.

Prototype

LONG RegQueryValueEx( HKEY hKey, LPCTSTR lpValueName,   LPDWORD lpReserved,

  LPDWORD lpType, LPBYTE lpData, LPDWORD lpcbData);

Parameters

hKey - [in] Handle to an open key.  The key must have been opened with the KEY_QUERY_VALUE access right.  This handle is returned by the RegCreateKeyEx() or RegOpenKeyEx() function or it can be one of the following predefined keys:

  1. HKEY_CLASSES_ROOT

  2. HKEY_CURRENT_CONFIG

  3. HKEY_CURRENT_USER

  4. HKEY_LOCAL_MACHINE

  5. HKEY_PERFORMANCE_DATA

  6. HKEY_PERFORMANCE_NLSTEXT

  7. HKEY_PERFORMANCE_TEXT

  8. HKEY_USERS

 

Windows Me/98/95:  This parameter can also be the following key: HKEY_DYN_DATA

 

lpValueName - [in] Pointer to a null-terminated string containing the name of the value to query.  If lpValueName is NULL or an empty string, "", the function retrieves the type and data for the key's unnamed or default value, if any.  Keys do not automatically have an unnamed or default value.  Unnamed values can be of any type.

lpReserved - Reserved; must be NULL.

lpType - [out] Pointer to a variable that receives a code indicating the type of data stored in the specified value.  The lpType parameter can be NULL if the type code is not required.

lpData - [out] Pointer to a buffer that receives the value's data.  This parameter can be NULL if the data is not required.  If the data is a string, the function checks for a terminating null character.  If one is not found, the string is stored with a null terminator if the buffer is large enough to accommodate the extra character.

lpcbData - [in, out] Pointer to a variable that specifies the size of the buffer pointed to by the lpData parameter, in bytes.  When the function returns, this variable contains the size of the data copied to lpData.

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, this size includes any terminating null character or characters.  The lpcbData parameter can be NULL only if lpData is NULL.  If the buffer specified by lpData parameter is not large enough to hold the data, the function returns ERROR_MORE_DATA and stores the required buffer size in the variable pointed to by lpcbData.  In this case, the contents of the lpData buffer are undefined.  If lpData is NULL, and lpcbData is non-NULL, the function returns ERROR_SUCCESS and stores the size of the data, in bytes, in the variable pointed to by lpcbData.  This enables an application to determine the best way to allocate a buffer for the value's data.

If hKey specifies HKEY_PERFORMANCE_DATA and the lpData buffer is not large enough to contain all of the returned data, RegQueryValueEx() returns ERROR_MORE_DATA and the value returned through the lpcbData parameter is undefined.  This is because the size of the performance data can change from one call to the next.  In this 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.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  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.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.

 

Table 30.

 

An application typically calls RegEnumValue() to determine the value names and then RegQueryValueEx() to retrieve the data for the names.  Ensure that you reinitialize the value pointed to by the lpcbData parameter each time you call this function.  This is very important when you call this function in a loop, as in the following code example:

DWORD lpcbData;

BYTE Data[lpcbData];

 

for(;;)

{

   lpcbData = 10;            // reinitialize every time

   ret = RegQueryValueExA(..., Data, lpcbData);

   if(ret != ERROR_SUCCESS)  // handle error

}

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, the string may not have been stored with the proper null-terminating characters.  Applications should ensure that the string is properly terminated before using it, otherwise, the application may fail by overwriting a buffer.  If the 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 RegQueryValueEx() or by not defining UNICODE before including the windows.h file), this function converts the stored Unicode string to an ANSI string before copying it to the buffer pointed to by lpData. When calling 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 un-requested objects.  Don't be surprised; this is normal behavior.  When calling the RegQueryValueEx() function, you should always expect to walk the returned data structure to look for the requested object.

 

RegCreateKeyEx()

 

Item

Description

Function

RegCreateKeyEx().

Use

To create the specified registry key.  If the key already exists, the function opens it.

Prototype

LONG RegCreateKeyEx( HKEY hKey, LPCTSTR lpSubKey, DWORD Reserved, LPTSTR lpClass, DWORD dwOptions, REGSAM samDesired, LPSECURITY_ATTRIBUTES lpSecurityAttributes, PHKEY phkResult, LPDWORD lpdwDisposition);

Parameters

See below.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  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.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.  The key that the RegCreateKeyEx() function creates has no values.  An application can use the RegSetValueEx() function to set key values.   An application cannot create a key that is a direct child of HKEY_USERS or HKEY_LOCAL_MACHINE.  An application can create subkeys in lower levels of the HKEY_USERS or HKEY_LOCAL_MACHINE trees.  If your service or application impersonates different users, do not use this function with HKEY_CURRENT_USER.  Instead, call the RegOpenCurrentUser() function.

 

Table 31.

 

hKey - [in] Handle to an open key.  The calling process must have KEY_CREATE_SUB_KEY access to the key.  This handle is returned by the RegCreateKeyEx() or RegOpenKeyEx() function or it can be one of the following predefined keys:

  1. HKEY_CLASSES_ROOT

  2. HKEY_CURRENT_CONFIG

  3. HKEY_CURRENT_USER

  4. HKEY_LOCAL_MACHINE

  5. HKEY_USERS

 

For Windows Me/98/95:  This parameter can also be the following key:  HKEY_DYN_DATA

lpSubKey - [in] Pointer to a null-terminated string specifying the name of a subkey that this function opens or creates.  The subkey specified must be a subkey of the key identified by the hKey parameter.  This parameter cannot be NULL.  The subkey name specified by lpSubKey must not begin with the backslash character ('\').  If it does, ERROR_BAD_PATHNAME is returned.

Reserved - Reserved; must be zero.

lpClass - [in] Pointer to a null-terminated string that specifies the class (object type) of this key.  This parameter may be ignored.  This parameter can be NULL.  This parameter is used for both local and remote registry keys.

dwOptions - [in] This parameter can be one of the following values.

 

Value

Meaning

REG_OPTION_NON_VOLATILE

This key is not volatile; this is the default.  The information is stored in a file and is preserved when the system is restarted.  The RegSaveKey() function saves keys that are not volatile.

REG_OPTION_VOLATILE

All keys created by the function are volatile.  The information is stored in memory and is not preserved when the corresponding registry hive is unloaded.  For HKEY_LOCAL_MACHINE, this occurs when the system is shut down.  For registry keys loaded by the RegLoadKey() function, this occurs when the corresponding RegUnLoadKey() is performed.  The RegSaveKey() function does not save volatile keys.  This flag is ignored for keys that already exist.

REG_OPTION_BACKUP_RESTORE

If this flag is set, the function ignores the samDesired parameter and attempts to open the key with the access required to backup or restore the key.  If the calling thread has the SE_BACKUP_NAME privilege enabled, the key is opened with the ACCESS_SYSTEM_SECURITY and KEY_READ access rights.  If the calling thread has the SE_RESTORE_NAME privilege enabled, the key is opened with the ACCESS_SYSTEM_SECURITY and KEY_WRITE access rights.  If both privileges are enabled, the key has the combined access rights for both privileges.

 

Table 32.

 

samDesired - [in] Access mask that specifies the access rights for the key.

lpSecurityAttributes - [in] Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes.  If lpSecurityAttributes is NULL, the handle cannot be inherited.  The lpSecurityDescriptor member of the structure specifies a security descriptor for the new key.  If lpSecurityAttributes is NULL, the key gets a default security descriptor.  The ACLs in a default security descriptor for a key are inherited from its direct parent key.

phkResult - [out] Pointer to a variable that receives a handle to the opened or created key.  When you no longer need the returned handle, call the RegCloseKey() function to close it.

lpdwDisposition - [out] Pointer to a variable that receives one of the following disposition values.

 

Value

Meaning

REG_CREATED_NEW_KEY

The key did not exist and was created.

REG_OPENED_EXISTING_KEY

The key existed and was simply opened without being changed.

 

Table 33.

 

If lpdwDisposition is NULL, no disposition information is returned.

 

RegSetValueEx()

 

Item

Description

Function

RegSetValueEx().

Use

To set the data and type of a specified value under a registry key.

Prototype

LONG RegSetValueEx( HKEY hKey, LPCTSTR lpValueName, DWORD Reserved, DWORD dwType, const BYTE* lpData, DWORD cbData);

Parameters

hKey - [in] Handle to an open key.  The key must have been opened with the KEY_SET_VALUE access right.  This handle is returned by the RegCreateKeyEx() or RegOpenKeyEx() function or it can be one of the following predefined keys:

  1. HKEY_CLASSES_ROOT

  2. HKEY_CURRENT_CONFIG

  3. HKEY_CURRENT_USER

  4. HKEY_LOCAL_MACHINE

  5. HKEY_PERFORMANCE_DATA

  6. HKEY_USERS

 

Windows Me/98/95:  This parameter can also be the following value: HKEY_DYN_DATA

 

lpValueName - [in] Pointer to a string containing the name of the value to set.  If a value with this name is not already present in the key, the function adds it to the key.  If lpValueName is NULL or an empty string, "", the function sets the type and data for the key's unnamed or default value.  Windows Server 2003, Windows XP/2000/NT:  Registry keys do not have default values, but they can have one unnamed value, which can be of any type.

Reserved - Reserved; must be zero.

dwType - [in] Type of data pointed to by the lpData parameter.

lpData - [in] Pointer to a buffer containing the data to be stored with the specified value name.  For string-based types, such as REG_SZ, the string must be null-terminated.  With the REG_MULTI_SZ data type, the string must be terminated with two null characters.  If the last character is not a null-terminating character, the function examines the next character to determine whether it is a null-terminating character and increments the length to accommodate the additional character if necessary.

 

cbData - [in] Size of the information pointed to by the lpData parameter, in bytes.  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 or characters.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  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.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.  Value sizes are limited by available memory.  Long values (more than 2048 bytes) should be stored as files with the file names stored in the registry.  This helps the registry perform efficiently.  Application elements such as icons, bitmaps, and executable files should be stored as files and not be placed in the registry.  If dwType is the REG_SZ, REG_MULTI_SZ, or REG_EXPAND_SZ type and the ANSI version of this function is used (either by explicitly calling RegSetValueExA() or by not defining UNICODE before including the windows.h file), the data pointed to by the lpData parameter must be an ANSI character string.  The string is converted to Unicode before it is stored in the registry.

 

Table 34.

 

RegOpenKeyEx()

 

Item

Description

Function

RegOpenKeyEx().

Use

To open the specified registry key.

Prototype

LONG RegOpenKeyEx( HKEY hKey, LPCTSTR lpSubKey, DWORD ulOptions, REGSAM samDesired, PHKEY phkResult);

Parameters

hKey - [in] Handle to an open key.  This handle is returned by the RegCreateKeyEx() or RegOpenKeyEx() function or it can be one of the following predefined keys:

  1. HKEY_CLASSES_ROOT

  2. HKEY_CURRENT_USER

  3. HKEY_LOCAL_MACHINE

  4. HKEY_USERS

 

Windows Me/98/95:  This parameter can also be the following key: HKEY_DYN_DATA

 

lpSubKey - [in] Pointer to a null-terminated string containing the name of the subkey to open.  If this parameter is NULL or a pointer 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.

ulOptions - Reserved; must be zero.

samDesired - [in] Access mask that specifies the desired access rights to the key.  The function fails if the security descriptor of the key does not permit the requested access for the calling process.

phkResult - [out] Pointer to a variable that receives a handle to the opened key.  When you no longer need the returned handle, call the RegCloseKey() function to close it.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  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.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.  Unlike the RegCreateKeyEx() function, the RegOpenKeyEx() function does not create the specified key if the key does not exist in the registry.  If your service or application impersonates different users, do not use this function with HKEY_CURRENT_USER.  Instead, call the RegOpenCurrentUser() function.  A single registry key can be opened only 65634 times.  On the 65535th open attempt, this function fails with ERROR_NO_SYSTEM_RESOURCES.

 

Table 35.

 

RegOpenCurrentUser()

 

Item

Description

Function

RegOpenCurrentUser().

Use

To retrieve a handle to the HKEY_CURRENT_USER key for the user the current thread is impersonating.

Prototype

LONG RegOpenCurrentUser(REGSAM samDesired, PHKEY phkResult);

Parameters

samDesired - [in] Access mask that specifies the desired access rights to the key.  The function fails if the security descriptor of the key does not permit the requested access for the calling process.

phkResult - [out] Pointer to a variable that receives a handle to the opened key.  When you no longer need the returned handle, call the RegCloseKey() function to close it.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  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.

Include file

<windows.h>

Remark

The HKEY_CURRENT_USER key maps to the root of the current user's branch in the HKEY_USERS key.  It is cached for all threads in a process.  Therefore, this value does not change when another user's profile is loaded.  RegOpenCurrentUser() uses the thread's token to access the appropriate key, or the default if the profile is not loaded.

 

Table 36.

 

RegOpenUserClassesRoot()

 

Item

Description

Function

RegOpenUserClassesRoot().

Use

To retrieve a handle to the HKEY_CLASSES_ROOT key for a specified user. The user is identified by an access token.  The returned key has a view of the registry that merges the contents of the HKEY_LOCAL_MACHINE\Software\Classes key with the contents of the Software\Classes keys in the user's registry hive.

Prototype

LONG RegOpenUserClassesRoot( HANDLE hToken, DWORD dwOptions, REGSAM samDesired, PHKEY phkResult);

Parameters

hToken - [in] Handle to a primary or impersonation access token that identifies the user of interest.  This can be a token handle returned by a call to LogonUser(), CreateRestrictedToken(), DuplicateToken(), DuplicateTokenEx(), OpenProcessToken(), or OpenThreadToken() functions.  The handle must have TOKEN_QUERY access.

dwOptions - Reserved; must be zero.

samDesired - [in] Access mask that specifies the desired access rights to the key.  The function fails if the security descriptor of the key does not permit the requested access for the calling process.

phkResult - [out] Pointer to a variable that receives a handle to the opened key.  When you no longer need the returned handle, call the RegCloseKey() function to close it.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  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.

Include file

<windows.h>

Remark

The RegOpenUserClassesRoot() function enables you to retrieve the merged HKEY_CLASSES_ROOT information for users other than the interactive user.  For example, the server component of a client/server application could use RegOpenUserClassesRoot() to retrieve the merged information for a client.  RegOpenUserClassesRoot() fails if the user profile for the specified user is not loaded.  When a user logs on interactively, the system automatically loads the user's profile.  For other users, you can call the LoadUserProfile() function to load the user's profile.  However, LoadUserProfile() can be very time-consuming, so do not call it for this purpose unless it is absolutely necessary to have the user's merged HKEY_CLASSES_ROOT information.  Applications running in the security context of the interactively logged-on user do not need to use RegOpenUserClassesRoot().  These applications can call the RegOpenKeyEx() function to retrieve a merged view of the HKEY_CLASSES_ROOT key for the interactive user.

 

Table 37.

 

RegQueryMultipleValues()

 

Item

Description

Function

RegQueryMultipleValues().

Use

To retrieve the type and data for a list of value names associated with an open registry key.

Prototype

LONG RegQueryMultipleValues( HKEY hKey, PVALENT val_list, DWORD num_vals, LPTSTR lpValueBuf,

  LPDWORD ldwTotsize);

Parameter

hKey

[in] Handle to an open key.  The key must have been opened with the KEY_QUERY_VALUE access right.  This handle is returned by the RegCreateKeyEx() or RegOpenKeyEx() function or it can be one of the following predefined keys:

  1. HKEY_CLASSES_ROOT

  2. HKEY_CURRENT_CONFIG

  3. HKEY_CURRENT_USER

  4. HKEY_LOCAL_MACHINE

  5. HKEY_PERFORMANCE_DATA

  6. HKEY_USERS

 

Windows Me/98/95:  This parameter can also be the following key: HKEY_DYN_DATA

 

val_list - [out] Pointer to an array of VALENT structures that describe one or more value entries.  On input, the ve_valuename member of each structure must contain a pointer to the name of a value to retrieve.  The function fails if any of the specified values do not exist in the specified key.  If the function succeeds, each element of the array contains the information for the specified value.

num_vals - [in] Number of elements in the val_list array.

lpValueBuf - [out] Pointer to a buffer.  If the function succeeds, the buffer receives the data for each value. If lpValueBuf is NULL, the value pointed to by the ldwTotsize parameter must be zero, in which case the function returns ERROR_MORE_DATA and ldwTotsize receives the required size of the buffer, in bytes.

ldwTotsize - [in, out] Pointer to a variable that specifies the size of the buffer pointed to by the lpValueBuf parameter, in bytes.  If the function succeeds, ldwTotsize receives the number of bytes copied to the buffer.  If the function fails because the buffer is too small, ldwTotsize receives the required size, in bytes.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  If the function fails, the return value is one of the following error codes:

  1. ERROR_CANTREAD - RegQueryMultipleValues() cannot instantiate or access the provider of the dynamic key.

  2. ERROR_MORE_DATA - The buffer pointed to by lpValueBuf was too small.  In this case, ldwTotsize returns the required buffer size.

  3. ERROR_TRANSFER_TOO_LONG - The total size of the requested data (size of the val_list array + ldwTotSize) is more than the system limit of one megabyte.

Header file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.  The RegQueryMultipleValues() function allows an application to query one or more values of a static or dynamic key.  If the target key is a static key, the system provides all of the values in an atomic fashion.  To prevent excessive serialization, the aggregate data returned by the function cannot exceed one megabyte.   If the target key is a dynamic key, its provider must provide all the values in an atomic fashion.  This means the provider should fill the results buffer synchronously, providing a consistent view of all the values in the buffer while avoiding excessive serialization.  The provider can provide at most one megabyte of total output data during an atomic call to this function.  RegQueryMultipleValues() is supported remotely; that is, the hKey parameter passed to the function can refer to a remote computer.

 

Table 38.

 

GetVersionEx()

 

Item

Description

Function

GetVersionEx().

Use

To obtain extended information about the version of the operating system that is currently running.

Prototype

BOOL GetVersionEx(LPOSVERSIONINFO   lpVersionInfo);

Parameters

lpVersionInfo - [in, out] Pointer to an OSVERSIONINFO data structure that the function fills with operating system version information. Before calling the GetVersionEx() function, set the dwOSVersionInfoSize member of this structure to sizeof(OSVERSIONINFO).  For Windows NT 4.0 SP6 and later:  This member can be a pointer to an OSVERSIONINFOEX structure.  Set the dwOSVersionInfoSize member to sizeof(OSVERSIONINFOEX) to identify the structure type.

Return value

If the function succeeds, the return value is a nonzero value.  If the function fails, the return value is zero. To get extended error information, call GetLastError().  The function fails if you specify an invalid value for the dwOSVersionInfoSize member of the OSVERSIONINFO or OSVERSIONINFOEX structure.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.  Also see below.

 

Table 39.

 

When using the GetVersionEx() function to determine whether your application is running on a particular version of the operating system, check for version numbers that are greater than or equal to the desired version numbers.  This ensures that the test succeeds for later versions of the operating system.  For example, if your application requires Windows XP, use the following test:

osver.dwOSVersionInfoSize = sizeof(OSVERSIONINFO);

GetVersionEx (&osver);

bIsWindowsXPorLater = ((osver.dwMajorVersion > 5) || ((osver.dwMajorVersion == 5) && (osver.dwMinorVersion >= 1));

Identifying the current operating system is usually not the best way to determine whether a particular operating system feature is present.  This is because the operating system may have had new features added in a redistributable DLL.  Rather than using GetVersionEx() to determine the operating system platform or version number, test for the presence of the feature itself.  To verify whether the current operating system is either Windows XP Media Center Edition or Tablet PC Edition, use the GetSystemMetrics() function.  To obtain information for the operating system on a remote computer, use the NetWkstaGetInfo() function, the Win32_OperatingSystem WMI class, or the OperatingSystem property of the IADsComputer interface.  To compare the current system version to a required version, use the VerifyVersionInfo() function instead of using GetVersionEx() to perform the comparison yourself.

 

RegDeleteKey()

 

Item

Description

Function

RegDeleteKey().

Use

To delete a subkey, including all of its values.

Prototype

LONG RegDeleteKey( HKEY hKey, LPCTSTR lpSubKey);

Parameters

hKey - [in] Handle to an open key. The key must have been opened with the DELETE access right.  This handle is returned by the RegCreateKeyEx() or RegOpenKeyEx() function or it can be one of the following predefined keys:

 

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

 

Windows Me/98/95:  This parameter can also be the following value: HKEY_DYN_DATA

 

lpSubKey - [in] Pointer to a null-terminated string specifying the name of the key to be deleted.  It must be a subkey of the key identified by hKey, but it cannot have subkeys.  This parameter cannot be NULL.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.  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.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.  A deleted key is not removed until the last handle to it has been closed.  The subkey to be deleted must not have subkeys.  To delete a key and all its subkeys, you need to recursively enumerate the subkeys and delete them individually.  To recursively delete keys, use the SHDeleteKey() function.

 

Table 40.

 

---------------------------Registry: Functions & structures---------------------------

 

Further reading and digging:

 

  1. Check the best selling C, C++ and Windows books at Amazon.com.

  2. Microsoft Visual C++, online MSDN.

  3. MSDN library.

  4. For Multibytes, Unicode characters and Localization stories please refer to Multibyte & Unicode 1 and Multibyte & Unicode 2.

  5. Structure, enum, union and typedef story can be found at enum, typedef, struct etc.

  6. Notation used in MSDN is Hungarian Notation instead of CamelCase and is discussed C & C++ Notation.

  7. Windows data type information is in Windows data types.

 

 

 

 

 

 

| Previous | Main | Site Index | Download | Disclaimer | Privacy |