Funzione GetFileMUIPath (winnls.h)

Articolo
03/08/2023

Recupera il percorso di tutti i file di risorse specifici della lingua associati al file LN fornito. L'applicazione deve chiamare ripetutamente questa funzione per ottenere il percorso per ogni file di risorse.

Sintassi

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
);

Parametri

[in] dwFlags

Flag che identificano il formato e il filtro della lingua. I flag seguenti specificano il formato della lingua indicata da pwszLanguage. I flag si escludono a vicenda e il valore predefinito è MUI_LANGUAGE_NAME.

Valore	Significato
MUI_LANGUAGE_ID	Recuperare la stringa di lingua nel formato dell'identificatore di lingua .
MUI_LANGUAGE_NAME	Recuperare la stringa di lingua nel formato del nome della lingua .

I flag seguenti specificano il filtro per la funzione da usare nell'individuazione di file di risorse specifici della lingua se pwszLanguage è impostato su NULL. I flag di filtro si escludono a vicenda e il valore predefinito è MUI_USER_PREFERRED_UI_LANGUAGES.

Valore	Significato
MUI_USE_SEARCH_ALL_LANGUAGES	Recuperare tutti i file di risorse specifici della lingua per il percorso indicato da pcwszFilePath, senza prendere in considerazione la licenza dei file. Questo flag è rilevante solo se l'applicazione fornisce una stringa Null per pwszLanguage.
MUI_USER_PREFERRED_UI_LANGUAGES	Recuperare solo i file che implementano le lingue nell'elenco di fallback. Le chiamate successive enumera i fallback successivi, nell'ordine appropriato. Il primo file indicato dal valore di output di pcchFileMUIPath deve essere il più adatto. Questo flag è rilevante solo se l'applicazione fornisce una stringa Null per pwszLanguage.
MUI_USE_INSTALLED_LANGUAGES	Recuperare solo i file per le lingue installate nel computer. Questo flag è rilevante solo se l'applicazione fornisce una stringa Null per pwszLanguage.

I flag seguenti consentono all'utente di indicare il tipo di file specificato da pcwszFilePath in modo che la funzione possa determinare se deve aggiungere ".mui" al nome del file. I flag si escludono a vicenda. Se l'applicazione passa entrambi i flag, la funzione ha esito negativo. Se l'applicazione non passa alcun flag, la funzione controlla il file nella cartella radice per verificare il tipo di file e decidere la denominazione dei file.

Valore	Significato
MUI_LANG_NEUTRAL_PE_FILE	Non verificare il file passato in pcwszFilePath e accodare ".mui" al nome del file prima dell'elaborazione. Ad esempio, modificare Abc.exe in Abc.exe.mui.
MUI_NON_LANG_NEUTRAL_FILE	Non verificare il file passato in pcwszFilePath e non accodare ".mui" al nome del file prima dell'elaborazione. Ad esempio, usare Abc.txt o Abc.chm.

[in] pcwszFilePath

Puntatore a una stringa con terminazione Null che specifica un percorso di file. Il percorso è relativo a un file LN esistente o a un file, ad esempio un file .txt, inf o msc. Se il file è un file LN, la funzione cerca i file contenenti le risorse specifiche della lingua associate. Per tutti gli altri tipi di file, la funzione cerca i file che corrispondono esattamente al nome e al percorso del file indicati. L'applicazione può sovrascrivere il comportamento del controllo del tipo di file usando il flag MUI_LANG_NEUTRAL_PE_FILE o MUI_NON_LANG_NEUTRAL_FILE. Per altre informazioni, vedere la sezione Osservazioni.

Nota Il percorso del file specificato può essere un percorso di rete, ad esempio "\\machinename\c$\windows\system32\notepad.exe".

[in, out, optional] pwszLanguage

Puntatore a un buffer contenente una stringa di lingua. In input, questo buffer contiene l'identificatore della lingua o il nome della lingua per cui l'applicazione deve trovare i file di risorse specifici della lingua, a seconda delle impostazioni di dwFlags. Al termine della restituzione dalla funzione, questo parametro contiene la lingua del file di risorse specifico della lingua trovato dalla funzione.

In alternativa, l'applicazione può impostare questo parametro su NULL, con il valore a cui fa riferimento pcchLanguage impostato su 0. In questo caso, la funzione recupera le dimensioni del buffer necessarie in pcchLanguage.

[in, out] pcchLanguage

Puntatore alla dimensione del buffer, in caratteri, per la stringa di lingua indicata da pwszLanguage. Se l'applicazione imposta il valore a cui fa riferimento questo parametro su 0 e passa NULL per pwszLanguage, le dimensioni del buffer richieste verranno restituite in pcchLanguage e le dimensioni del buffer restituite sono sempre LOCALE_NAME_MAX_LENGTH, perché la funzione viene in genere chiamata più volte in successione. La funzione non può determinare la dimensione esatta del nome della lingua per tutte le chiamate successive e non può estendere il buffer nelle chiamate successive. Pertanto LOCALE_NAME_MAX_LENGTH è l'unico massimo sicuro.

[out, optional] pwszFileMUIPath

Puntatore a un buffer contenente il percorso del file di risorse specifico della lingua. È consigliabile allocare questo buffer per essere di dimensioni MAX_PATH.

In alternativa, questo parametro può recuperare NULL se il valore a cui fa riferimento pcchFileMUIPath è impostato su 0. In questo caso, la funzione recupera le dimensioni necessarie per il buffer del percorso del file in pcchFileMUIPath.

[in, out] pcchFileMUIPath

Puntatore alla dimensione del buffer, in caratteri, per il percorso del file indicato da pwszFileMUIPath. Al termine della restituzione dalla funzione, questo parametro indica le dimensioni del percorso del file recuperato. Se l'applicazione imposta il valore a cui fa riferimento questo parametro su 0, la funzione recupera NULL per pwszFileMUIPath, le dimensioni del buffer richieste verranno restituite in pcchFileMUIPath e la dimensione del buffer restituita è sempre MAX_PATH, perché la funzione viene in genere chiamata più volte in successione. La funzione non può determinare la dimensione esatta del percorso per tutte le chiamate successive e non può estendere il buffer nelle chiamate successive. Pertanto MAX_PATH è l'unico massimo sicuro.

[in, out] pululEnumerator

Puntatore a una variabile di enumerazione. La prima volta che questa funzione viene chiamata, il valore della variabile deve essere 0. Tra le chiamate successive, l'applicazione non deve modificare il valore di questo parametro. Dopo che la funzione recupera tutti i possibili percorsi di file di risorse specifici del linguaggio, restituisce FALSE.

Valore restituito

Restituisce TRUE se ha esito positivo o FALSE in caso contrario. Se la funzione non riesce, i parametri di output non cambiano.

Per ottenere informazioni sull'errore estese, l'applicazione può chiamare GetLastError, che può restituire i codici di errore seguenti:

ERROR_INSUFFICIENT_BUFFER. Le dimensioni del buffer fornite non sono sufficienti o non sono state impostate correttamente su NULL.
ERROR_NO_MORE_FILES. Non sono stati più file da elaborare.

Commenti

Questa funzione verifica che esistano file di risorse specifici della lingua, ma non verifica che siano corretti. Richiede che i file di risorse vengano archiviati in base alla convenzione di archiviazione illustrata in Distribuzione di applicazioni.

Se la chiamata a questa funzione specifica il flag MUI_LANGUAGE_ID, la stringa di lingua specificata deve

usare un identificatore di lingua esadecimale che non include lo 0x iniziale e ha una lunghezza di 4 caratteri.

Ad esempio, en-US deve essere passato come "0409" e en come "0009". La stringa di lingua restituita si troverà nell'oggetto

stesso formato.

Quando si specifica MUI_LANGUAGE_ID, ogni valore esadecimale nella stringa di lingua specificata deve rappresentare un identificatore di lingua effettivo. In particolare, non è possibile specificare i valori corrispondenti alle impostazioni locali seguenti:

Per ricevere informazioni enumerate, l'applicazione deve chiamare ripetutamente questa funzione fino a quando non restituisce FALSE, lasciando invariato il contenuto di pululEnumerator tra le chiamate. Poiché ogni chiamata recupera il percorso di un file di risorse specifico della lingua diverso, l'applicazione deve cancellare il buffer della lingua in una stringa vuota tra le chiamate. Se l'applicazione non esegue questa operazione, il valore di input di pwszLanguage ha la precedenza sull'impostazione di dwFlags.

In genere, il caricatore di risorse viene usato per trovare i file di risorse. Tuttavia, l'applicazione può anche usare questa funzione per trovare i file. Se il percorso del file di input è relativo a un file LN, la funzione allega un suffisso ".mui" quando si cercano i file di risorse specifici della lingua corrispondenti.

Ad esempio, la funzione recupera i file seguenti quando l'applicazione passa la stringa "C:\mydir\Example1.dll" in pcwszFilePath come percorso del file radice, con dwFlags impostato su 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

La prima chiamata alla funzione imposta pwszFileMUIPath su "C:\mydir\en-US\Example1.dll.mui". La seconda chiamata imposta il percorso del file su "C:\mydir\ja-JP\Example1.dll.mui". La funzione restituisce FALSE quando viene chiamata una terza volta e GetLastError restituisce ERROR_NO_MORE_FILES.

Se il file indicato da pcwszFilePath non dispone di dati di configurazione delle risorse o se il file non esiste, la funzione lascia il nome del file così come quando si cercano i file di risorse specifici della lingua corrispondenti.

Ad esempio, l'applicazione passa la stringa "C:\mydir\Example2.txt" in pcwszFilePath come percorso del file radice, con dwFlags impostato su MUI_LANGUAGE_NAME | MUI_USER_PREFERRED_UI_LANGUAGES. Si consideri il caso in cui le lingue dell'interfaccia utente preferite dall'utente (in ordine) sono catalane, "ca-ES" e spagnolo (Spagna), "es-ES" e dove esistono i file seguenti:

(nessun file corrispondente 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

La prima chiamata alla funzione determina che non sono presenti risorse per "ca-ES" o per la lingua neutra "ca". La funzione tenta quindi l'opzione successiva "es-ES", per cui riesce a trovare una corrispondenza. Prima di tornare, la funzione imposta pwszFileMUIPath su "C:\mydir\es-ES\Example2.txt". Una seconda chiamata dell'applicazione alla funzione continua l'enumerazione impostando pwszFileMUIPath su "C:\mydir\es\Example2.txt".

Se il file di destinazione e i relativi file di risorse associati sono effettivamente assembly abilitati side-by-side, GetFileMUIPath non può essere usato per recuperare il percorso del file di risorse. Per informazioni dettagliate su come usare assembly side-by-side con supporto MUI, vedere Using Assemblies with a Multilanguage User Interface (Uso di assembly con interfaccia utente multilanguage ).

Firma C#

[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
            );

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winnls.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll