Funzione GetFileMUIInfo (winnls.h)

Articolo
03/08/2023

Recupera informazioni relative alle risorse relative a un file.

Sintassi

BOOL GetFileMUIInfo(
  [in]                DWORD        dwFlags,
  [in]                PCWSTR       pcwszFilePath,
  [in, out, optional] PFILEMUIINFO pFileMUIInfo,
  [in, out]           DWORD        *pcbFileMUIInfo
);

Parametri

[in] dwFlags

Flag che specificano le informazioni da recuperare. È consentita qualsiasi combinazione dei flag seguenti. Il valore predefinito dei flag è MUI_QUERY_TYPE | MUI_QUERY_CHECKSUM.

Valore	Significato
MUI_QUERY_TYPE	Recuperare uno dei valori seguenti nel membro dwFileType di FILEMUIINFO: MUI_FILETYPE_NOT_LANGUAGE_NEUTRAL: il file di input specificato non dispone di dati di configurazione delle risorse. Pertanto, non è né un file LN né un file di risorse specifico della lingua. Questo tipo di file è tipico per i file eseguibili meno recenti. Se questo tipo di file viene specificato, la funzione non recupererà informazioni utili per gli altri tipi. MUI_FILETYPE_LANGUAGE_NEUTRAL_MAIN. Il file di input è un file LN. MUI_FILETYPE_LANGUAGE_NEUTRAL_MUI. Il file di input è un file di risorse specifico della lingua associato a un file LN.
MUI_QUERY_CHECKSUM	Recuperare il checksum della risorsa del file di input nel membro pChecksum di FILEMUIINFO. Se il file di input non dispone di dati di configurazione delle risorse, questo membro della struttura contiene 0.
MUI_QUERY_LANGUAGE_NAME	Recuperare la lingua associata al file di input. Per un file di risorse specifico della lingua, questo flag richiede la lingua associata. Per un file LN, questo flag richiede la lingua delle risorse di fallback finali per il modulo, che può essere nel file LN o in un file di risorse specifico della lingua separato a cui fanno riferimento i dati di configurazione delle risorse del file LN. Per altre informazioni, vedere la sezione Osservazioni.
MUI_QUERY_RESOURCE_TYPES	Recuperare elenchi di tipi di risorse nei file di risorse specifici della lingua e nei file LN specificati nei dati di configurazione delle risorse. Per accedere a queste informazioni, vedere la sezione Osservazioni.

[in] pcwszFilePath

Puntatore a una stringa con terminazione Null che indica il percorso del file. In genere il file è un file LN o un file di risorse specifico della lingua. Se non è uno di questi tipi, l'unico valore significativo recuperato dalla funzione è MUI_FILETYPE_NOT_LANGUAGE_NEUTRAL. La funzione recupera questo valore solo se è impostato il flag MUI_QUERY_RESOURCE_TYPES.

[in, out, optional] pFileMUIInfo

Puntatore a un buffer contenente informazioni sui file in una struttura FILEMUIINFO ed eventualmente nei dati che seguono tale struttura. Il buffer delle informazioni potrebbe essere molto più grande della dimensione della struttura stessa. A seconda delle impostazioni del flag, la funzione può archiviare informazioni considerevoli dopo la struttura, in corrispondenza degli offset recuperati nella struttura. Per altre informazioni, vedere la sezione Osservazioni.

In alternativa, l'applicazione può impostare questo parametro su NULL se pcbFileMUIInfo è impostato su 0. In questo caso, la funzione recupera le dimensioni necessarie per il buffer delle informazioni in pcbFileMUIInfo.

Nota Se il valore di pFileMUIInfo non è NULL, il membro dwSize deve essere impostato sulle dimensioni della struttura FILEMUIINFO (incluso il buffer delle informazioni) e il membro dwVersion deve essere impostato sulla versione corrente di 0x001.

[in, out] pcbFileMUIInfo

Puntatore alle dimensioni del buffer, in byte, per le informazioni sul file indicate da pFileMUIInfo. Al termine della restituzione dalla funzione, questo parametro contiene le dimensioni del buffer delle informazioni sul file recuperato e la struttura FILEMUIINFO che lo contiene.

In alternativa, l'applicazione può impostare questo parametro su 0 se imposta NULL in pFileMUIInfo. In questo caso, la funzione recupera le dimensioni necessarie del buffer delle informazioni sui file in pcbFileMUIInfo. Per allocare la quantità di memoria corretta, questo valore deve essere aggiunto alle dimensioni della struttura FILEMUIINFO stessa.

Nota Il valore di questo parametro deve corrispondere al valore del membro dwSize di FILEMUIINFO se il valore di pFileMUIInfo non è NULL.

Valore restituito

Restituisce TRUE se ha esito positivo o FALSE in caso contrario. Per ottenere informazioni sull'errore estese, l'applicazione può chiamare GetLastError.

Commenti

Per il flag MUI_QUERY_LANGUAGE_NAME, questa funzione recupera un offset, in byte, dall'inizio di FILEMUIINFO nel membro dwLanguageNameOffset .

Di seguito è riportato un codice di esempio che accede al nome della lingua associato al file di input:

LPWSTR lpszLang = reinterpret_cast<LPWSTR>(
        reinterpret_cast<BYTE*>(pFileMUIInfo) +
        pFileMUIInfo->dwLanguageNameOffset);

Per il flag MUI_QUERY_RESOURCE_TYPES, questa funzione recupera le informazioni sul file di risorse specifiche del linguaggio nei membri FILEMUIINFO seguenti:

Il membro dwTypeIDMUIOffset contiene l'offset a una matrice di identificatori di risorse contenuti nel file di risorse specifico della lingua.
Il membro dwTypeIDMUISize contiene le dimensioni della matrice di identificatori di risorsa per il file di risorse specifico della lingua.
Il membro dwTypeNameMUIOffset contiene l'offset in una matrice di nomi di risorse contenuti nel file di risorse specifico della lingua.

Se il file di input è un file LN, la funzione compila tutti i membri della struttura precedenti. Inoltre, compila i membri seguenti:

Il membro dwTypeIDMainOffset contiene l'offset in una matrice di identificatori di risorse contenuti nel file LN.
Il membro dwTypeIDMainSize contiene le dimensioni della matrice di identificatori di risorsa per il file LN.
Il membro dwTypeNameMainOffset contiene l'offset in una matrice di nomi di risorse contenuti nel file.

Di seguito è riportato un codice di esempio che accede alla matrice di identificatori di risorsa nel file LN.

DWORD *pdwTypeID = reinterpret_cast<DWORD *>(
        reinterpret_cast<BYTE*>(pFileMUIInfo) +
        pFileMUIInfo->dwTypeIDMainOffset);

Nota Gli elenchi di risorse specifiche della lingua sono accessibili nello stesso modo.

Di seguito è riportato il codice di esempio per accedere alla matrice multistring di nomi di risorse nel file LN.

LPWSTR lpszNames = reinterpret_cast<LPWSTR>(
        reinterpret_cast<BYTE*>(pFileMUIInfo) +
        pFileMUIInfo->dwTypeNameMainOffset);

Nota Gli elenchi di risorse specifiche della lingua sono accessibili nello stesso modo.

Ognuno degli esempi di codice usa due cast reinterpretati. Prima di tutto, il codice esegue il cast in BYTE* in modo che il puntatore aritmetico per l'offset venga eseguito in byte. Il codice esegue quindi il cast del puntatore risultante al tipo desiderato.

Un altro approccio consiste nel scrivere il codice seguente anziché il codice illustrato negli esempi. L'effetto è lo stesso e la scelta è strettamente uno di stile.

DWORD ix = pFileMUIInfo->dwLanguageNameOffset - 
        offsetof(struct _FILEMUIINFO, abBuffer);
LPWSTR lpszLang = reinterpret_cast<LPWSTR>(&(pFileMUIInfo->abBuffer[ix]));

Firma C#

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean GetFileMUIInfo(
            System.UInt32 dwFlags,
            System.String pcwszFilePath,
            ref FILEMUIINFO pFileMUIInfo,
            ref System.UInt32 pcbFileMUIInfo
            );

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