Функция MapFileAndCheckSumA (imagehlp.h)

Статья
08/24/2023

Вычисляет контрольную сумму указанного файла.

Синтаксис

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

Параметры

[in] Filename

Имя файла, для которого вычисляется контрольная сумма.

[out] HeaderSum

Указатель на переменную, получающую исходную контрольную сумму из файла изображения, или нуль при возникновении ошибки.

[out] CheckSum

Указатель на переменную, получающую вычисленную контрольную сумму.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет CHECKSUM_SUCCESS (0).

Если функция завершается сбоем, возвращается одно из следующих значений.

Возвращаемый код или значение	Описание
CHECKSUM_MAP_FAILURE 2	Не удалось сопоставить файл.
CHECKSUM_MAPVIEW_FAILURE 3	Не удалось сопоставить представление файла.
CHECKSUM_OPEN_FAILURE 1	Не удалось открыть файл.
CHECKSUM_UNICODE_FAILURE 4	Не удалось преобразовать имя файла в Юникод.

Функция MapFileAndCheckSum вычисляет новую контрольную сумму для файла и возвращает ее в параметре CheckSum . Эта функция используется любым приложением, которое создает или изменяет исполняемый образ. Контрольные суммы требуются для драйверов режима ядра и некоторых системных библиотек DLL. Компоновщик вычисляет исходную контрольную сумму во время компоновки, если используется соответствующий переключатель компоновщика. Дополнительные сведения см. в документации по компоновщику.

Рекомендуется, чтобы все образы имели допустимые контрольные суммы. Вызывающий объект несет ответственность за размещение вновь вычисленной контрольной суммы в сопоставленный образ и обновление образа файла на диске.

Передача параметра Filename , который не указывает на допустимый исполняемый образ, приведет к непредсказуемым результатам. Всем пользователям этой функции рекомендуется убедиться, что передается допустимый исполняемый образ.

Все функции ImageHlp, такие как эта, являются однопоточными. Поэтому вызовы из нескольких потоков к этой функции, скорее всего, приведут к непредвиденному поведению или повреждению памяти. Чтобы избежать этого, необходимо синхронизировать все параллельные вызовы из нескольких потоков в эту функцию.

Примечание Реализация этой функции в Юникоде вызывает реализацию ASCII, и в результате функция может завершиться ошибкой, если кодовая страница не поддерживает символы в пути. Например, если вы передаете путь к файлу Юникода, отличному от английского языка, и кодовая страница по умолчанию — английский, то нераспознанные символы, не являющиеся английскими, преобразуются в "??" и не удается открыть файл (функция возвращает CHECKSUM_OPEN_FAILURE).

Примечание

Заголовок imagehlp.h определяет MapFileAndCheckSum в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	imagehlp.h
Библиотека	Imagehlp.lib
DLL	Imagehlp.dll

См. также раздел

CheckSumMappedFile

Функции ImageHlp