VerQueryValueA 函式 (winver.h)

發行項
03/04/2024

從指定的版本資訊資源擷取指定的版本資訊。若要擷取適當的資源，您必須先呼叫 GetFileVersionInfoSize 函式，然後再呼叫 GetFileVersionInfo 函式。

語法

BOOL VerQueryValueA(
  [in]  LPCVOID pBlock,
  [in]  LPCSTR  lpSubBlock,
  [out] LPVOID  *lplpBuffer,
  [out] PUINT   puLen
);

參數

[in] pBlock

類型： LPCVOID

GetFileVersionInfo 函式所傳回的版本信息資源。

[in] lpSubBlock

類型： LPCTSTR

要擷取的版本資訊值。字串必須由反斜杠分隔的名稱 (\) ，而且必須具有下列其中一種形式。

\

根區塊。函式會擷取版本資訊資源 VS_FIXEDFILEINFO 結構的指標。

\VarFileInfo\Translation

Var 變數信息結構中的轉譯數位—這個結構的 Value 成員。函式會擷取這個語言陣列和代碼頁標識碼的指標。應用程式可以使用這些標識碼，在版本信息資源中使用 szKey 成員) 來存取語言特定的 StringTable 結構 (。

\StringFileInfo\lang-codepage\string-name

語言特定 StringTable 結構中的值。 lang-codepage 名稱是語言和代碼頁標識符組的串連，可在資源的翻譯陣列中找到為 DWORD。在這裡， lang-codepage 名稱必須指定為十六進位字串。 字串名稱必須是下列一節中所述的其中一個預先定義字串。函式會擷取指定的語言和代碼頁特定的字串值。

[out] lplpBuffer

類型： LPVOID*

當這個方法傳回時，會包含 pBlock 所指向之緩衝區中所要求版本資訊的指標位址。釋放相關聯的 pBlock 記憶體時，會釋放 lplpBuffer 所指向的記憶體。

[out] puLen

類型： PUINT

當這個方法傳回時，會包含 lplpBuffer 所指向之所要求數據大小的指標：對於版本資訊值，儲存在 lplpBuffer 之字串的長度;若為轉譯數位值，則為儲存在 lplpBuffer 之陣列的大小，以位元組為單位;若為根區塊，則為結構的大小，以位元組為單位。

傳回值

類型： BOOL

如果指定的版本信息結構存在，且版本資訊可用，則傳回值為非零。如果長度緩衝區的位址為零，則指定的版本資訊名稱沒有可用的值。

如果指定的名稱不存在或指定的資源無效，則傳回值為零。

備註

此函式適用於16位、32位和64位檔案映像。

以下是預先定義的版本資訊 Unicode 字串。

註解	InternalName	ProductName
CompanyName	LegalCopyright	ProductVersion
FileDescription	LegalTrademarks	PrivateBuild
FileVersion	OriginalFilename	SpecialBuild

範例

下列範例示範如何列舉可用的版本語言，並擷取每個語言的 FileDescription 字串值。

請務必先呼叫 GetFileVersionInfoSize 和 GetFileVersionInfo 函式，再呼叫 VerQueryValue 以正確初始化 pBlock 緩衝區。

// Structure used to store enumerated languages and code pages.

HRESULT hr;

struct LANGANDCODEPAGE {
  WORD wLanguage;
  WORD wCodePage;
} *lpTranslate;

// Read the list of languages and code pages.

VerQueryValue(pBlock, 
              TEXT("\\VarFileInfo\\Translation"),
              (LPVOID*)&lpTranslate,
              &cbTranslate);

// Read the file description for each language and code page.

for( i=0; i < (cbTranslate/sizeof(struct LANGANDCODEPAGE)); i++ )
{
  hr = StringCchPrintf(SubBlock, 50,
            TEXT("\\StringFileInfo\\%04x%04x\\FileDescription"),
            lpTranslate[i].wLanguage,
            lpTranslate[i].wCodePage);
	if (FAILED(hr))
	{
	// TODO: write error handler.
	}

  // Retrieve file description for language and code page "i". 
  VerQueryValue(pBlock, 
                SubBlock, 
                &lpBuffer, 
                &dwBytes); 
}

注意

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

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	winver.h (包含 Windows.h)
程式庫	Version.lib
Dll	Api-ms-win-core-version-l1-1-0.dll