Função MapFileAndCheckSumA (imagehlp.h)

Artigo
11/20/2024

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.

Valor de retorno

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.

Código/valor de retorno	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.

Observações

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 simples. 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.

Observação a implementação Unicode dessa função chama a implementação ASCII e, como resultado, a função poderá 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 largos não reconhecidos não em inglês serão convertidos em "??" e o arquivo não pode ser aberto (a função retorna CHECKSUM_OPEN_FAILURE).

Nota

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

Consulte também

CheckSumMappedFile

imagehlp functions

Compartilhar via