Функция FormatMessage

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 для получения кода ошибки).

Параметры

dwFlags
Определяет аспекты процесса форматирования сообщения и способ обработки параметра lpSource. Младшее слово dwFlags определяет как функция должна обрабатывать концы строк в буфере вывода. Младший байт может также определить максимальную ширину отформатированной строки. Вы можете определить комбинацию следующих значений
ЗначениеОписание
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, а является указателем на массив значений, который содержит параметры
Младший байт dwFlags может определять максимальную ширину отформатированной строки. Используйте константу FORMAT_MESSAGE_MAX_WIDTH_MASK и поразрядные логические операции для установки и получения этого максимального значения ширины строки.

Следующая таблица показывает как FormatMessage интерпретирует значение младшего байта.

0Нет никаких ограничений ширины выводимой строки. Функция сохраняет символы конца строки, которые находятся в тексте описания сообщения в буфер вывода
Ненулевое значение, отличное от FORMAT_MESSAGE_MAX_WIDTH_MASKЗначение отличное от нуля является максимальным числом символов в выводимой строке. Функция игнорирует символы конца строки в тексте описания сообщения. Функция никогда не разбивает строку, разделенную пробельными символами (пробелы, символы табуляции и пустой строки). Функция сохраняет только жестко обозначенные символы конца строки в тексте сообщения в буфер вывода. Символы конца строки обозначаются escape-последовательностью %n
FORMAT_MESSAGE_MAX_WIDTH_MASKФункция игнорирует символы конца строки в тексте сообщения. Функция сохраняет только жестко обозначенные в тексте сообщения символы конца строки в буфер вывода. Функция не генерирует новых символов конца строки
lpSource
Определяет источник сообщений. Тип данного параметра зависит от установок в параметре dwFlags
FORMAT_MESSAGE_FROM_HMODULEДескриптор модуля, который содержит искомую таблицу сообщений
FORMAT_MESSAGE_FROM_STRINGУказатель на строку, которая содержит неформатированный текст сообщения. Она будет просканирована на предмет наличия шаблонов вставки и отформатирована соответствующим образом
dwMessageId
Идентификатор требуемого сообщения. Параметр игнорируется, если dwFlags включает FORMAT_MESSAGE_FROM_STRING
dwLanguageId
Идентификатор языка требуемого сообщения. Параметр игнорируется, если dwFlags включает FORMAT_MESSAGE_FROM_STRING. Если вы передадите определенный LANGID в этом параметре, то FormatMessage вернет сообщение только для этого LANGID. Если функция не может найти сообщение для заданного LANGID, то возвращается ERROR_RESOURCE_LANG_NOT_FOUND. Если вы используете 0, то FormatMessage ищет сообщение для LANGID в следующем порядке:
  1. Нейтральный язык
  2. LANGID потока, основанный на значении локали потока
  3. Пользовательский LANGID, основанный на значении локали по умолчанию для пользователя
  4. Системный LANGID, основанный на значении локали по умолчанию для системы
  5. US English
Если FormatMessage не находит сообщение ни для одного из этих LANGID, она возвращает строку сообщения для любого языка, который присутствует. Если и это терпит неудачу, то она возвращает ERROR_RESOURCE_LANG_NOT_FOUND
lpBuffer
Указатель на буфер для форматирования сообщения. Если dwFlags включает FORMAT_MESSAGE_ALLOCATE_BUFFER, то функция выделяет буфер, используя функцию LocalAlloc, и помещает указатель на буфер в адрес, указанный в lpBuffer
nSize
Если флаг FORMAT_MESSAGE_ALLOCATE_BUFFER не установлен, то параметр устанавливает максимальный размер буфера сообщения. Если FORMAT_MESSAGE_ALLOCATE_BUFFER установлен, то параметр устанавливает минимальный размер буфера
Arguments
Указатель на массив значений для вставки в выводимое сообщение. %1 в форматируемом сообщении используется для первого значения в массиве Arguments; %2 - для второго значения и т.д. Интерпретация каждого значения зависит от шаблонов форматирования, вставленных в сообщение. По умолчанию каждое значение должно обрабатываться как указатель на строку с нулевым символом в конце. По умолчанию, параметр Arguments имеет тип va_list*, который является зависимым от языка и реализации типом данных для описания переменного числа параметров. Если вам не нужен указатель типа va_list*, то определите флаг FORMAT_MESSAGE_ARGUMENT_ARRAY и передайте указатель на массив значений. Эти значения будут вставлены в отформатированное сообщение. Каждый шаблон вставки должен иметь соответствующий элемент в массиве.

Пример


' смотри также пример 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

Категория

Ошибки