org.xvolks.jnative.util.Advapi32
|
JNative v1.3 project : see http://jnative.sf.net |
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public class Advapi32
$Id: Advapi32.java,v 1.4 2006/06/09 20:44:04 mdenty Exp $ This software is released under the LGPL.
| Field Summary | |
|---|---|
static java.lang.String |
DLL_NAME
|
| Constructor Summary | |
|---|---|
Advapi32()
|
|
| Method Summary | |
|---|---|
static int |
getLastErrorCode()
|
static void |
listKey(HKEY hKey)
|
static void |
main(java.lang.String[] args)
|
static boolean |
RegCloseKey(HKEY hKey)
RegCloseKey Closes a handle to the specified registry key. |
static RegKey |
RegEnumKeyEx(HKEY hKey,
int dwIndex,
RegKey lKey)
RegEnumKeyEx Enumerates the subkeys of the specified open registry key. |
static RegValue |
RegEnumValue(HKEY hKey,
int dwIndex,
RegValue lRegValue)
RegEnumValue Enumerates the values for the specified open registry key. |
static RegData |
RegGetValue(HKEY hKey,
java.lang.String lpSubKey,
java.lang.String lpValue,
int dwFlags,
RegData lRegData)
RegGetValue Retrieves the type and data for the specified registry value. |
static HKEY |
RegOpenKeyEx(HKEY key,
java.lang.String lpSubKey,
REGSAM samDesired)
RegOpenKeyEx Opens the specified registry key. |
static RegQueryKey |
RegQueryInfoKey(HKEY hKey,
RegQueryKey lKey)
RegQueryInfoKey Retrieves information about the specified registry key. |
static RegData |
RegQueryValueEx(HKEY hKey,
java.lang.String lpValueName,
RegData lRegData)
RegQueryValueEx Retrieves the type and data for the specified value name associated with an open registry key. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final java.lang.String DLL_NAME
| Constructor Detail |
|---|
public Advapi32()
| Method Detail |
|---|
public static int getLastErrorCode()
public static HKEY RegOpenKeyEx(HKEY key,
java.lang.String lpSubKey,
REGSAM samDesired)
throws NativeException,
java.lang.IllegalAccessException
RegOpenKeyEx
Opens the specified registry key. Note that key names are not case sensitive.
LONG RegOpenKeyEx(
HKEY hKey,
LPCTSTR lpSubKey,
DWORD ulOptions,
REGSAM samDesired,
PHKEY phkResult
);
Parameters
hKey
[in] A handle to an open registry key. 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_USER
HKEY_LOCAL_MACHINE
HKEY_USERS
Windows Me/98/95: This parameter can also be the following key:
HKEY_DYN_DATA
lpSubKey
[in] The name of the registry subkey to be opened.
Key names are not case sensitive.
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.
For more information, see Registry Element Size Limits.
ulOptions
This parameter is reserved and must be zero.
samDesired
[in] A 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. For more information, see Registry Key Security and Access Rights.
phkResult
[out] A pointer to a variable that receives a handle to the opened key. If the key is not one of the predefined registry keys, call the RegCloseKey function after you have finished using the handle.
Return Values
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.
Remarks
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 65534 times. When attempting the 65535th open operation, this function fails with ERROR_NO_SYSTEM_RESOURCES.
NativeException
java.lang.IllegalAccessException
public static boolean RegCloseKey(HKEY hKey)
throws NativeException,
java.lang.IllegalAccessException
RegCloseKey
Closes a handle to the specified registry key.
LONG RegCloseKey(
HKEY hKey
);
Parameters
hKey
[in] A handle to the open key to be closed. The handle must have been opened by the RegCreateKeyEx, RegOpenKeyEx, or RegConnectRegistry function.
Return Values
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.
Remarks
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. RegFlushKey, however, uses many system resources and should be called only when necessary.
NativeException
java.lang.IllegalAccessException
public static RegKey RegEnumKeyEx(HKEY hKey,
int dwIndex,
RegKey lKey)
throws NativeException,
java.lang.IllegalAccessException
RegEnumKeyEx
Enumerates the subkeys of the specified open registry key. The function retrieves information about one subkey each time it is called.
LONG RegEnumKeyEx(
HKEY hKey,
DWORD dwIndex,
LPTSTR lpName,
LPDWORD lpcName,
LPDWORD lpReserved,
LPTSTR lpClass,
LPDWORD lpcClass,
PFILETIME lpftLastWriteTime
);
Parameters
hKey
[in] A handle to an open registry key. The key must have been opened with the KEY_ENUMERATE_SUB_KEYS access right. For more information, see Registry Key Security and Access Rights.
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_PERFORMANCE_DATA
HKEY_USERS
Windows Me/98/95: This parameter can also be the following value:
HKEY_DYN_DATA
dwIndex
[in] The 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] A 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.
For more information, see Registry Element Size Limits.
lpcName
[in, out] A 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
This parameter is reserved and must be NULL.
lpClass
[in, out] A pointer to a buffer that receives the null-terminated class string of the enumerated subkey. This parameter can be NULL.
lpcClass
[in, out] A 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] A pointer to a variable that receives the time at which the enumerated subkey was last written. This parameter can be NULL.
Return Values
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.
If the lpName buffer is too small to receive the name of the key, the function returns ERROR_MORE_DATA.
Remarks
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.
hKey - dwIndex - lKey -
NativeException
java.lang.IllegalAccessException
public static RegQueryKey RegQueryInfoKey(HKEY hKey,
RegQueryKey lKey)
throws NativeException,
java.lang.IllegalAccessException
RegQueryInfoKey
Retrieves information about the specified registry key.
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] A handle to an open registry key. The key must have been opened with the KEY_QUERY_VALUE access right. For more information, see Registry Key Security and Access Rights.
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_PERFORMANCE_DATA
HKEY_USERS
Windows Me/98/95: This parameter can also be the following key:
HKEY_DYN_DATA
lpClass
[out] A pointer to a buffer that receives the key class. This parameter can be NULL.
lpcClass
[in, out] A pointer to a variable that specifies the size of the buffer pointed to by the lpClass parameter, in characters.
The size should include the terminating null character. When the function returns, this variable contains the size of the class string that is 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 terminating null character.
If lpClass is NULL, lpcClass can be NULL.
If the lpClass parameter is a valid address, but the lpcClass parameter is not, for example, it is NULL, then 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, then 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
This parameter is reserved and must be NULL.
lpcSubKeys
[out] A pointer to a variable that receives the number of subkeys that are contained by the specified key. This parameter can be NULL.
lpcMaxSubKeyLen
[out] A pointer to a variable that receives the size of the key's subkey with the longest name, in characters, not including the terminating null character. This parameter can be NULL.
Windows Me/98/95: The size includes the terminating null character.
lpcMaxClassLen
[out] A pointer to a variable that receives the size of the longest string that specifies a subkey class, in characters. The count returned does not include the terminating null character. This parameter can be NULL.
lpcValues
[out] A pointer to a variable that receives the number of values that are associated with the key. This parameter can be NULL.
lpcMaxValueNameLen
[out] A pointer to a variable that receives the size of the key's longest value name, in characters. The size does not include the terminating null character. This parameter can be NULL.
lpcMaxValueLen
[out] A 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] A pointer to a variable that receives the size of the key's security descriptor, in bytes. This parameter can be NULL.
lpftLastWriteTime
[out] A pointer to a FILETIME structure that receives the last write time. This parameter can be NULL.
The function sets the members of the FILETIME structure to indicate the last time that the key or any of its value entries is modified.
Windows Me/98/95: The function sets the members of the FILETIME structure to 0 (zero), because the system does not keep track of registry key last write time information.
Return Values
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.
NativeException
java.lang.IllegalAccessException
public static RegData RegQueryValueEx(HKEY hKey,
java.lang.String lpValueName,
RegData lRegData)
throws NativeException,
java.lang.IllegalAccessException
Retrieves the type and data for the specified value name associated with an open registry key.
To ensure that any string values (REG_SZ, REG_MULTI_SZ, and REG_EXPAND_SZ) returned are null-terminated, use the RegGetValue function.
LONG RegQueryValueEx(
HKEY hKey,
LPCTSTR lpValueName,
LPDWORD lpReserved,
LPDWORD lpType,
LPBYTE lpData,
LPDWORD lpcbData
);
Parameters
hKey
[in] A handle to an open registry key. The key must have been opened with the KEY_QUERY_VALUE access right. For more information, see Registry Key Security and Access Rights.
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_PERFORMANCE_DATA
HKEY_PERFORMANCE_NLSTEXT
HKEY_PERFORMANCE_TEXT
HKEY_USERS
Windows Me/98/95: This parameter can also be the following key:
HKEY_DYN_DATA
lpValueName
[in] The name of the registry value.
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.
For more information, see Registry Element Size Limits.
Keys do not automatically have an unnamed or default value. Unnamed values can be of any type.
Windows Me/98/95: Every key has a default value that initially does not contain data. On Windows 95, the default value type is always REG_SZ. On Windows 98 and Windows Me, the type of a key's default value is initially REG_SZ, but RegSetValueEx can specify a default value with a different type.
lpReserved
This parameter is reserved and must be NULL.
lpType
[out] A pointer to a variable that receives a code indicating the type of data stored in the specified value. For a list of the possible type codes, see Registry Value Types. The lpType parameter can be NULL if the type code is not required.
lpData
[out] A pointer to a buffer that receives the value's data. This parameter can be NULL if the data is not required.
lpcbData
[in, out] A 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.
The lpcbData parameter can be NULL only if lpData is NULL.
If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, this size includes any terminating null character or characters. For more information, see Remarks.
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 Values
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.
Remarks
An application typically calls RegEnumValue to determine the value names and then RegQueryValueEx to retrieve the data for the names.
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. Therefore, even if the function returns ERROR_SUCCESS, the application should ensure that the string is properly terminated before using it; otherwise, it may overwrite a buffer. (Note that REG_MULTI_SZ strings should have two null-terminating characters.)
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 RegQueryValueExA 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 unrequested objects. Do not 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.
Example Code [C++]
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.
#include <windows.h>
#include <malloc.h>
#define TOTALBYTES 8192
#define BYTEINCREMENT 1024
DWORD BufferSize = TOTALBYTES;
PPERF_DATA_BLOCK PerfData = NULL;
while( RegQueryValueEx( HKEY_PERFORMANCE_DATA,
TEXT("Global"),
NULL,
NULL,
(LPBYTE) PerfData,
&BufferSize ) == ERROR_MORE_DATA )
{
// Get a buffer that is big enough.
BufferSize += BYTEINCREMENT;
PerfData = (PPERF_DATA_BLOCK) realloc( PerfData, BufferSize );
}
hKey - lpValueName - lRegData -
NativeException
java.lang.IllegalAccessException
public static RegData RegGetValue(HKEY hKey,
java.lang.String lpSubKey,
java.lang.String lpValue,
int dwFlags,
RegData lRegData)
throws NativeException,
java.lang.IllegalAccessException
Retrieves the type and data for the specified registry value.
LONG RegGetValue(
HKEY hkey,
LPCTSTR lpSubKey,
LPCTSTR lpValue,
DWORD dwFlags,
LPDWORD pdwType,
PVOID pvData,
LPDWORD pcbData
);
Parameters
hkey
[in] A handle to an open registry key. The key must have been opened with the KEY_QUERY_VALUE access right. For more information, see Registry Key Security and Access Rights.
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_PERFORMANCE_DATA
HKEY_PERFORMANCE_NLSTEXT
HKEY_PERFORMANCE_TEXT
HKEY_USERS
lpSubKey
[in] The name of the registry key. This key must be a subkey of the key specified by the hkey parameter.
Key names are not case sensitive.
lpValue
[in] The name of the registry value.
If this parameter is NULL or an empty string, "", the function retrieves the type and data for the key's unnamed or default value, if any.
For more information, see Registry Element Size Limits.
Keys do not automatically have an unnamed or default value. Unnamed values can be of any type.
dwFlags
[in] The flags that restrict the data type of value to be queried. If the data type of the value does not meet this criteria, the function fails. This parameter can be one or more of the following values.
Value Meaning
RRF_RT_ANY
0x0000ffff No type restriction.
RRF_RT_DWORD
0x00000018 Restrict type to 32-bit RRF_RT_REG_BINARY | RRF_RT_REG_DWORD.
RRF_RT_QWORD
0x00000048 Restrict type to 64-bit RRF_RT_REG_BINARY | RRF_RT_REG_DWORD.
RRF_RT_REG_BINARY
0x00000008 Restrict type to REG_BINARY.
RRF_RT_REG_DWORD
0x00000010 Restrict type to REG_DWORD.
RRF_RT_REG_EXPAND_SZ
0x00000004 Restrict type to REG_EXPAND_SZ.
RRF_RT_REG_MULTI_SZ
0x00000020 Restrict type to REG_MULTI_SZ.
RRF_RT_REG_NONE
0x00000001 Restrict type to REG_NONE.
RRF_RT_REG_QWORD
0x00000040 Restrict type to REG_QWORD.
RRF_RT_REG_SZ
0x00000002 Restrict type to REG_SZ.
This parameter can also include one or more of the following values.
Value Meaning
RRF_NOEXPAND
0x10000000 Do not automatically expand environment strings if the value is of type REG_EXPAND_SZ.
RRF_ZEROONFAILURE
0x20000000 If pvData is not NULL, set the contents of the buffer to zeroes on failure.
pdwType
[out] A pointer to a variable that receives a code indicating the type of data stored in the specified value. For a list of the possible type codes, see Registry Value Types. This parameter can be NULL if the type is not required.
pvData
[out] A 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. Otherwise, the function fails and returns ERROR_MORE_DATA.
pcbData
[in, out] A pointer to a variable that specifies the size of the buffer pointed to by the pvData parameter, in bytes. When the function returns, this variable contains the size of the data copied to pvData.
The pcbData parameter can be NULL only if pvData is NULL.
If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, this size includes any terminating null character or characters. For more information, see Remarks.
If the buffer specified by pvData 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 pcbData. In this case, the contents of the pvData buffer are undefined.
If pvData is NULL, and pcbData is non-NULL, the function returns ERROR_SUCCESS and stores the size of the data, in bytes, in the variable pointed to by pcbData. 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 pvData buffer is not large enough to contain all of the returned data, the function returns ERROR_MORE_DATA and the value returned through the pcbData 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 RegGetValue again passing the updated buffer size in the pcbData 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 pcbData is unpredictable.
Return Values
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.
Remarks
An application typically calls RegEnumValue to determine the value names and then RegGetValue to retrieve the data for the names.
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. Therefore, even if the function returns ERROR_SUCCESS, the application should ensure that the string is properly terminated before using it; otherwise, it may overwrite a buffer. (Note that REG_MULTI_SZ strings should have two null-terminating characters.)
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 RegGetValueA 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 pvData.
When calling this 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. Do not be surprised; this is normal behavior. You should always expect to walk the returned data structure to look for the requested object.
To compile an application that uses this function, define WIN32_WINNT as 0x0600 or later. For more information, see Using the SDK Headers.
NativeException
java.lang.IllegalAccessException
public static RegValue RegEnumValue(HKEY hKey,
int dwIndex,
RegValue lRegValue)
throws NativeException,
java.lang.IllegalAccessException
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.
LONG RegEnumValue(
HKEY hKey,
DWORD dwIndex,
LPTSTR lpValueName,
LPDWORD lpcValueName,
LPDWORD lpReserved,
LPDWORD lpType,
LPBYTE lpData,
LPDWORD lpcbData
);
Parameters
hKey
[in] A handle to an open registry key. The key must have been opened with the KEY_QUERY_VALUE access right. For more information, see Registry Key Security and Access Rights.
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_PERFORMANCE_DATA
HKEY_USERS
Windows Me/98/95: This parameter can also be the following value:
HKEY_DYN_DATA
dwIndex
[in] The 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] A pointer to a buffer that receives the name of the value, including the terminating null character.
For more information, see Registry Element Size Limits.
lpcValueName
[in, out] A 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
This parameter is reserved and must be NULL.
lpType
[out] A pointer to a variable that receives a code indicating the type of data stored in the specified value. For a list of the possible type codes, see Registry Value Types. The lpType parameter can be NULL if the type code is not required.
lpData
[out] A 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] A 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 data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, this size includes any terminating null character or characters. For more information, see Remarks.
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.
Registry value names are limited to 32767 bytes. The ANSI version of this function treats this param as a USHORT value. Therefore, if you specify a value greater than 32767 bytes, there is an overflow and the function may return ERROR_MORE_DATA.
Return Values
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.
Remarks
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 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 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.
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. Therefore, even if the function returns ERROR_SUCCESS, the application should ensure that the string is properly terminated before using it; otherwise, it may overwrite a buffer. (Note that REG_MULTI_SZ strings should have two null-terminating characters.)
To determine the maximum size of the name and data buffers, use the RegQueryInfoKey function.
hKey - dwIndex - lRegValue -
NativeException
java.lang.IllegalAccessException
public static void main(java.lang.String[] args)
throws NativeException,
java.lang.IllegalAccessException
NativeException
java.lang.IllegalAccessException
public static void listKey(HKEY hKey)
throws NativeException,
java.lang.IllegalAccessException
hKey -
NativeException
java.lang.IllegalAccessException
|
JNative v1.3 project : see http://jnative.sf.net |
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||