Função GetFileMUIInfo (winnls.h)

Artigo
08/27/2023

Recupera informações relacionadas a recursos sobre um arquivo.

Sintaxe

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

Parâmetros

[in] dwFlags

Sinalizadores que especificam as informações a serem recuperadas. Qualquer combinação dos sinalizadores a seguir é permitida. O valor padrão dos sinalizadores é MUI_QUERY_TYPE | MUI_QUERY_CHECKSUM.

Valor	Significado
MUI_QUERY_TYPE	Recupere um dos seguintes valores no membro dwFileType de FILEMUIINFO: MUI_FILETYPE_NOT_LANGUAGE_NEUTRAL: o arquivo de entrada especificado não tem dados de configuração de recurso. Portanto, ele não é um arquivo LN nem um arquivo de recurso específico do idioma. Esse tipo de arquivo é típico para arquivos executáveis mais antigos. Se esse tipo de arquivo for especificado, a função não recuperará informações úteis para os outros tipos. MUI_FILETYPE_LANGUAGE_NEUTRAL_MAIN. O arquivo de entrada é um arquivo LN. MUI_FILETYPE_LANGUAGE_NEUTRAL_MUI. O arquivo de entrada é um arquivo de recurso específico do idioma associado a um arquivo LN.
MUI_QUERY_CHECKSUM	Recupere a soma de verificação de recursos do arquivo de entrada no membro pChecksum de FILEMUIINFO. Se o arquivo de entrada não tiver dados de configuração de recurso, esse membro da estrutura conterá 0.
MUI_QUERY_LANGUAGE_NAME	Recupere o idioma associado ao arquivo de entrada. Para um arquivo de recurso específico do idioma, esse sinalizador solicita o idioma associado. Para um arquivo LN, esse sinalizador solicita o idioma dos recursos de fallback finais para o módulo, que pode estar no arquivo LN ou em um arquivo de recurso específico de linguagem separado referenciado pelos dados de configuração de recurso do arquivo LN. Para obter mais informações, consulte a seção Comentários.
MUI_QUERY_RESOURCE_TYPES	Recupere listas de tipos de recursos nos arquivos de recursos específicos do idioma e nos arquivos LN conforme eles são especificados nos dados de configuração do recurso. Consulte a seção Comentários para obter uma maneira de acessar essas informações.

[in] pcwszFilePath

Ponteiro para uma cadeia de caracteres terminada em nulo que indica o caminho para o arquivo. Normalmente, o arquivo é um arquivo LN ou um arquivo de recurso específico do idioma. Se não for um desses tipos, o único valor significativo recuperado pela função será MUI_FILETYPE_NOT_LANGUAGE_NEUTRAL. A função só recuperará esse valor se o sinalizador MUI_QUERY_RESOURCE_TYPES estiver definido.

[in, out, optional] pFileMUIInfo

Ponteiro para um buffer que contém informações de arquivo em uma estrutura FILEMUIINFO e possivelmente em dados que seguem essa estrutura. O buffer de informações pode ter que ser muito maior do que o tamanho da própria estrutura. Dependendo das configurações do sinalizador, a função pode armazenar informações consideráveis após a estrutura, em deslocamentos recuperados na estrutura . Para obter mais informações, consulte a seção Comentários.

Como alternativa, o aplicativo poderá definir esse parâmetro como NULL se pcbFileMUIInfo estiver definido como 0. Nesse caso, a função recupera o tamanho necessário para o buffer de informações em pcbFileMUIInfo.

Nota Se o valor de pFileMUIInfo não for NULL, o membro dwSize deverá ser definido como o tamanho da estrutura FILEMUIINFO (incluindo o buffer de informações) e o membro dwVersion deverá ser definido como a versão atual do 0x001.

[in, out] pcbFileMUIInfo

Ponteiro para o tamanho do buffer, em bytes, para as informações de arquivo indicadas por pFileMUIInfo. No retorno bem-sucedido da função, esse parâmetro contém o tamanho do buffer de informações de arquivo recuperado e a estrutura FILEMUIINFO que o contém.

Como alternativa, o aplicativo poderá definir esse parâmetro como 0 se definir NULL em pFileMUIInfo. Nesse caso, a função recupera o tamanho do buffer de informações de arquivo necessário em pcbFileMUIInfo. Para alocar a quantidade correta de memória, esse valor deve ser adicionado ao tamanho da própria estrutura FILEMUIINFO .

Nota O valor desse parâmetro deve corresponder ao valor do membro dwSize de FILEMUIINFO se o valor de pFileMUIInfo não for NULL.

Retornar valor

Retornará TRUE se tiver êxito ou FALSE caso contrário. Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError.

Comentários

Para o sinalizador MUI_QUERY_LANGUAGE_NAME, essa função recupera um deslocamento, em bytes, do início de FILEMUIINFO no membro dwLanguageNameOffset .

Veja a seguir o código de exemplo que acessa o nome do idioma associado ao arquivo de entrada:

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

Para o sinalizador MUI_QUERY_RESOURCE_TYPES, essa função recupera informações de arquivo de recurso específicas do idioma nos seguintes membros FILEMUIINFO :

O membro dwTypeIDMUIOffset contém o deslocamento para uma matriz de identificadores de recursos contidos no arquivo de recurso específico do idioma.
O membro dwTypeIDMUISize contém o tamanho da matriz de identificadores de recursos para o arquivo de recurso específico da linguagem.
O membro dwTypeNameMUIOffset contém o deslocamento para uma matriz de nomes de recursos contidos no arquivo de recurso específico do idioma.

Se o arquivo de entrada for um arquivo LN, a função preencherá todos os membros da estrutura acima. Além disso, ele preenche os seguintes membros:

O membro dwTypeIDMainOffset contém o deslocamento para uma matriz de identificadores de recursos contidos no arquivo LN.
O membro dwTypeIDMainSize contém o tamanho da matriz de identificadores de recurso para o arquivo LN.
O membro dwTypeNameMainOffset contém o deslocamento para uma matriz de nomes de recursos contidos no arquivo.

Veja a seguir um código de exemplo que acessa a matriz de identificadores de recursos no arquivo LN.

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

Nota As listas de recursos específicos do idioma são acessadas da mesma maneira.

Veja a seguir o código de exemplo para acessar a matriz multistring de nomes de recursos no arquivo LN.

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

Nota As listas de recursos específicos do idioma são acessadas da mesma maneira.

Cada um dos exemplos de código usa duas conversões reinterpretas. Primeiro, o código é convertido em BYTE* para que a aritmética do ponteiro para o deslocamento seja feita em bytes. Em seguida, o código converte o ponteiro resultante para o tipo desejado.

Outra abordagem é escrever o seguinte em vez do código mostrado nos exemplos. O efeito é o mesmo e a escolha é estritamente de estilo.

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

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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winnls.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll