Функция FormatMessage

Форматирует строку сообщения. Функция требует определения сообщения как вводимых данных. Определение сообщения может прийти из буфера, который передается в функцию. Оно может прийти из ресурса таблицы сообщений в уже загруженном модуле. Или вызывающая программа (вызывающий модуль) может попросить, чтобы функция нашла в ресурсе (ах) таблицы системных сообщений определение сообщения. Функция находит определение сообщения в ресурсе таблицы сообщений основанных на идентификаторе сообщения и идентификаторе языка. Функция копирует форматированный текст сообщения в буфер выводимых данных, обрабатывая любые встроенные последовательности вставок, если это требуется.

Синтаксис

Параметры

Варианты форматирования и как интерпретировать параметр lpSource. Младший байт dwFlags определяет, как функция обрабатывает разрывы строк в буфере выводимых данных. Младший байт может также установить максимальную ширину выводимой форматированной строки.

Этот параметр, может иметь один или несколько нижеследующих значений.

Младший байт dwFlags может определить максимальную длину выводимой форматированной строки. Ниже перечисляются возможные значения младшего байта.

Расположение определения сообщения. Тип этого параметра зависит от параметров настройки в параметре dwFlags.

Если ни один из этих флажков не устанавлен в dwFlags, то параметр lpSource игнорируется.

Идентификатор сообщения для затребованного сообщения. Этот параметр игнорируется, если dwFlags включает в себя FORMAT_MESSAGE_FROM_STRING.

Идентификатор языка для затребованного сообщения. Этот параметр игнорируется, если dwFlags включает в себя FORMAT_MESSAGE_FROM_STRING.

Если Вы передаёте конкретный LANGID в этом параметре, то FormatMessage возвратит сообщение только для этого LANGID. Если функция не может найти сообщение для этого LANGID, она возвращает  значение ERROR_RESOURCE_LANG_NOT_FOUND. Если Вы передаете нуль, FormatMessage ищет сообщение для LANGIDs в нижеследующем порядке:

1. Неопределенный язык
2. Потоковый LANGID, основывается на потоках с локализированными значениями
3. Пользовательский по умолчанию LANGID, основывается на локализированном значении языка страны (местности) пользователя по умолчанию
4. Системный по умолчанию LANGID, основывается на системном значении локализации по умолчанию
5. Английский язык в США

Если FormatMessage не локализирует сообщения для какого-либо предшествующего LANGIDs, то она возвращает любую языковую строку сообщения, которая присутствует. Если функция завершается ошибкой, то возвращает значение ERROR_RESOURCE_LANG_NOT_FOUND.

Указатель на буфер, который получает строку с завершающим нулем, устанавливающую форматированное сообщение. Если параметр dwFlags включает в себя значение FORMAT_MESSAGE_ALLOCATE_BUFFER, функция назначает буфер, используя функцию LocalAlloc и помещает указатель на буфер по адресу, указанному в параметре lpBuffer.

Этот буфер не может быть больше, чем 64 КБ.

nSize

Если флажок FORMAT_MESSAGE_ALLOCATE_BUFFER не установлен, то этот параметр определяет размер буфера выводимых данных, в TCHARs. Если FORMAT_MESSAGE_ALLOCATE_BUFFER установлен, то этот параметр определяет минимальное число TCHARs, назначаемое для буфера выводимых данных.

Этот буфер не может быть больше, чем 64 КБ.

Arguments

Массив значений, которые используются как значения вставки в форматированном сообщении. %1 в форматирующей строке указывает первое значение в массиве Arguments; %2 указывает второй параметр; и так далее.

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

По умолчанию, параметр Arguments имеет тип va_list *, который является конкретным для языка и конкретным для реализации типом данных для того, чтобы характеризовать переменное число параметров. Состояние параметра va_list не определяется по возвращению из функции. Чтобы использовать va_list снова, ликвидируйте указатель  списка переменных параметров, используя va_begin и повторно инициализируйте его при помощи va_start.

Если у Вас нет указателя типа va_list *, то установите флажок FORMAT_MESSAGE_ARGUMENT_ARRAY и передайте указатель на массив значений DWORD_PTR; эти значения - вводимые данные в сообщение, форматированное как значения вставки. У каждой вставки должен быть соответствующий элемент в массиве.

Windows Me/98/95:  Никакая отдельная строка включения не может выйти за пределы 1023 символов по длине.

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

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

Если функция завершается ошибкой, возвращаемое значение - нуль. Чтобы получить дополнительную информацию об ошибке, вызовите GetLastError.

Замечания

Внутри текста сообщения, несколько ESC-последовательностей поддерживаются для того, чтобы динамически форматировать сообщение. Эти ESC-последовательности и их значения показаны в нижеследующих таблицах. Все ESC-последовательности начинаются с символа процента (%).

Любой другой символ нецифры после символа процента форматируется в выводимом сообщении без символа процента. Ниже - некоторые примеры.

Замечания по безопасности

Если эта функция вызванная без флажка FORMAT_MESSAGE_IGNORE_INSERTS, то параметр Arguments должен содержать в себе достаточно многие параметры, чтобы удовлетворить все последовательности вставки в строке сообщения, и они должны иметь корректный тип. По этой причине, не используйте ненадежные или неизвестные строки сообщений с включенными вставками, потому что они могут содержать в себе больше последовательностей включения, чем, параметр Arguments обеспечивает, или они могут иметь ошибочный тип. В частности опасно получать случайные коды системных ошибок, возвращенные из API и использования флажка FORMAT_MESSAGE_FROM_SYSTEM без флажка FORMAT_MESSAGE_IGNORE_INSERTS.

Демонстрационный код [C++]

Функция FormatMessage может быть использована, чтобы получать строки сообщения об ошибках для кодов системных ошибок, возвращенных функцией GetLastError. Пример смотри в статье Получение последнего кода ошибки. Нижеследующие примеры также демонстрируют использования функции FormatMessage.

Пример ниже показывает, как использовать массив параметра и спецификаторы ширины и точности.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <stdio.h>

void main(void)
{
    LPWSTR pMessage = L"%1!*.*s! %4 %5!*s!";
    DWORD_PTR pArgs[] = { (DWORD_PTR)4, (DWORD_PTR)2, (DWORD_PTR)L"Bill",  // %1!*.*s!
         (DWORD_PTR)L"Bob",                                                // %4
         (DWORD_PTR)6, (DWORD_PTR)L"Bill" };                               // %5!*s!
    const DWORD size = 100+1;
    WCHAR buffer[size];


    if (!FormatMessage(FORMAT_MESSAGE_FROM_STRING | FORMAT_MESSAGE_ARGUMENT_ARRAY,
                       pMessage, 
                       0,  // игнорируется
                       0,  // игнорируется
                       (LPWSTR)&buffer, 
                       size, 
                       (va_list*)pArgs))
    {
        wprintf(L"Format message failed with 0x%x\n", GetLastError());
        return;
    }

    wprintf(L"Formatted message: %s\n", buffer);
}

Демонстрационный код

Пример ниже показывает, как реализовать осуществить предыдущий пример, используя va_list.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <stdio.h>

LPWSTR GetFormattedMessage(LPWSTR pMessage, ...);

void main(void)
{
    LPWSTR pBuffer = NULL;
    LPWSTR pMessage = L"%1!*.*s! %3 %4!*s!";

    pBuffer = GetFormattedMessage(pMessage, 4, 2, L"Bill", L"Bob", 6, L"Bill");
    if (pBuffer)
    {
        wprintf(L"Formatted message: %s\n", pBuffer);
        LocalFree(pBuffer);
    }
    else
    {
        wprintf(L"Format message failed with 0x%x\n", GetLastError());
    }
}

LPWSTR GetFormattedMessage(LPWSTR pMessage, ...)
{
    LPWSTR pBuffer = NULL;

    va_list args = NULL;
    va_start(args, pMessage);

    FormatMessage(FORMAT_MESSAGE_FROM_STRING |
                  FORMAT_MESSAGE_ALLOCATE_BUFFER,
                  pMessage, 
                  0,  // игнорируется
                  0,  // игнорируется
                  (LPWSTR)&pBuffer, 
                  0, 
                  &args);

    va_end(args);

    return pBuffer;
}

Смотри также

Обзор Обработка ошибок, Функции, используемые при обработке ошибок, Ресурс MESSAGETABLE, Компилятор сообщения, Таблицы сообщений