FormatMessage-Funktion Die FormatMessage-Funktion formatiert einen Meldungsstring, bei welchem es sich auch um einen String aus der Systemtabelle handeln kann...
Betriebssystem:  Win95, Win98, WinNT, Win2000, WinME	Views:  13.831

Beschreibung:
Die FormatMessage-Funktion formatiert einen Meldungsstring, bei welchem es sich auch um einen String aus der Systemtabelle handeln kann oder von einem geladenen Modul mit einer internen Message-Tabelle. Weiterhin kann man der Funktion Parameter übergeben, welche dann anstelle der Platzhalter (zb. 1%, 2%, etc.) eingefügt werden. Die Funktion findet den entsprechenden Message-String anhand der übergebenden Sprach-Konstanten.

Deklaration:

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

Parameter:

dwFlags	Erwartet eine oder mehrere der folgenden Konstanten, damit die Funktion weiß, woher sie den Message-String bekommen kann. Mehrere Konstanten können durch den "Or" Operator kombiniert werden. FORMAT_MESSAGE_ALLOCATE_BUFFER Legt fest, daß die Funktion autom. einem dem Text entsprechend großen Puffer reserviert. In diesem Fallist lpBuffer ein Pointer zu dem Message-String. Verwenden Sie die LocalFree-Funktion, um den Speicher des Puffers wieder frei zu geben.   FORMAT_MESSAGE_IGNORE_INSERTS Legt fest, daß keinerlei Platzhalter ersetzt werden sollen. In diesem Fall kann bei "Arguments" eine "0" übergeben werden.   FORMAT_MESSAGE_FROM_STRING Legt fest, daß die Funktion den Message-String aus dem Puffer "lpBuffer" holt. In dem Fall sollte nSize die Größe des Puffers in Bytes angeben. Diese Option kann nicht mit "FORMAT_MESSAGE_FROM_HMODULE" oder "FORMAT_MESSAGE_FROM_SYSTEM" kombiniert werden.   FORMAT_MESSAGE_FROM_HMODULE Legt fest, daß es sich bei "lpSource" um einen Handle zu einem Modul handelt, welches die Messagetabelle beinhaltet. Ist "lpSource" NULL, werden die eigenen Module nach einer Messagestring-Tabelle durchsucht. Dies Option kann nicht mit "FORMAT_MESSAGE_FROM_STRING" kombiniert werden.   FORMAT_MESSAGE_FROM_SYSTEM Legt fest, daß die Funktion die System-Tabellen nach einem geeignetem Eintrag durchsuchen soll. In Verbindung mit "FORMAT_MESSAGE_FROM_HMODULE" werden zunächst die programmeigenen Module durchsucht. Ist das Ergebnis erfolglos, werden die System-Tabellen durchsucht. Diese Option kann dazu benutzt werden um den Fehlertext eines Fehler-Rückgabewertes zu bekommen.   FORMAT_MESSAGE_ARGUMENT_ARRAY Teilt der Funktion mit, daß für "Arguments" ein Pointer auf ein Array mit Platzhalter-Strings übergeben wird.   FORMAT_MESSAGE_MAX_WIDTH_MASK Wenn diese Konstante gesetzt ist, kann das Low-Order Byte der dwFlags-Option die Maximallänge an Zeichen der Massage haben. Ist dies der Fall, so wird jedesmal ein "vbCrLf"in die Message eingefügt wenn die angegebene maximale Weite der Message droht länger zu werden. Das Low-Order Byte sollte ungleich "FORMAT_MESSAGE_MAX_WIDTH_MASK" sein. Ist das Low-OrderByte "0" so werden keine zusätzlichen Zeilenumbrüche eingefügt. Trotzdem können in der MessageZeilenumbrüche vorkommen, wenn sie in dem Message-String definiert sind. Ist das Low-Order Byte"FORMAT_MESSAGE_MAX_WIDTH_MASK, werden alle Zeilenumbrüch aus dem Message-String entfernt.   dwFlags Konstanten Deklaration: Const FORMAT_MESSAGE_ALLOCATE_BUFFER = &H100 Const FORMAT_MESSAGE_IGNORE_INSERTS = &H200 Const FORMAT_MESSAGE_FROM_STRING = &H400 Const FORMAT_MESSAGE_FROM_SYSTEM = &H1000 Const FORMAT_MESSAGE_FROM_HMODULE = &H800 Const FORMAT_MESSAGE_ARGUMENT_ARRAY = &H2000 Const FORMAT_MESSAGE_MAX_WIDTH_MASK = &HFF
lpSource	Ist der Parameter "FORMAT_MESSAGE_FROM_STRING gesetz worden, so muß hier ein String übergeben werden. Sollte "FORMAT_MESSAGE_FROM_HMODULE" übergeben worden sein, so muß es sich bei dieser Option um ein Handle zu einem Modul handeln. Ist "FORMAT_MESSAGE_FROM_SYSTEM" übergeben worden, so kann lpSource "0" sein.
dwMessageId	Beschreibt eine Message-ID in einer Message-Tabelle. Diese Option wird ignoriert, falls die "FORMAT_MESSAGE_FROM_SYSTEM"-Konstante in "dwFlags" gesetzt worden ist. Die MessageID kann eine der Fehler-Konstanten sein.
dwLanguageId	Teilt der Funktion mit, in welcher Sprache die Massage aus der Message-Tabelle geholt werden soll. Wird die Sprache nicht gefunden, so gibt die Funktion "ERROR_RESOURCE_LANG_NOT_FOUND" zurück. Wird eine "0" übergeben so sucht die Funktion nacheinander die "Thread, Standard, System" und die "US Englischen" Sprachen durch, bis ein Message-String zu der übergebenden Message-ID gefunden worden ist. Findet die Funktion keine der entsprechenden Sprachen, so wird "ERROR_RESOURCE_LANG_NOT_FOUND" zurückgegeben. Die zu übergebende Sprach-ID ist eine Kombination aus 2 verschiedenen Sprach-Konstanten. dwLanguageId Konstanten Deklaration: ' Hauptsprachen Const LANG_BULGARIAN = &H2 'Bulgarisch Const LANG_CHINESE = &H4 'Chinesisch Const LANG_CROATIAN = &H1A 'Kroatisch Const LANG_CZECH = &H5 'Tschechisch Const LANG_DANISH = &H6 'Dänisch Const LANG_DUTCH = &H13 'Holländisch Const LANG_ENGLISH = &H9 'Englisch Const LANG_FINNISH = &HB 'Finnisch Const LANG_FRENCH = &HC 'Französisch Const LANG_GERMAN = &H7 'Deutsch Const LANG_GREEK = &H8 'Grichisch Const LANG_HUNGARIAN = &HE 'Ungarisch Const LANG_ICELANDIC = &HF '?? Const LANG_ITALIAN = &H10 'Italienisch Const LANG_JAPANESE = &H11 'Japanisch Const LANG_KOREAN = &H12 'Koreanisch Const LANG_NEUTRAL = &H0 'Neutral Const LANG_NORWEGIAN = &H14 'Norwegisch Const LANG_POLISH = &H15 'Polnisch Const LANG_PORTUGUESE = &H16 'Portugisisch Const LANG_ROMANIAN = &H18 'Romänisch Const LANG_RUSSIAN = &H19 'Russisch Const LANG_SLOVAK = &H1B 'Slovakisch Const LANG_SLOVENIAN = &H24 'Slovenisch Const LANG_SPANISH = &HA 'Spanisch Const LANG_SWEDISH = &H1D 'Schwedisch Const LANG_TURKISH = &H1F 'Türkisch   ' Untersprachen Const SUBLANG_CHINESE_HONGKONG = &H1D 'Chinesisch (Hong Kong) Const SUBLANG_CHINESE_SIMPLIFIED = &H2 'Chinesisch (China) Const SUBLANG_CHINESE_SINGAPORE = &H4 'Chinesisch (Signapur) Const SUBLANG_CHINESE_TRADITIONAL = &H1 'Chinesisch (Taiwan) Const SUBLANG_DEFAULT = &H1 'Standard Const SUBLANG_DUTCH = &H1 'Holländisch Const SUBLANG_DUTCH_BELGIAN = &H2 'Holländisch (Belgien) Const SUBLANG_ENGLISH_AUS = &H3 'Englisch (Australien) Const SUBLANG_ENGLISH_CAN = &H4 'Englisch (Kanada) Const SUBLANG_ENGLISH_EIRE = &H6 'Englisch (Irland) Const SUBLANG_ENGLISH_NZ = &H5 'Englisch (Neu Seeland) Const SUBLANG_ENGLISH_UK = &H2 'Englisch (UK) Const SUBLANG_ENGLISH_US = &H1 'Englisch (USA) Const SUBLANG_FRENCH = &H1 'Französisch Const SUBLANG_FRENCH_BELGIAN = &H2 'Französisch (Belgien) Const SUBLANG_FRENCH_CANADIAN = &H3 'Französisch (Kanada) Const SUBLANG_FRENCH_SWISS = &H4 'Französisch (Schweiz) Const SUBLANG_GERMAN = &H1 'Deutsch Const SUBLANG_GERMAN_AUSTRIAN = &H3 'Deutsch (Österreich) Const SUBLANG_GERMAN_SWISS = &H2 'Deutsch (Schweiz) Const SUBLANG_ITALIAN = &H1 'Italienisch Const SUBLANG_ITALIAN_SWISS = &H2 'Italienisch (Schweiz) Const SUBLANG_NEUTRAL = &H0 'Neutral (Standard) Const SUBLANG_NORWEGIAN_BOKMAL = &H1 'Norwegisch (Bokma) Const SUBLANG_NORWEGIAN_NYNORSK = &H2 'Norwegisch (Nynorsk) Const SUBLANG_PORTUGUESE = &H2 'Portugisisch Const SUBLANG_PORTUGUESE_BRAZILIAN = &H1 'Portugisisch (Brasilianisch) Const SUBLANG_SPANISH = &H1 'Spanisch (Castilian) Const SUBLANG_SPANISH_MEXICAN = &H2 'Spanisch (Mexikanisch) Const SUBLANG_SPANISH_MODERN = &H3 'Spanisch (Modern) Const SUBLANG_SYS_DEFAULT = &H2 'System Standard ()   ' Beispiel: LangID bekommen   ' Liefert die Standard Sprachen-ID LangID = LANG_NEUTRAL Or (SUBLANG_DEFAULT * 1024)
lpBuffer	Hier wird ein ein leerer Puffer-String erwartet. Wird die "FORMAT_MESSAGE_ALLOCATE_BUFFER"-Option gesetzt, wird der Puffer mit einem Pointer zu dem eigentlichem Puffer gefüllt. Ist dies der Fall, geben sie den Pufferspeicher wieder mit der LocalFree-Funktion frei.
nSize	Wird die "FORMAT_MESSAGE_ALLOCATE_BUFFER"-Option nicht gesetzt, so muß hier die Größe des Puffers in Bytes angegeben werden. Andernfall muß hier die minimale Länge des Puffers angegeben werden.
Arguments	Wenn Sie die Option "FORMAT_MESSAGE_ARGUMENT_ARRAY" gesetzt haben, erwartet "Arguments" einen Pointer zu einem Array. Ist dies nicht der Fall, so muß man hier einen Pointer zu einem String angeben, in welchem alle Platzhalter-Ersetzer mit einem "|" Zeichen getrennt sind. Bei Windows 95 sollte keiner diese Strings länger als 1023 Zeichen sein. Die Anordnung der Argumente sieht so aus, daß einige Messages einen String wie z.B. "Bitte Legen sie Diskette %1 ein" haben. Der String in dem Array mit dem Index "0" müsste dann die Zeichenfolge beinhalten, mit der "%1" ersetzt werden soll. Hat eine Massage mehrere Platzhalter, so müssen mehrere Indexfelder in einem Array deklariert werden. Ansonsten wird die Entwicklungsumgebung (VB6) oder auch das Programm eventuell abstürzen.

Rückgabewert:
Ist die Funktion erfolgreich, so enthält der Rückgabewert die Länge des Message-String (abzgl. des "vbNullChar"-Zeichens). War der Funktionsaufruf erfolglos, wird 0 zurückgegeben. Wird eine Sprache bezüglich der Sprachübergabe nicht gefunden, so ist der Rückgabewert "ERROR_RESOURCE_LANG_NOT_FOUND".

Const ERROR_RESOURCE_LANG_NOT_FOUND = 1815&

Beispiel:

Private 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 Konstanten
Private Const FORMAT_MESSAGE_ALLOCATE_BUFFER = &H100
Private Const FORMAT_MESSAGE_IGNORE_INSERTS = &H200
Private Const FORMAT_MESSAGE_FROM_STRING = &H400
Private Const FORMAT_MESSAGE_FROM_SYSTEM = &H1000
Private Const FORMAT_MESSAGE_FROM_HMODULE = &H900
Private Const FORMAT_MESSAGE_ARGUMENT_ARRAY = &H2000
Private Const FORMAT_MESSAGE_MAX_WIDTH_MASK = &HFF
 
' FormatMessage Rückgabe-Konstante
Private Const ERROR_RESOURCE_LANG_NOT_FOUND = 1815&
 
' Einige FormatMessage Sprachkonstanten
Private Const LANG_NEUTRAL = &H0
Private Const LANG_GERMAN = &H7
Private Const LANG_FRENCH = &HC
Private Const LANG_ENGLISH = &H9
 
' Einige FormatMessage Sub-Sprach-Konstanten
Private Const SUBLANG_DEFAULT = &H1
Private Const SUBLANG_FRENCH = &H1
Private Const SUBLANG_ENGLISH_US = &H1
Private Const SUBLANG_GERMAN = &H1
 
' Eine der Get-/Set- LastError Konstanten
Private Const ERROR_ACCESS_DENIED = 5& ' Zugriff verweigert

Private Sub Command1_Click() 
  Dim Flags As Long, Puffer As String 
  Dim Retval As Long, Sprache As Long 
  Dim Fehler As Long 
 
  ' Den Fehlertext mit FormatMessage in der Standardsprache ausgeben 
  Flags = FORMAT_MESSAGE_FROM_SYSTEM Or FORMAT_MESSAGE_IGNORE_INSERTS 
  Sprache = LANG_NEUTRAL Or (SUBLANG_DEFAULT * 1024) 
  Puffer = Space(256) ' Puffergröße festlegen
  Fehler = ERROR_ACCESS_DENIED ' Von dem Fehler wollen wir den passenden Fehlertext 
 
  Retval = FormatMessage( Flags, 0&, Fehler, Sprache, Puffer, Len(Puffer), 0&) 
 
  ' Ist FormatMessage erfolgreich? Wenn ja, dann Fehlertext ausgeben
  If Retval = 0 Then 
    MsgBox "Ein Fehler ist bei dem ermitteln des Fehlertextes aufgetreten.", vbCritical, "Fehler" 
  Else 
    Debug.Print Left$(Puffer, Retval) & vbCrLf 
  End If 
End Sub