GetFileMUIPath-Funktion (winnls.h)

Artikel
03/04/2024

Ruft den Pfad zu allen sprachspezifischen Ressourcendateien ab, die der angegebenen LN-Datei zugeordnet sind. Die Anwendung muss diese Funktion wiederholt aufrufen, um den Pfad für jede Ressourcendatei abzurufen.

Syntax

BOOL GetFileMUIPath(
  [in]                DWORD      dwFlags,
  [in]                PCWSTR     pcwszFilePath,
  [in, out, optional] PWSTR      pwszLanguage,
  [in, out]           PULONG     pcchLanguage,
  [out, optional]     PWSTR      pwszFileMUIPath,
  [in, out]           PULONG     pcchFileMUIPath,
  [in, out]           PULONGLONG pululEnumerator
);

Parameter

[in] dwFlags

Flags zur Identifizierung des Sprachformats und der Filterung. Die folgenden Flags geben das Format der sprache an, die durch pwszLanguage angegeben wird. Die Flags schließen sich gegenseitig aus, und der Standardwert ist MUI_LANGUAGE_NAME.

Wert	Bedeutung
MUI_LANGUAGE_ID	Rufen Sie die Sprachzeichenfolge im Sprachbezeichnerformat ab .
MUI_LANGUAGE_NAME	Rufen Sie die Sprachzeichenfolge im Format des Sprachnamens ab.

Die folgenden Flags geben die Filterung für die Funktion an, die zum Suchen sprachspezifischer Ressourcendateien verwendet werden soll, wenn pwszLanguage auf NULL festgelegt ist. Die Filterflags schließen sich gegenseitig aus, und der Standardwert ist MUI_USER_PREFERRED_UI_LANGUAGES.

Wert	Bedeutung
MUI_USE_SEARCH_ALL_LANGUAGES	Rufen Sie alle sprachspezifischen Ressourcendateien für den durch pcwszFilePath angegebenen Pfad ab, ohne die Dateilizenzierung in Betracht zu ziehen. Dieses Flag ist nur relevant, wenn die Anwendung eine NULL-Zeichenfolge für pwszLanguage bereitstellt.
MUI_USER_PREFERRED_UI_LANGUAGES	Rufen Sie nur die Dateien ab, die Sprachen in der Fallbackliste implementieren. Aufeinanderfolgende Aufrufe listet die aufeinander folgenden Fallbacks in der entsprechenden Reihenfolge auf. Die erste Datei, die durch den Ausgabewert von pcchFileMUIPath angegeben wird, sollte am besten geeignet sein. Dieses Flag ist nur relevant, wenn die Anwendung eine NULL-Zeichenfolge für pwszLanguage bereitstellt.
MUI_USE_INSTALLED_LANGUAGES	Rufen Sie nur die Dateien für die auf dem Computer installierten Sprachen ab. Dieses Flag ist nur relevant, wenn die Anwendung eine NULL-Zeichenfolge für pwszLanguage bereitstellt.

Mit den folgenden Flags kann der Benutzer den Dateityp angeben, der von pcwszFilePath angegeben wird, damit die Funktion bestimmen kann, ob sie dem Dateinamen ".mui" hinzufügen muss. Die Flags schließen sich gegenseitig aus. Wenn die Anwendung beide Flags übergibt, schlägt die Funktion fehl. Wenn die Anwendung keines der Flags übergibt, überprüft die Funktion die Datei im Stammordner, um den Dateityp zu überprüfen und die Benennung der Datei festzulegen.

Wert	Bedeutung
MUI_LANG_NEUTRAL_PE_FILE	Überprüfen Sie nicht die in pcwszFilePath übergebene Datei, und fügen Sie ".mui" vor der Verarbeitung an den Dateinamen an. Ändern Sie beispielsweise Abc.exe in Abc.exe.mui.
MUI_NON_LANG_NEUTRAL_FILE	Überprüfen Sie die in pcwszFilePath übergebene Datei nicht, und fügen Sie vor der Verarbeitung nicht ".mui" an den Dateinamen an. Verwenden Sie beispielsweise Abc.txt oder Abc.chm.

[in] pcwszFilePath

Zeiger auf eine NULL-endende Zeichenfolge, die einen Dateipfad angibt. Der Pfad ist entweder für eine vorhandene LN-Datei oder für eine Datei wie eine .txt-, INF- oder MSC-Datei. Wenn es sich bei der Datei um eine LN-Datei handelt, sucht die Funktion nach Dateien, die die zugeordneten sprachspezifischen Ressourcen enthalten. Für alle anderen Dateitypen sucht die Funktion Nach Dateien, die genau dem angegebenen Dateinamen und Pfad entsprechen. Ihre Anwendung kann das Verhalten der Dateitypüberprüfung mit dem flag MUI_LANG_NEUTRAL_PE_FILE oder MUI_NON_LANG_NEUTRAL_FILE überschreiben. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

Hinweis Der angegebene Dateipfad kann ein Netzwerkpfad sein, z. B. "\\computername\c$\windows\system32\notepad.exe".

[in, out, optional] pwszLanguage

Zeiger auf einen Puffer, der eine Sprachzeichenfolge enthält. Bei der Eingabe enthält dieser Puffer den Sprachbezeichner oder Sprachnamen, für den die Anwendung sprachspezifische Ressourcendateien finden soll, abhängig von den Einstellungen von dwFlags. Bei erfolgreicher Rückgabe der Funktion enthält dieser Parameter die Sprache der sprachspezifischen Ressourcendatei, die die Funktion gefunden hat.

Alternativ kann die Anwendung diesen Parameter auf NULL festlegen, wobei der Wert, auf den von pcchLanguage verwiesen wird, auf 0 festgelegt ist. In diesem Fall ruft die Funktion die erforderliche Puffergröße in pcchLanguage ab.

[in, out] pcchLanguage

Zeiger auf die Puffergröße in Zeichen für die durch pwszLanguage angegebene Sprachzeichenfolge. Wenn die Anwendung den Wert, auf den dieser Parameter verweist, auf 0 festlegt und NULL für pwszLanguage übergibt, wird die erforderliche Puffergröße in pcchLanguage zurückgegeben, und die zurückgegebene Puffergröße wird immer LOCALE_NAME_MAX_LENGTH, da die Funktion in der Regel mehrmals hintereinander aufgerufen wird. Die Funktion kann nicht die genaue Größe des Sprachnamens für alle aufeinander folgenden Aufrufe ermitteln und den Puffer bei nachfolgenden Aufrufen nicht erweitern. Somit ist LOCALE_NAME_MAX_LENGTH das einzige sichere Maximum.

[out, optional] pwszFileMUIPath

Zeiger auf einen Puffer, der den Pfad zur sprachspezifischen Ressourcendatei enthält. Es wird dringend empfohlen, diesen Puffer MAX_PATH zuzuweisen.

Alternativ kann dieser Parameter NULL abrufen, wenn der Wert, auf den von pcchFileMUIPath verwiesen wird, auf 0 festgelegt ist. In diesem Fall ruft die Funktion die erforderliche Größe für den Dateipfadpuffer in pcchFileMUIPath ab.

[in, out] pcchFileMUIPath

Zeiger auf die Puffergröße in Zeichen für den durch pwszFileMUIPath angegebenen Dateipfad. Bei erfolgreicher Rückgabe der Funktion gibt dieser Parameter die Größe des abgerufenen Dateipfads an. Wenn die Anwendung den Wert, auf den dieser Parameter verweist, auf 0 festlegt, ruft die Funktion NULL für pwszFileMUIPath ab, die erforderliche Puffergröße wird in pcchFileMUIPath zurückgegeben, und die zurückgegebene Puffergröße ist immer MAX_PATH, da die Funktion in der Regel mehrmals hintereinander aufgerufen wird. Die Funktion kann nicht die genaue Größe des Pfads für alle aufeinander folgenden Aufrufe ermitteln und den Puffer bei nachfolgenden Aufrufen nicht erweitern. Somit ist MAX_PATH das einzige sichere Maximum.

[in, out] pululEnumerator

Zeiger auf eine Enumerationsvariable. Wenn diese Funktion zum ersten Mal aufgerufen wird, sollte der Wert der Variablen 0 sein. Zwischen nachfolgenden Aufrufen sollte die Anwendung den Wert dieses Parameters nicht ändern. Nachdem die Funktion alle möglichen sprachspezifischen Ressourcendateipfade abgerufen hat, gibt sie FALSE zurück.

Rückgabewert

Gibt TRUE zurück, wenn dies erfolgreich war, oder andernfalls FALSE . Wenn die Funktion fehlschlägt, ändern sich die Ausgabeparameter nicht.

Um erweiterte Fehlerinformationen zu erhalten, kann die Anwendung GetLastError aufrufen, wodurch die folgenden Fehlercodes zurückgegeben werden können:

ERROR_INSUFFICIENT_BUFFER. Eine angegebene Puffergröße war nicht groß genug, oder sie wurde fälschlicherweise auf NULL festgelegt.
ERROR_NO_MORE_FILES. Es wurden keine weiteren Dateien verarbeitet.

Hinweise

Diese Funktion überprüft, ob sprachspezifische Ressourcendateien vorhanden sind, aber sie überprüft nicht, ob sie korrekt sind. Die Ressourcendateien müssen gemäß der unter Anwendungsbereitstellung erläuterten Speicherkonvention gespeichert werden.

Wenn der Aufruf dieser Funktion das flag MUI_LANGUAGE_ID angibt, muss die angegebene Sprachzeichenfolge

Verwenden Sie einen hexadezimalen Sprachbezeichner, der das führende 0x-Element nicht enthält und 4 Zeichen lang ist.

Beispielsweise sollte en-US als "0409" und en als "0009" übergeben werden. Die zurückgegebene Sprachzeichenfolge wird im

gleiches Format.

Wenn MUI_LANGUAGE_ID angegeben wird, muss jeder Hexadezimalwert in der angegebenen Sprachzeichenfolge einen tatsächlichen Sprachbezeichner darstellen. Insbesondere können die Werte, die den folgenden Gebietsschemas entsprechen, nicht angegeben werden:

Um enumerierte Informationen zu erhalten, sollte die Anwendung diese Funktion wiederholt aufrufen, bis false zurückgegeben wird, sodass der Inhalt von pululEnumerator zwischen den Aufrufen unverändert bleibt. Da jeder Aufruf den Pfad zu einer anderen sprachspezifischen Ressourcendatei abruft, muss die Anwendung den Sprachpuffer zwischen Aufrufen in eine leere Zeichenfolge löschen. Wenn die Anwendung dies nicht tut, hat der Eingabewert von pwszLanguage Vorrang vor der Einstellung von dwFlags.

In der Regel wird das Ressourcenladeprogramm verwendet, um Ressourcendateien zu suchen. Ihre Anwendung kann diese Funktion jedoch auch verwenden, um die Dateien zu suchen. Wenn der Eingabedateipfad für eine LN-Datei gilt, fügt die Funktion bei der Suche nach den entsprechenden sprachspezifischen Ressourcendateien das Suffix ".mui" an.

Die Funktion ruft beispielsweise die folgenden Dateien ab, wenn die Anwendung die Zeichenfolge "C:\mydir\Example1.dll" in pcwszFilePath als Stammdateipfad übergibt, wobei dwFlags auf MUI_LANGUAGE_NAME | MUI_USE_SEARCH_ALL_LANGUAGES:

C:\mydir\Example1.dll
- C:\mydir\en-US\Example1.dll.mui
- C:\mydir\ja-JP\Example1.dll.mui

Der erste Aufruf der Funktion legt pwszFileMUIPath auf "C:\mydir\en-US\Example1.dll.mui" fest. Der zweite Aufruf legt den Dateipfad auf "C:\mydir\ja-JP\Example1.dll.mui" fest. Die Funktion gibt FALSE zurück, wenn sie ein drittes Mal aufgerufen wird, und GetLastError gibt ERROR_NO_MORE_FILES zurück.

Wenn die durch pcwszFilePath angegebene Datei keine Ressourcenkonfigurationsdaten enthält oder die Datei nicht vorhanden ist, belässt die Funktion den Dateinamen unverändert, wenn sie nach den entsprechenden sprachspezifischen Ressourcendateien sucht.

Beispielsweise übergibt die Anwendung die Zeichenfolge "C:\mydir\Example2.txt" in pcwszFilePath als Stammdateipfad, wobei dwFlags auf MUI_LANGUAGE_NAME | MUI_USER_PREFERRED_UI_LANGUAGES. Betrachten wir den Fall, in dem die Benutzeroberflächensprachen (in der Reihenfolge) bevorzugt sind Katalanisch, "ca-ES" und Spanisch (Spanien), "es-ES", und wo die folgenden Dateien vorhanden sind:

(keine entsprechende Datei in C:\mydir)
- C:\mydir\en-US\Example2.txt
- C:\mydir\en\Example2.txt
- C:\mydir\es-ES\Example2.txt
- C:\mydir\es\Example2.txt
- C:\mydir\ja-JP\Example2.txt

Der erste Aufruf der Funktion bestimmt, dass keine Ressourcen für "ca-ES" oder für die neutrale Sprache "ca" vorhanden sind. Die Funktion versucht dann die nächste Option, "es-ES", für die eine Übereinstimmung gefunden werden kann. Vor der Rückgabe legt die Funktion pwszFileMUIPath auf "C:\mydir\es-ES\Example2.txt" fest. Ein zweiter Anwendungsaufruf der -Funktion setzt die Enumeration fort, indem pwszFileMUIPath auf "C:\mydir\es\Example2.txt" festgelegt wird.

Wenn es sich bei der Zieldatei und den zugeordneten Ressourcendateien tatsächlich um parallel aktivierte Assemblys handelt, kann GetFileMUIPath nicht zum Abrufen des Pfads zur Ressourcendatei verwendet werden. Weitere Informationen zur Verwendung von parallelen Assemblys mit MUI-Unterstützung finden Sie unter Verwenden von Assemblys mit einer mehrsprachigen Benutzeroberfläche .

C#-Signatur

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean GetFileMUIPath(
            System.UInt32 dwFlags,
            System.String pcwszFilePath,
            System.Text.StringBuilder pwszLanguage,
            ref System.UInt32 pcchLanguage,
            System.Text.StringBuilder pwszFileMUIPath,
            ref System.UInt32 pcchFileMUIPath,
            ref System.UInt64 pululEnumerator
            );

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winnls.h (windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll