FormatMessage

[funkcja] Formatuje daną wiadomość zgodnie z podanymi wytycznymi.

Składnia

#include <windows.h>

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

Argumenty

Argument Opis

dwFlags

Opcje formatowania, opisujące również jak interpretować argument lpSource. Młodszy bajt z dwFlags określa, jak funkcja ma przerywać linie w buforze wyjściowym. Może on również określać maksymalną szerokość danej linii. Ten argument może przyjąć jedną lub więcej następujących wartości:

FORMAT_MESSAGE_ALLOCATE_BUFFER (0x00000100)
Funkcja zaalokuje bufor wystarczająco duży, aby przechować sformatowaną wiadomość, i umieści wskaźnik do zaalokowanego bufora w argumencie lpBuffer. W tym wypadku argument lpBuffer musi być wskaźnikiem na typ LPTSTR, czyli należy go na ten typ rzutować (Dla przykładu:

( LPTSTR ) & lpBuffer

). Argument nSize określa minimalną liczbę znaków do alokacji w wyjściowym buforze. Po wywołaniu funkcji FormatMessage należy użyć funkcji LocalFree, kiedy bufor z danymi nie będzie już potrzebny.

Windows Vista/Windows Server 2008 i późniejsze:
Jeśli długość sformatowanej wiadomości przekracza 128 KB, funkcja FormatMessage zakończy swoje działanie niepowodzeniem, a funkcja _{» WinAPI ♦}GetLastError zwróci ERROR_MORE_DATA.

FORMAT_MESSAGE_ARGUMENT_ARRAY (0x00002000)
Argument Arguments nie jest strukturą va_list, ale jest wskaźnikiem na tablicę zawierającą argumenty. Ta flaga nie może być użyta z 64-bitowymi wartościami typu integer. Jeśli korzystasz z takiej wartości, musisz użyć struktury va_list.
FORMAT_MESSAGE_FROM_HMODULE (0x00000800)
Argument lpSource jest uchwytem do modułu zawierającego tablicę wiadomości zasobów do przeszukania. Jeśli lpSource będzie równy NULL, obraz pliku aktualnego procesu będzie przeszukany. Ta flaga nie może być użyta z FORMAT_MESSAGE_FROM_STRING. Jeśli moduł nie ma tablicy wiadomości zasobów, Funkcja zawiedzie w ERROR_RESOURCE_TYPE_NOT_FOUND.
FORMAT_MESSAGE_FROM_STRING (0x00000400)
Argument lpSource jest wskaźnikiem na tekst, który zawiera definicję wiadomości. Może ona zawierać wstawione sekwencje, właśnie jako wiadomość tekstowa w tablicy wiadomości zasobów. Ta flaga nie może być użyta z FORMAT_MESSAGE_FROM_HMODULE ani z FORMAT_MESSAGE_FROM_SYSTEM.
FORMAT_MESSAGE_FROM_SYSTEM (0x00001000)
Funkcja przeszuka systemową tablicę wiadomości zasobów w celu znalezienia szukanej wiadomości. Jeśli ta flaga będzie użyta z FORMAT_MESSAGE_FROM_HMODULE, funkcja przeszuka systemową tablicę wiadomości, jeżeli wiadomość nie zostanie znaleziona w module podanym w argumencie lpSource. Ta flaga nie może być użyta z FORMAT_MESSAGE_FROM_STRING. Aplikacja może podać wartość zwróconą przez _{» WinAPI ♦}GetLastError, aby odebrać tekst wiadomości zdefiniowanego w systemie błędu.
FORMAT_MESSAGE_IGNORE_INSERTS (0x00000200)
Wstawione sekwencje w definicji wiadomości będą ignorowane i wstawione do bufora wyjściowego w niezmienionej postaci. Flaga jest użyteczna dla wiadomości, która ma być sformatowana później. Jeśli ta flaga jest ustawiona, argument Arguments jest ignorowany.

Młodszy bajt z dwFlags może określać maksymalną szerokość sformatowanej linii. Dopuszczalne jest użycie następujących wartości:

0
Maksymalna szerokość linii nie jest określona.
FORMAT_MESSAGE_MAX_WIDTH_MASK (0x000000FF)
Funkcja ignoruje regularne przerwania linii w tekstowej definicji wiadomości. Funkcja nie generuje przerwań nowych linii.

Jeśli ustawiona będzie inna wartość, będzie ona określać maksymalną liczbę znaków w linii.

lpSource

Położenie definicji waidomości. Typ argumentu zależy od ustawień dwFlags.

FORMAT_MESSAGE_FROM_HMODULE (0x00000800)
Uchwyt do modułu zawiera tablicę wiadomości do przeszukania.
FORMAT_MESSAGE_FROM_STRING (0x00000400)
Wskaźnik na tekst, który zawiera niesformatowaną treść wiadomości.

dwMessageId Identyfikator wiadomości. Jeśli dwFlags zawiera FORMAT_MESSAGE_FROM_STRING, argument jest ignorowany.

dwLanguageId

Identyfikator języka dla wiadomości. Jeśli dwFlags zawiera FORMAT_MESSAGE_FROM_STRING, argument jest ignorowany.

Jeżeli podasz LANGID w tym argumencie, funkcja zwróci wiadomość tylko dla danego LANGID. Jeśli funkcja nie może znaleźć wiadomości, ustawia błąd (może być pobrany za pomocą _{» WinAPI ♦}GetLastError) ERROR_RESOURCE_LANG_NOT_FOUND. Jeśli podasz 0, funkcja FormatMessage przeszuka wiadomości w następującym porządku:

Język neutralny
LANGID wątku
domyślny LANGID dla danego użytkownika
domyślny LANGID dla systemu
Angielski

lpBuffer Wskaźnik na bufor, który odbierze sformatowaną wiadomość. Jeśli dwFlags zawiera FORMAT_MESSAGE_ALLOCATE_BUFFER, funkcja zaalokuje bufor używając funkcji LocalAlloc. Rozmiar bufora nie może przekroczyć 64 KB.

nSize Jeśli flaga FORMAT_MESSAGE_ALLOCATE_BUFFER nie jest ustawiona, ten arhument określa rozmiar bufora wyjściowego. Jeśli jednak jest ustawiona, argument określa minimalną liczbę znaków do zaalokowania. Bufor wyjściowy nie może być większy niż 64 KB.

Arguments Tablica wartości, które będą użyte do wstawienia ich w sformatowanej wiadomości. Znak %1 w argumencie lpSource oznacza pierwszą wartość z tablicy Arguments, %2 drugą, itd.

Jeśli nie używasz va_list, ustaw flagę FORMAT_MESSAGE_ARGUMENT_ARRAY i podaj tablicę wartości DWORD_PTR.

Zwracana wartość

Funkcja zwraca numer znaków zapisanych w buforze wyjściowym, wyłączając kończący znak NULL.

Opis szczegółowy

Funkcja FormatMessage formatuje daną wiadomość zgodnie z podanymi wytycznymi, po czym sformatowaną wiadomość kopiuje do bufora wyjściowego. Może być użyta do odebrania tekstowej informacji o błędzie ustawionej funkcją SetLastError.

W argumencie lpSource można stosować następujące znaki:

Łańcuch	Znaczenie
%0	Przerywa tekst, bez wstawiania znaku nowej linii.
%n!format string!	Określa wygląd otrzymanego tekstu, użycie %1 oznacza odwołanie się do pierwszego argumentu, %2 do drugiego, itd. Aby określić długość i precyzję, użyj znaku *.

Inny znak poprzedzony znakiem procenta będzie sformatowany bez znaku %. Oto kilka przykładów:

Łańcuch	Rezultat
%%	Znak procenta
%space	Pojedyncza spacja
%.	Pojedyncza kropka
%!	Pojedynczy wykrzyknik
%n	Znak nowej linii
%r	Znak powrotu karetki
%t	Pojedynczy tabulator

Przykładowy kod pokazuje, jak można pobrać tekstowe określenie błędu w danym (domyślnym) języku i wyświetlić je funkcją MessageBox.:

void AlertLastError()
{
LPVOID lpBuf;
FormatMessage( FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, GetLastError(), MAKELANGID( LANG_NEUTRAL, SUBLANG_DEFAULT ),( LPTSTR ) & lpBuf, 1024, NULL );
MessageBox( 0,( char * ) lpBuf, 0, 0 );
LocalFree( lpBuf );
}

Wymagania

Minimalny obsługiwany klient	Windows 2000 Professional
Minimalny obsługiwany serwer	Windows 2000 Server
Nagłówek	Winbase.h (wewnątrz Windows.h)
Biblioteka	Kernel32.lib
DLL	Kernel32.dll
Nazwy Unicode i ANSI	FormatMessageW (Unicode) i FormatMessageA (ANSI)

Linki zewnętrzne

http://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx

Wszystkie teksty są chronione prawami autorskimi. Kopiowanie lub rozpowszechnianie treści poza niniejszym serwisem jest zabronione.

Powyższe ograniczenie nie dotyczy autora opracowania, któremu przysługuje prawo do rozpowszechniania własnego tekstu wedle własnego uznania.