FillMemory

VOID FillMemory ( PVOID Destination, DWORD Length, BYTE Fill );

Аргументы

0. Destination — указатель на заполняемый блок памяти.

1. Length — размер заполняемого блока памяти в байтах.

2. Fill — значение байта, которым заполняется блок памяти.

Примечание

Функция FillMemory заполняет блок памяти указанным значением.

Описание данной функции содержится в файле заголовка winbase.h.

FormatMessage

DWORD FormatMessage( DWORD dwFlags, LPCVOID lpSource, DWORD dwMessageId, DWORD dwLanguageId, LPTSTR lpBuffer, DWORD nSize, va_list *Arguments );

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

В случае успешного завершения работы функции возвращает число байт (версия ANSI) или символов (версия Unicode), записанных в выходной буфер, исключая завершающий строку нулевой символ. В противном случае возвращает нулевое значение. Расширенную информацию по ошибке можно получить, вызвав функцию GetLastError.

Примечание

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

• FORMAT_MESSAGE_ALLOCATE_BUFFER — в аргументе lpBuffer содержится указатель типа PVOID, а в аргументе nSize содержится размер выходного буфера в байтах (версия ANSI) или символах (версия Unicode). Данная функция выделяет буфер достаточного размера, для размещения в нём всего отформатированного сообщения и помещает указатель на буфер, размещённый по адресу, содержащемуся в аргументе 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 записан дескриптор модуля, содержащий таблицу искомых ресурсов сообщений. Если аргумент lpSource имеет нулевое значение, ищется файл отображения процесса текущего приложения. Этот флаг несовместим с флагом FORMAT_MESSAGE_FROM_STRING.

• FORMAT_MESSAGE_FROM_SYSTEM — указывает на то, что функция должна произвести поиск в системной таблице ресурсов сообщений по номеру сообщения. Если одновременно с этим флагом устанавливается флаг FORMAT_MESSAGE_FROM_HMODULE, то поиск в системной таблице ресурсов осуществляется в том случае, если данное сообщение не найдено в модуле, определённом в аргументе lpSource. Этот флаг несовместим с флагом FORMAT_MESSAGE_FROM_STRING. Установка данного флага позволяет приложению использовать возвращаемое значение функции GetLastError для поиска связанного с ошибкой текстового сообщения.

• FORMAT_MESSAGE_ARGUMENT_ARRAY — в аргументе Arguments содержится не объект структуры va_list, а указатель на 32-разрядную величину, представляющую аргументы.

Младший байт аргумента dwFlags может содержать длину форматированной строки текста. Для получения этой величины может быть использована битовая маска FORMAT_MESSAGE_MAX_WIDTH_MASK. Если младший байт аргумента dwFlags имеет нулевое значение, на длину строки не накладывается никаких ограничений. Функция сохраняет символы перевода строки, содержащиеся в исходном сообщении. Если младший байт аргумента dwFlags имеет ненулевое значение, отличное от FORMAT_MESSAGE_MAX_WIDTH_MASK, то это значение определяет максимальное число символов в строке. Функция игнорирует регулярные символы перевода строки в тексте определения сообщения. Функция никогда не разрывает строку, ограниченную пробелами, символом перевода строки. Она сохраняет в выходном буфере специально установленные символы перевода строки из текста определения сообщения. Для специальной установки символа перевода строки используется последовательность символов %n escape. Если младший байт аргумента dwFlags имеет значение FORMAT_MESSAGE_MAX_WIDTH_MASK, то функция игнорирует регулярные символы перевода строки в тексте определения сообщения. Она сохраняет в выходном буфере специально установленные символы перевода строки из текста определения сообщения и не устанавливает новые символы перевода строки.

0. lpSource — определяет источник информации об определении сообщения. Тип этого аргумента зависит от значения аргумента dwFlags. Если в аргументе dwFlags установлен флаг FORMAT_MESSAGE_FROM_HMODULE, то аргумент lpSource имеет тип hModule и содержит дескриптор модуля, содержащего таблицу сообщений, в которой будет производиться поиск. Если в аргументе dwFlags установлен флаг FORMAT_MESSAGE_FROM_STRING, то аргумент lpSource имеет тип LPTSTR и содержит указатель на неформатированный текст сообщения. Он будет просмотрен на предмет нахождения в нём последовательностей автозамены и соответствующим образом отформатирован. Если в аргументе dwFlags не установлен ни один из этих флагов, то значение аргумента lpSource игнорируется.

1. dwMessageId — содержит 32-разрядный идентификатор сообщения для требуемого сообщения. Если в аргументе dwFlags установлен флаг FORMAT_MESSAGE_FROM_STRING, то значение данного аргумента игнорируется.

2. dwLanguageId — содержит 32-разрядный идентификатор языка для требуемого сообщения. Если в аргументе dwFlags установлен флаг FORMAT_MESSAGE_FROM_STRING, то значение данного аргумента игнорируется.

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

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

5. lpBuffer — указатель на буфер, содержащий форматированное (и заканчивающееся нулём) сообщение. Если в аргументе dwFlags установлен флаг FORMAT_MESSAGE_ALLOCATE_BUFFER, функция создаёт этот буфер с использованием функции LocalAlloc, и помещает указатель на созданный буфер по адресу, указанному в переменной lpBuffer.

6. nSize — если в аргументе dwFlags не установлен флаг FORMAT_MESSAGE_ALLOCATE_BUFFER, этот аргумент содержит размер выходного буфера в байтах (версия ANSI) или символах (версия Unicode). Если флаг FORMAT_MESSAGE_ALLOCATE_BUFFER установлен, этот аргумент определяет минимальный размер создаваемого буфера в байтах или символах.

7. Arguments — указатель на массив 32-разрядных величин, используемый для задания последовательностей автозамены. Символ %1 в форматируемой строке соответствует первому элементу массива Arguments, символ %2 — второму элементу данного массива и т.д.

8. Интерпретация каждой из этих 32-разрядных величин зависит от информации о форматировании последовательностей автозамены, содержащейся в определении сообщения. По умолчанию каждое из этих значений рассматривается как указатель на заканчивающуюся нулём строку.

9. По умолчанию аргумент Arguments имеет тип va_list*, определяющий различное число аргументов, зависящих от языка и реализации. Если приложение не использует тип va_list*, то в аргументе dwFlags устанавливается флаг FORMAT_MESSAGE_ARGUMENT_ARRAY и значение аргумента Arguments трактуется в описанном выше смысле.

Примечание

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

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

LPVOID lpMsgBuf;

FormatMessage(

FORMAT_MESSAGE_ALLOCATE_BUFFER |

FORMAT_MESSAGE_FROM_SYSTEM |

FORMAT_MESSAGE_IGNORE_INSERTS,

NULL,

GetLastError(),

MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),//Язык, используемый по умолчанию

(LPTSTR) &lpMsgBuf,

0,

NULL

);

// Обработка полученной строки.

// ...

// Вывод строки на экран.

MessageBox( NULL, (LPCTSTR)lpMsgBuf, "Error", MB_OK | MB_ICONINFORMATION );

// Освобождение буфера.

LocalFree( lpMsgBuf );

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

• %0 — завершает текст сообщения, не добавляя символа перевода строки. Эта управляющая последовательность используется для создания длинных строк или для завершения всего сообщения без добавления нового символа перевода строки.

• %n!printf format string! — определяет позицию автозамены. Величина n может принимать значение от 1 до 99. Строка форматирования printf (которая должна выделяться восклицательными знаками) не является обязательной и, если она не определена, то вместо неё по умолчанию подставляется строка !s!.

• Строка форматирования printf может содержать символ * вместо любого из компонентов точности или ширины. Если символ * указан для одного из этих компонентов, то функция FormatMessage использует автозамену %n+1, если же символ * указан для обоих компонентов, то используется автозамена %n+2.

• Для чисел с плавающей запятой формат printf не используются спецификаторы e, E, f и g. Для того чтобы обойти это ограничение, можно воспользоваться функцией sprintf для форматирования числа в формате с плавающей запятой, поместить форматированную строку во временный буфер, а затем использовать этот буфер в последовательности автозамены.

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

• %% — один знак процента в форматированной строке,

• %n — знак обязательного перевода строки, если строка форматирования оказалась в конце строки. Этот символ используется для форматирования текста, размещаемого в пространстве, ограниченном по ширине.

• %space — пробел в форматированном тексте. Этот символ используется для внесения в строку дополнительных пробелов.

• %. — отдельная точка в форматированном тексте. Этот символ используется для помещения точки в начало строки, не прерывая определения текста сообщения.

• %! — отдельный восклицательный знак в форматированном тексте. Этот символ используется для помещения восклицательного знака в начале строки автозамены, не принимаемого по ошибке за начало строки форматирования printf.

Описание данной функции содержится в файле заголовка winbase.h. При работе с данной функцией следует включить в проект библиотеку kernel32.lib.