共用方式為


RegQueryValueExA 函式 (winreg.h)

擷取與開啟登錄機碼相關聯之指定值名稱的類型和資料。

警告

如果查詢的值是字串 (REG_SZ、REG_MULTI_SZ,而且REG_EXPAND_SZ) 傳回的值不保證為 null 終止。 如果您想要確保傳回的字串值以 Null 終止,請使用 RegGetValue 函式。 如需詳細資訊,請參閱下面的備註。

語法

LSTATUS RegQueryValueExA(
  [in]                HKEY    hKey,
  [in, optional]      LPCSTR  lpValueName,
                      LPDWORD lpReserved,
  [out, optional]     LPDWORD lpType,
  [out, optional]     LPBYTE  lpData,
  [in, out, optional] LPDWORD lpcbData
);

參數

[in] hKey

開啟登錄機碼的控制碼。 金鑰必須已以KEY_QUERY_VALUE存取權限開啟。 如需詳細資訊,請參閱 登錄機碼安全性和存取權限

RegCreateKeyExRegCreateKeyTransactedRegOpenKeyEx 或 RegOpenKeyTransacted函式會傳回此控制碼。 它也可以是下列其中一個 預先定義的索引鍵

HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA
HKEY_PERFORMANCE_NLSTEXT
HKEY_PERFORMANCE_TEXT
HKEY_USERS

[in, optional] lpValueName

登錄值的名稱。

如果 lpValueNameNull 或空字串 「」,則函式會擷取索引鍵未命名或預設值的類型和資料,如果有的話。

如果 lpValueName 指定不在登錄中的值,函式會傳回ERROR_FILE_NOT_FOUND。

索引鍵不會自動有未命名或預設值。 未命名的值可以是任何類型。 如需詳細資訊,請參閱 登錄專案大小限制

lpReserved

此參數是保留的,而且必須是 Null

[out, optional] lpType

變數的指標,接收程式碼,指出儲存在指定值中的資料類型。 如需可能的類型代碼清單,請參閱 登錄實值型別。 如果不需要類型代碼, 則 lpType 參數可以是 Null

[out, optional] lpData

接收值資料之緩衝區的指標。 如果不需要資料,這個參數可以是 Null

[in, out, optional] lpcbData

變數的指標,指定 lpData 參數所指向的緩衝區大小,以位元組為單位。 當函式傳回時,此變數會包含複製到 lpData的資料大小。

只有在lpDataNull時,l其Data參數才能為Null

如果資料具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ類型,則此大小會包含任何終止 的 Null 字元或字元,除非資料未儲存。 如需詳細資訊,請參閱<備註>。

如果 lpData 參數指定的緩衝區不夠大,無法保存資料,函式會傳回ERROR_MORE_DATA,並將所需的緩衝區大小儲存在 l其Data指向的變數中。 在此情況下, 未定義 lpData 緩衝區的內容。

如果 lpDataNull,且 lusbData 為非Null,則函式會傳回ERROR_SUCCESS,並以位元組為單位儲存資料的大小,以位元組為單位,並儲存 lusbData所指向的變數中。 這可讓應用程式判斷為值資料配置緩衝區的最佳方式。

如果 hKey 指定 HKEY_PERFORMANCE_DATA ,且 lpData 緩衝區不夠大,無法包含所有傳回的資料, 則 RegQueryValueEx 會傳回ERROR_MORE_DATA,且未定義透過 lhsData 參數傳回的值。 這是因為效能資料的大小可以從一個呼叫變更為下一個呼叫。 在此情況下,您必須增加緩衝區大小,並再次呼叫 RegQueryValueEx ,並在 lwindowsData 參數中傳遞更新的緩衝區大小。 重複此動作,直到函式成功為止。 您必須維護個別的變數來追蹤緩衝區大小,因為 lData 傳回的值無法預測。

如果 lpValueName 登錄值不存在, 則 RegQueryValueEx 會傳回ERROR_FILE_NOT_FOUND,且未定義透過 lData 參數傳回的值。

傳回值

如果函式成功,傳回值會ERROR_SUCCESS。

如果函式失敗,則傳回值是 系統錯誤碼

如果 lpData 緩衝區太小而無法接收資料,函式會傳回ERROR_MORE_DATA。

如果 lpValueName 登錄值不存在,函式會傳回ERROR_FILE_NOT_FOUND。

備註

應用程式通常會呼叫 RegEnumValue 來判斷值名稱,然後 RegQueryValueEx 來擷取名稱的資料。

如果資料具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ類型,字串可能尚未以適當的終止 Null 字元儲存。 因此,即使函式傳回ERROR_SUCCESS,應用程式也應該確保字串在使用之前已正確終止;否則,它可能會覆寫緩衝區。 (請注意,REG_MULTI_SZ字串應該有兩個終止 的 null 字元。) 應用程式可以確保字串正確終止的方式是使用 RegGetValue,以視需要新增終止 的 Null 字元。

如果資料具有REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ類型,而且此函式的 ANSI 版本會 (藉由明確呼叫 RegQueryValueExA 或未定義 UNICODE,或在包含 Windows.h 檔案) 之前未定義 UNICODE,則此函式會先將儲存的 Unicode 字串轉換成 ANSI 字串,然後再將它複製到 lpData所指向的緩衝區。

呼叫 RegQueryValueEx 函式,並將 hKey 設定為 HKEY_PERFORMANCE_DATA 控制碼和指定物件的值字串時,傳回的資料結構有時會有未查詢的物件。 不要驚奇;這是正常行為。 呼叫 RegQueryValueEx 函式時,您應該一律預期會逐步執行傳回的資料結構來尋找要求的物件。

請注意,存取特定登錄機碼的作業會重新導向。 如需詳細資訊,請參閱 登錄中的登錄虛擬化32 位和 64 位應用程式資料

範例

請確定每次呼叫此函式時 ,都會重新初始化lData 參數所指向的值。 當您在迴圈中呼叫此函式時,這非常重要,如下列程式碼範例所示。

#include <windows.h>
#include <malloc.h>
#include <stdio.h>

#define TOTALBYTES    8192
#define BYTEINCREMENT 4096

void main()
{
    DWORD BufferSize = TOTALBYTES;
    DWORD cbData;
    DWORD dwRet;

    PPERF_DATA_BLOCK PerfData = (PPERF_DATA_BLOCK) malloc( BufferSize );
    cbData = BufferSize;

    printf("\nRetrieving the data...");

    dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
                             TEXT("Global"),
                             NULL,
                             NULL,
                             (LPBYTE) PerfData,
                             &cbData );
    while( dwRet == ERROR_MORE_DATA )
    {
        // Get a buffer that is big enough.

        BufferSize += BYTEINCREMENT;
        PerfData = (PPERF_DATA_BLOCK) realloc( PerfData, BufferSize );
        cbData = BufferSize;

        printf(".");
        dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
                         TEXT("Global"),
                         NULL,
                         NULL,
                         (LPBYTE) PerfData,
                         &cbData );
    }
    if( dwRet == ERROR_SUCCESS )
        printf("\n\nFinal buffer size is %d\n", BufferSize);
    else printf("\nRegQueryValueEx failed (%d)\n", dwRet);
}

注意

winreg.h 標頭會將 RegQueryValueEx 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼,可能會導致編譯或執行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例

規格需求

   
最低支援的用戶端 Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平臺 Windows
標頭 winreg.h (包含 Windows.h)
程式庫 Advapi32.lib
DLL Advapi32.dll

另請參閱

ExpandEnvironmentStrings

RegCreateKeyEx

RegEnumKeyEx

RegEnumValue

RegGetValue

RegOpenKeyEx

RegQueryInfoKey

登錄函式

登錄概觀