Função VerQueryValueA (winver.h)

Artigo
03/04/2024

Recupera informações de versão especificadas do recurso de informações de versão especificado. Para recuperar o recurso apropriado, antes de chamar VerQueryValue, você deve primeiro chamar a função GetFileVersionInfoSize e, em seguida, a função GetFileVersionInfo .

Sintaxe

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

Parâmetros

[in] pBlock

Tipo: LPCVOID

O recurso de informações de versão retornado pela função GetFileVersionInfo .

[in] lpSubBlock

Tipo: LPCTSTR

O valor de informações de versão a ser recuperado. A cadeia de caracteres deve consistir em nomes separados por barras invertidas (\) e deve ter uma das formas a seguir.

\

O bloco raiz. A função recupera um ponteiro para a estrutura VS_FIXEDFILEINFO para o recurso de informações de versão.

\VarFileInfo\Translation

A matriz de tradução em uma estrutura de informações da variável Var – o membro Value dessa estrutura. A função recupera um ponteiro para essa matriz de identificadores de página de código e idioma. Um aplicativo pode usar esses identificadores para acessar uma estrutura StringTable específica do idioma (usando o membro szKey ) no recurso de informações de versão.

\StringFileInfo\lang-codepage\string-name

Um valor em uma estrutura StringTable específica do idioma. O nome da página lang-code é uma concatenação de um par de identificadores de página de código e idioma encontrado como um DWORD na matriz de tradução do recurso. Aqui, o nome da página lang-code deve ser especificado como uma cadeia de caracteres hexadecimal. O nome da cadeia de caracteres deve ser uma das cadeias de caracteres predefinidas descritas na seção Comentários a seguir. A função recupera um valor de cadeia de caracteres específico para a página de idioma e código indicada.

[out] lplpBuffer

Tipo: LPVOID*

Quando esse método retorna, contém o endereço de um ponteiro para as informações de versão solicitadas no buffer apontado por pBlock. A memória apontada por lplpBuffer é liberada quando a memória pBlock associada é liberada.

[out] puLen

Tipo: PUINT

Quando esse método retorna, contém um ponteiro para o tamanho dos dados solicitados apontados por lplpBuffer: para valores de informações de versão, o comprimento em caracteres da cadeia de caracteres armazenada em lplpBuffer; para valores de matriz de tradução, o tamanho em bytes da matriz armazenada em lplpBuffer; e para o bloco raiz, o tamanho em bytes da estrutura.

Retornar valor

Tipo: BOOL

Se a estrutura de informações de versão especificada existir e as informações de versão estiverem disponíveis, o valor retornado não será zero. Se o endereço do buffer de comprimento for zero, nenhum valor estará disponível para o nome de informações de versão especificado.

Se o nome especificado não existir ou o recurso especificado não for válido, o valor retornado será zero.

Comentários

Essa função funciona em imagens de arquivo de 16, 32 e 64 bits.

Veja a seguir as informações de versão predefinidas Cadeias de caracteres Unicode.

Comentários	InternalName	ProductName
CompanyName	LegalCopyright	ProductVersion
FileDescription	LegalTrademarks	PrivateBuild
FileVersion	OriginalFilename	SpecialBuild

Exemplos

O exemplo a seguir mostra como enumerar os idiomas de versão disponíveis e recuperar o valor da cadeia de caracteres FileDescription para cada idioma.

Chame as funções GetFileVersionInfoSize e GetFileVersionInfo antes de chamar VerQueryValue para inicializar corretamente o buffer 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); 
}

Observação

O cabeçalho winver.h define VerQueryValue como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winver.h (inclua Windows.h)
Biblioteca	Version.lib
DLL	Api-ms-win-core-version-l1-1-0.dll