Função VerQueryValueA (winver.h)

Artigo
11/20/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 um dos formulários 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 de variável var – o membro valor 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 de stringTable específica do idioma (usando o membro szKey do ) no recurso de informações de versão.

\StringFileInfo\lang-codepage\string-name

Um valor em uma estrutura de stringTable específica do idioma. O nome de 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 para o recurso. Aqui, o nome de lang-codepage deve ser especificado como uma cadeia de caracteres hexadecimal. O nome da cadeia de caracteres nome 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 é retornado, 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 de pBlock associada é liberada.

[out] puLen

Tipo: PUINT

Quando esse método é retornado, 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.

Valor de retorno

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 se o recurso especificado não for válido, o valor retornado será zero.

Observações

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

Veja a seguir as informações de versão predefinidas de 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.

Certifique-se de chamar 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); 
}

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

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