Função MapFileAndCheckSumA (imagehlp.h)

  • Artigo

Calcula a soma de verificação do arquivo especificado.

Sintaxe

DWORD IMAGEAPI MapFileAndCheckSumA(
  [in]  PCSTR  Filename,
  [out] PDWORD HeaderSum,
  [out] PDWORD CheckSum
);

Parâmetros

[in] Filename

O nome do arquivo para o qual a soma de verificação deve ser computada.

[out] HeaderSum

Um ponteiro para uma variável que recebe a soma de verificação original do arquivo de imagem ou zero se houver um erro.

[out] CheckSum

Um ponteiro para uma variável que recebe a soma de verificação computada.

Retornar valor

Se a função for bem-sucedida, o valor retornado será CHECKSUM_SUCCESS (0).

Se a função falhar, o valor retornado será um dos seguintes.

Valor/código retornado Descrição
CHECKSUM_MAP_FAILURE
2
 Não foi possível mapear o arquivo.
CHECKSUM_MAPVIEW_FAILURE
3
 Não foi possível mapear uma exibição do arquivo.
CHECKSUM_OPEN_FAILURE
1
 Não foi possível abrir o arquivo.
CHECKSUM_UNICODE_FAILURE
4
 Não foi possível converter o nome do arquivo em Unicode.

Comentários

A função MapFileAndCheckSum calcula uma nova soma de verificação para o arquivo e a retorna no parâmetro CheckSum . Essa função é usada por qualquer aplicativo que cria ou modifica uma imagem executável. Somas de verificação são necessárias para drivers no modo kernel e algumas DLLs do sistema. O vinculador computa a soma de verificação original no momento do link, se você usar a opção de vinculador apropriada. Para obter mais detalhes, consulte a documentação do vinculador.

É recomendável que todas as imagens tenham somas de verificação válidas. É responsabilidade do chamador colocar a soma de verificação recém-computada na imagem mapeada e atualizar a imagem em disco do arquivo.

Passar um parâmetro Filename que não aponte para uma imagem executável válida produzirá resultados imprevisíveis. Qualquer usuário dessa função é incentivado a garantir que uma imagem executável válida esteja sendo passada.

Todas as funções ImageHlp, como esta, são threaded único. Portanto, chamadas de mais de um thread para essa função provavelmente resultarão em comportamento inesperado ou corrupção de memória. Para evitar isso, você deve sincronizar todas as chamadas simultâneas de mais de um thread para essa função.

Nota A implementação Unicode dessa função chama a implementação ASCII e, como resultado, a função pode falhar se a página de código não der suporte aos caracteres no caminho. Por exemplo, se você passar um caminho de arquivo Unicode não inglês e a página de código padrão for inglês, os caracteres não reconhecidos em todo o inglês serão convertidos em "??" e o arquivo não pode ser aberto (a função retorna CHECKSUM_OPEN_FAILURE).
 

Observação

O cabeçalho imagehlp.h define MapFileAndCheckSum 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 XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho imagehlp.h
Biblioteca Imagehlp.lib
DLL Imagehlp.dll

Confira também

CheckSumMappedFile

Funções ImageHlp