Declare Function FormatMessage Lib "kernel32" Alias "FormatMessageA" ( _
ByVal dwFlags As Long, _
lpSource As Any, _
ByVal dwMessageId As Long, _
ByVal dwLanguageId As Long, _
ByVal lpBuffer As String, _
ByVal nSize As Long, _
Arguments As Long) As Long
FormatMessage позволяет выводит осмысленные сообщения об ошибках, возникающих при вызовах многих функций API. Функция требует на входе описания сообщения. Описание сообщения может передаваться в функцию из буфера. Оно может также передаваться из ресурса таблицы сообщений загруженного модуля или вызывающая программа может сообщить функции, чтобы та взяла описание сообщения из таблицы сообщений системного ресурса. Функция находит описание сообщения в таблице сообщений ресурса основываясь на идентификаторе сообщения и идентификаторе языка. Функция копирует отформатированный текст сообщения в буфер вывода, обрабатывая любые вставляемые последовательности, если это требуется
В успешном случае функция возвращает число символов, хранимых в буфере, включая завершающий нулевой символ. В случае ошибки функция возвращает 0 (используйте GetLastError для получения кода ошибки).
| Значение | Описание |
|---|---|
| FORMAT_MESSAGE_ALLOCATE_BUFFER = &H100 | Определяет, что параметр lpBuffer является указателем на PVOID и nSize определяет минимальное число символов TCHARs для буфера сообщения. Функция выделяет достаточно большой буфер, чтобы поместить отформатированное сообщение, и помещает указатель на выделенный буфер в адрес, указанный в lpBuffer. Вызывающая программа должна использовать функцию LocalFree, чтобы освободить память, выделенную под буфер, когда она больше не нужна |
| FORMAT_MESSAGE_IGNORE_INSERTS | Определяет, что последовательность шаблонов вставки в описании сообщения должна игнорироваться и передаваться в буфер вывода неизмененной. Этот флажок полезен в тех случаях, когда необходимо выбрать сообщение для его более позднего форматирования. Если этот флажок установлен, то параметр Arguments игнорируется |
| FORMAT_MESSAGE_FROM_STRING | Определяет, что параметр lpSource является указателем на описание сообщения с заканчивающим нулевым символом. Описание сообщения может содержать шаблоны вставки, также может содержать текст сообщения из таблицы сообщений ресурса. Нельзя использовать вместе с FORMAT_MESSAGE_FROM_HMODULE или FORMAT_MESSAGE_FROM_SYSTEM |
| FORMAT_MESSAGE_FROM_HMODULE | Определяет, что параметр lpSource является дескриптором модуля, содержащего ресурс таблицы сообщений. Если этот дескриптор NULL, то поиск ведется в модуле текущего процесса. Нельзя использовать вместе с FORMAT_MESSAGE_FROM_STRING |
| FORMAT_MESSAGE_FROM_SYSTEM = &H1000 | Определяет, что функция должна искать требуемое сообщение в таблице сообщений системного ресурса. Если этот флажок определен вместе с FORMAT_MESSAGE_FROM_HMODULE, то функция ищет системную таблицу сообщений лишь в том случае, если сообщение не найдено в модуле, указанном в параметре lpSource. Нельзя использовать с FORMAT_MESSAGE_FROM_STRING. Если этот флажок определен, приложение может передавать в качестве параметра dwMessageId результат функции GetLastError, чтобы отыскать текст сообщения определенной системой ошибки |
| FORMAT_MESSAGE_ARGUMENT_ARRAY | Определяет, что параметр Arguments не является структурой va_list, а является указателем на массив значений, который содержит параметры |
Следующая таблица показывает как FormatMessage интерпретирует значение младшего байта.
| 0 | Нет никаких ограничений ширины выводимой строки. Функция сохраняет символы конца строки, которые находятся в тексте описания сообщения в буфер вывода |
| Ненулевое значение, отличное от FORMAT_MESSAGE_MAX_WIDTH_MASK | Значение отличное от нуля является максимальным числом символов в выводимой строке. Функция игнорирует символы конца строки в тексте описания сообщения. Функция никогда не разбивает строку, разделенную пробельными символами (пробелы, символы табуляции и пустой строки). Функция сохраняет только жестко обозначенные символы конца строки в тексте сообщения в буфер вывода. Символы конца строки обозначаются escape-последовательностью %n |
| FORMAT_MESSAGE_MAX_WIDTH_MASK | Функция игнорирует символы конца строки в тексте сообщения. Функция сохраняет только жестко обозначенные в тексте сообщения символы конца строки в буфер вывода. Функция не генерирует новых символов конца строки |
| FORMAT_MESSAGE_FROM_HMODULE | Дескриптор модуля, который содержит искомую таблицу сообщений |
| FORMAT_MESSAGE_FROM_STRING | Указатель на строку, которая содержит неформатированный текст сообщения. Она будет просканирована на предмет наличия шаблонов вставки и отформатирована соответствующим образом |
' смотри также пример winerrors.zip ' Получим описания кодов ошибок ' Поместите на форме текстовое поле, где будут ' содержаться номера ошибок Dim Buffer As String ' буфер для хранения строки Dim sError As Long ' номер ошибки Buffer = Space(200) ' Устанавливаем номер ошибки sError = CLng(Text1.Text) SetLastError sError ' Создаем строку сообщения об ошибке FormatMessage FORMAT_MESSAGE_FROM_SYSTEM, ByVal 0&, GetLastError, LANG_NEUTRAL, Buffer, 200, ByVal 0& ' Показываем описание ошибки MsgBox Buffer