RegQueryValue函式 (轉)

RegQueryValue函式 (轉)[@more@]RegQueryValueEx(E)
The RegQueryValueEx function retrieves the type and data for a specified value name associated with an open registry key.
RegQueryValueEx找回一個開啟的登錄檔鍵值相關聯的給定的變數資料或者變數。
LONG RegQueryValueEx(
  HKEY hKey,  // handle to key  主鍵控制程式碼
  LPCTSTR lpValueName,  // value name  子鍵名稱
  LPD lpReserved,  // reserved  保留
  LPDWORD lpType,  // type buffer 
  LPBYTE lpData,  // data buffer  返回值的緩衝區
  LPDWORD lpcbData  // size of data buffer儲存返回值的緩衝區的大小
);
Parameters
hKey
[in] Handle to a currently open key or one of the following predefined keys:
HKEY_CLASSES_
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS
NT/2000/XP: HKEY_PERFORMANCE_DATA
: HKEY_PERFORMANCE_TEXT
Windows XP: HKEY_PERFORMANCE_NLSTEXT
Windows 95/98/Me: HKEY_DYN_DATA
lpValueName
[in] Pointer to a null-tenated 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.
Windows 95/98/Me: Every key has a default value that initially does not contain data. On Windows 95, the default value type is always REG_SZ. On , the type of a key's default value is initially REG_SZ, but RegSetValueEx can specify a default value with a different type.
/2000/XP: 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. 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
[in, out] Pointer to a buffer that receives the value's data. This parameter can be NULL if the data is not required.
lpcbData
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. 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, then lpcbData will also include the size of the 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 the value ERROR_MORE_DATA, and stores the required buffer size, in bytes, into the variable pointed to by lpcbData. In this case, the contents of the lpValue 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 lets an application determine the best way to allocate a buffer for the value's data.
Window NT: If hKey specifies HKEY_PERFORMANCE_DATA and the lpData buffer is too small, RegQueryValueEx returns ERROR_MORE_DATA but lpcbData does not return the required buffer size. This is because the size of the performance data can change from one call to the next. In 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
The key ntified by hKey must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.
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 proy 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 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.
Window NT/2000: When calling the RegQueryValueEx function with hKey set to the HKEY_PERFORMANCE_DATA handle and a value string of a specified , the returned data structure sometimes has unrequested 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.
Windows 95/98/Me: No registry subkey or value name may exceed 255 characters.
Windows 95/98/Me: RegQueryValueExW is supported by the Layer for Unicode. To use this, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.
Example Code
For an example, see Retrieving Data from the Registry.
Requirements
  Windows NT/2000/XP: Included in Windows NT 3.1 and later.
  Windows 95/98/Me: Included in Windows 95 and later.
  Header: Declared in Winreg.h; include Windows.h.
  Library: Use Adv32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP. Also supported by Microsoft Layer for Unicode.
RegQueryValueEx(C)
函式RegQueryValueEx找回一個開啟的登錄檔鍵值相關聯的給定的變數資料或者變數。
LONG RegQueryValueEx(
  HKEY hKey,  //  主鍵控制程式碼
  LPCTSTR lpValueName,  //  子鍵名稱
  LPDWORD lpReserved,  //  保留
  LPDWORD lpType,  // type buffer 
  LPBYTE lpData,  //  儲存返回值的緩衝區
  LPDWORD lpcbData  儲返回值的緩衝區的大小
);
引數：
Hkey  指向一個已經開啟的或者是下列值之一的控制程式碼
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS
Windows NT/2000/XP: HKEY_PERFORMANCE_DATA
Windows XP: HKEY_PERFORMANCE_TEXT
Windows XP: HKEY_PERFORMANCE_NLSTEXT
Windows 95/98/Me: HKEY_DYN_DATA
LpValueName
指向一個以空字元結束的字串，該字串包含要查詢的數值名稱。
如果lpValueName是NULL或者是空字串，函式將找回這個指定鍵值的未命名或者預設的數值。
Windows NT/2000/XP: Keys do not automatically have an unnamed or default value. Unnamed values can be of any type.
Windows 95/98/Me:  任何一個鍵在開始都有一個不包含資料預設的數值型別。在Window95中，預設的數值型別總是REG_SZ,在Windows98中，鍵的預設資料型別初始化為REG_SZ，但是函式RegSetValueEx可以指定一個不同的資料型別作為預設的資料型別。
Windows NT/2000/XP: 鍵不能自動的有一個位命名的或者預設的資料型別。為明明數值可以為任何型別的資料型別
LpReserved
保留的引數，必須為NULL
lpType
[輸出]指向接收儲存特定資料的資料型別的變數，關於特定型別的列表可以檢視註冊變數型別。如果這種型別不是必須的，引數lpType可以為NULL.
LpData
指向接收資料值的緩衝區，如果這個資料不是必須的引數可以為NULL.
LpcbData
[輸入/輸出]  指向一個變數，它表明引數lpData所指向的緩衝區用位元組計算的大小。當函式返回時，這個變數包含了lpData中內容的大小。
如果資料型別是REG_SZ, REG_MULTI_SZ 或者REG_EXPAND_SZ，引數lpcbData的大小將包含結束空字元或者空字串。
如果引數lpData為NULL，引數lpcbData也將為空。
如果引數lpData所指向的緩衝區太小而不能夠儲存返回的所有資料，函式將返回錯誤程式碼ERROR_MORE_DATA，引數lpcbData將儲存以位元組計算，緩衝區所需要的實際的大小，在這種情況下lpValue所指向的緩衝區將不被定義。
如果lpData為NULL,並且lpcbData不為NULL,函式將返回錯誤碼ERROR_SUCCESS，並且儲存以位元組計算的索要儲存的資料的大小。這將是決定分配資料緩衝區的最好方法。
Window NT: 如果鍵值控制程式碼hKey指向HKEY_PERFORMANCE_DATA並且lpData所指向的緩衝區lpData太小，函式RegQueryValueEx將返回錯誤碼ERROR_MORE_DATA，引數lpcbData將不返回所需要的緩衝區的大小。這是因為執行資料的大小可以隨著不同的而改變。在這種情況下，你必須增大緩衝區並且重新呼叫函式RegQueryValueEx，校正引數lpcbData大小，不斷的重複這樣的操作直到函式執行成功。因為lpcbData所返回的數值是不能與小知道的，因此你需要一個獨立的變數來指導緩衝區的大小。
返回值
如果函式執行成功，返回紙將是ERROR_SUCCESS。如果函式執行失敗，返回值是一個定義在頭Winerror.h不為零的錯誤碼。你可以透過函式FormatMessage以標誌FORMAT_MESSAGE_FROM_SYSTEM得到一個一般的錯誤描述。
備註
標誌引數hKey的鍵值被開啟必須擁有權利KEY_QUERY_VALUE。開啟一個鍵可以檢視函式RegCreateKeyEx 和 RegOpenKeyEx。
如果資料型別為REG_SZ, REG_MULTI_SZ 或者 REG_EXPAND_SZ，字串可能不被以空字元結束的字串。應用程式需要在應用它的時候確保該字串是完全的結束。否則，應用程式可能覆蓋了緩衝區而執行失敗。
如果資料型別為REG_SZ, REG_MULTI_SZ 或者 REG_EXPAND_SZ，並且函式為ANSI版本（或者明確的呼叫函式RegQueryValueExA或者在定義標頭檔案Windows.h前沒有定義UNICODE） ，
在複製到lpData所指向的緩衝區之前函式將儲存的Unicode字串轉變成ANSI字串 。
Window NT/2000:  當將hKey設為控制程式碼HKEY_PERFORMANCE_DATA和一個變數字串指向一個特定的時呼叫函式RegQueryValueEx，返回的結構體有時卻是未被請求的物件，其實這是正常的。當呼叫函式RegQueryValueEx時，你總是期望返回的資料結構是你需要的物件。（you should always expect to walk the returned data structure to look for the requested object. ）
Windows 95/98/Me: 沒有註冊的子鍵或者資料值可能超過255個字元。
Windows 95/98/Me:用函式 RegQueryValueExW支援Unicode。要想使用這個函式，你必須為你的應用程式新增特定的檔案支援。具體清檢視微軟的Unicode on Windows 95/98/Me Systems。
例子程式碼：
例項請看 Retrieving Data from the Registry.
需求
  Windows NT/2000/XP: 支援在Windows NT 3.1或者更晚版本.
  Windows 95/98/Me: 支援Windows 95及其更晚版本.
  Header: 在檔案 Winreg.h中宣告;在標頭檔案中Windows.h定義
  Library: 用Advapi32.lib.
  Unicode: 檢視 Unicode and ANSI versions on Windows NT/2000/XP也可以檢視 Microsoft Layer for Unicode的支援。