Função VerFindFileA (winver.h)

Artigo
03/13/2024

Determina onde instalar um arquivo com base em se ele localiza outra versão do arquivo no sistema. Os valores que VerFindFile retorna nos buffers especificados são usados em uma chamada subsequente para a função VerInstallFile .

Sintaxe

DWORD VerFindFileA(
  [in]           DWORD  uFlags,
  [in]           LPCSTR szFileName,
  [in, optional] LPCSTR szWinDir,
  [in]           LPCSTR szAppDir,
  [out]          LPSTR  szCurDir,
  [in, out]      PUINT  puCurDirLen,
  [out]          LPSTR  szDestDir,
  [in, out]      PUINT  puDestDirLen
);

Parâmetros

[in] uFlags

Tipo: DWORD

Esse parâmetro pode ser o valor a seguir. Todos os outros bits são reservados.

Valor	Significado
VFFF_ISSHAREDFILE 0x0001	O arquivo de origem pode ser compartilhado por vários aplicativos. Um aplicativo pode usar essas informações para determinar onde o arquivo deve ser copiado.

[in] szFileName

Tipo: LPCTSTR

O nome do arquivo a ser instalado. Inclua apenas o nome e a extensão do arquivo, não um caminho.

[in, optional] szWinDir

Tipo: LPCTSTR

O diretório no qual o Windows está em execução ou será executado. Essa cadeia de caracteres é retornada pela função GetWindowsDirectory .

[in] szAppDir

Tipo: LPCTSTR

O diretório em que o programa de instalação está instalando um conjunto de arquivos relacionados. Se o programa de instalação estiver instalando um aplicativo, esse será o diretório em que o aplicativo residirá. Esse parâmetro também aponta para o diretório atual do aplicativo, a menos que especificado de outra forma.

[out] szCurDir

Tipo: LPWSTR

Um buffer que recebe o caminho para uma versão atual do arquivo que está sendo instalado. O caminho é uma cadeia de caracteres terminada em zero. Se uma versão atual não estiver instalada, o buffer conterá uma cadeia de caracteres de comprimento zero. O buffer deve ter pelo menos _MAX_PATH caracteres, embora isso não seja necessário.

[in, out] puCurDirLen

Tipo: PUINT

O comprimento do buffer szCurDir . Esse ponteiro não deve ser NULL.

Quando a função retorna, lpuCurDirLen contém o tamanho, em caracteres, dos dados retornados em szCurDir, incluindo o caractere nulo de terminação. Se o buffer for muito pequeno para conter todos os dados, lpuCurDirLen será o tamanho do buffer necessário para manter o caminho.

[out] szDestDir

Tipo: LPTSTR

Um buffer que recebe o caminho para o local de instalação recomendado por VerFindFile. O caminho é uma cadeia de caracteres terminada em zero. O buffer deve ter pelo menos _MAX_PATH caracteres, embora isso não seja necessário.

[in, out] puDestDirLen

Tipo: PUINT

Um ponteiro para uma variável que especifica o comprimento do buffer szDestDir . Esse ponteiro não deve ser NULL.

Quando a função retorna, lpuDestDirLen contém o tamanho, em caracteres, dos dados retornados em szDestDir, incluindo o caractere nulo de terminação. Se o buffer for muito pequeno para conter todos os dados, lpuDestDirLen será o tamanho do buffer necessário para manter o caminho.

Retornar valor

Tipo: DWORD

O valor retornado é uma máscara de bits que indica o status do arquivo. Ela pode ser um ou mais dos seguintes valores. Todos os outros valores são reservados.

Valor/código retornado	Descrição
VFF_CURNEDEST 0x0001	A versão instalada atualmente do arquivo não está no destino recomendado.
VFF_FILEINUSE 0x0002	O sistema está usando a versão atualmente instalada do arquivo; portanto, o arquivo não pode ser substituído ou excluído.
VFF_BUFFTOOSMALL 0x0004	Pelo menos um dos buffers era muito pequeno para conter a cadeia de caracteres correspondente. Um aplicativo deve marcar os buffers de saída para determinar qual buffer era muito pequeno.

Comentários

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

VerFindFile procura uma cópia do arquivo especificado usando a função OpenFile . No entanto, ele determina o diretório do sistema do diretório do Windows especificado ou pesquisa o caminho.

Se o parâmetro dwFlags indicar que o arquivo é privado para este aplicativo (não VFFF_ISSHAREDFILE), VerFindFile recomenda instalar o arquivo no diretório do aplicativo. Caso contrário, se o sistema estiver executando uma cópia compartilhada do sistema, a função recomendará a instalação do arquivo no diretório do Windows. Se o sistema estiver executando uma cópia privada do sistema, a função recomendará a instalação do arquivo no diretório do sistema.

Observação

O cabeçalho winver.h define VerFindFile 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 (incluir Windows.h)
Biblioteca	Version.lib
DLL	Api-ms-win-core-version-l1-1-0.dll