Função GetFileMUIPath (winnls.h)

Artigo
03/08/2023

Recupera o caminho para todos os arquivos de recursos específicos do idioma associados ao arquivo LN fornecido. O aplicativo deve chamar essa função repetidamente para obter o caminho para cada arquivo de recurso.

Sintaxe

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

Parâmetros

[in] dwFlags

Sinalizadores que identificam o formato de linguagem e a filtragem. Os sinalizadores a seguir especificam o formato do idioma indicado por pwszLanguage. Os sinalizadores são mutuamente exclusivos e o padrão é MUI_LANGUAGE_NAME.

Valor	Significado
MUI_LANGUAGE_ID	Recupere a cadeia de caracteres de idioma no formato de identificador de idioma .
MUI_LANGUAGE_NAME	Recupere a cadeia de caracteres de idioma no formato de nome do idioma .

Os sinalizadores a seguir especificam a filtragem para a função a ser usada na localização de arquivos de recursos específicos da linguagem se pwszLanguage estiver definido como NULL. Os sinalizadores de filtragem são mutuamente exclusivos e o padrão é MUI_USER_PREFERRED_UI_LANGUAGES.

Valor	Significado
MUI_USE_SEARCH_ALL_LANGUAGES	Recupere todos os arquivos de recurso específicos do idioma para o caminho indicado por pcwszFilePath, sem considerar o licenciamento de arquivos. Esse sinalizador será relevante somente se o aplicativo fornecer uma cadeia de caracteres nula para pwszLanguage.
MUI_USER_PREFERRED_UI_LANGUAGES	Recupere apenas os arquivos que implementam idiomas na lista de fallback. Chamadas sucessivas enumeram os fallbacks sucessivos, na ordem apropriada. O primeiro arquivo indicado pelo valor de saída de pcchFileMUIPath deve ser o melhor ajuste. Esse sinalizador será relevante somente se o aplicativo fornecer uma cadeia de caracteres nula para pwszLanguage.
MUI_USE_INSTALLED_LANGUAGES	Recupere apenas os arquivos para os idiomas instalados no computador. Esse sinalizador será relevante somente se o aplicativo fornecer uma cadeia de caracteres nula para pwszLanguage.

Os sinalizadores a seguir permitem que o usuário indique o tipo de arquivo especificado por pcwszFilePath para que a função possa determinar se deve adicionar ".mui" ao nome do arquivo. Os sinalizadores são mutuamente exclusivos. Se o aplicativo passar os dois sinalizadores, a função falhará. Se o aplicativo não passar nenhum sinalizador, a função verificará o arquivo na pasta raiz para verificar o tipo de arquivo e decidir sobre a nomenclatura de arquivo.

Valor	Significado
MUI_LANG_NEUTRAL_PE_FILE	Não verifique o arquivo passado em pcwszFilePath e acrescente ".mui" ao nome do arquivo antes do processamento. Por exemplo, altere Abc.exe para Abc.exe.mui.
MUI_NON_LANG_NEUTRAL_FILE	Não verifique o arquivo passado em pcwszFilePath e não acrescente ".mui" ao nome do arquivo antes do processamento. Por exemplo, use Abc.txt ou Abc.chm.

[in] pcwszFilePath

Ponteiro para uma cadeia de caracteres terminada em nulo especificando um caminho de arquivo. O caminho é para um arquivo LN existente ou para um arquivo como um arquivo .txt, .inf ou .msc. Se o arquivo for um arquivo LN, a função procurará arquivos que contenham os recursos específicos do idioma associados. Para todos os outros tipos de arquivos, a função busca arquivos que correspondem exatamente ao nome do arquivo e ao caminho indicados. Seu aplicativo pode substituir o comportamento do tipo de arquivo marcar usando o sinalizador MUI_LANG_NEUTRAL_PE_FILE ou MUI_NON_LANG_NEUTRAL_FILE. Para obter mais informações, consulte a seção Comentários.

Nota O caminho do arquivo fornecido pode ser um caminho de rede: por exemplo, "\\machinename\c$\windows\system32\notepad.exe".

[in, out, optional] pwszLanguage

Ponteiro para um buffer que contém uma cadeia de caracteres de idioma. Na entrada, esse buffer contém o identificador de idioma ou o nome do idioma para o qual o aplicativo deve encontrar arquivos de recurso específicos do idioma, dependendo das configurações de dwFlags. No retorno bem-sucedido da função, esse parâmetro contém o idioma do arquivo de recurso específico da linguagem que a função encontrou.

Como alternativa, o aplicativo pode definir esse parâmetro como NULL, com o valor referenciado por pcchLanguage definido como 0. Nesse caso, a função recupera o tamanho do buffer necessário em pcchLanguage.

[in, out] pcchLanguage

Ponteiro para o tamanho do buffer, em caracteres, para a cadeia de caracteres de idioma indicada por pwszLanguage. Se o aplicativo definir o valor referenciado por esse parâmetro como 0 e passar NULL para pwszLanguage, o tamanho do buffer necessário será retornado em pcchLanguage e o tamanho do buffer retornado será sempre LOCALE_NAME_MAX_LENGTH, pois a função normalmente é chamada várias vezes em sucessão. A função não pode determinar o tamanho exato do nome do idioma para todas as chamadas sucessivas e não pode estender o buffer em chamadas subsequentes. Portanto, LOCALE_NAME_MAX_LENGTH é o único máximo seguro.

[out, optional] pwszFileMUIPath

Ponteiro para um buffer que contém o caminho para o arquivo de recurso específico do idioma. É altamente recomendável alocar esse buffer para ser de tamanho MAX_PATH.

Como alternativa, esse parâmetro poderá recuperar NULL se o valor referenciado por pcchFileMUIPath estiver definido como 0. Nesse caso, a função recupera o tamanho necessário para o buffer de caminho de arquivo no pcchFileMUIPath.

[in, out] pcchFileMUIPath

Ponteiro para o tamanho do buffer, em caracteres, para o caminho do arquivo indicado por pwszFileMUIPath. No retorno bem-sucedido da função, esse parâmetro indica o tamanho do caminho do arquivo recuperado. Se o aplicativo definir o valor referenciado por esse parâmetro como 0, a função recuperará NULL para pwszFileMUIPath, o tamanho do buffer necessário será retornado em pcchFileMUIPath e o tamanho do buffer retornado será sempre MAX_PATH, pois a função normalmente é chamada várias vezes em sucessão. A função não pode determinar o tamanho exato do caminho para todas as chamadas sucessivas e não pode estender o buffer em chamadas subsequentes. Portanto, MAX_PATH é o único máximo seguro.

[in, out] pululEnumerator

Ponteiro para uma variável de enumeração. Na primeira vez que essa função for chamada, o valor da variável deverá ser 0. Entre chamadas subsequentes, o aplicativo não deve alterar o valor desse parâmetro. Depois que a função recuperar todos os possíveis caminhos de arquivo de recurso específicos da linguagem, ela retornará FALSE.

Retornar valor

Retornará TRUE se tiver êxito ou FALSE caso contrário. Se a função falhar, os parâmetros de saída não serão alterados.

Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError, que pode retornar os seguintes códigos de erro:

ERROR_INSUFFICIENT_BUFFER. Um tamanho de buffer fornecido não era grande o suficiente ou foi definido incorretamente como NULL.
ERROR_NO_MORE_FILES. Não havia mais arquivos a serem processados.

Comentários

Essa função verifica se há arquivos de recurso específicos do idioma, mas não verifica se eles estão corretos. Ele exige que os arquivos de recurso sejam armazenados de acordo com a convenção de armazenamento explicada na Implantação de Aplicativos.

Se a chamada para essa função especificar o sinalizador MUI_LANGUAGE_ID, a cadeia de caracteres de idioma fornecida deverá

use um identificador de linguagem hexadecimal que não inclua o 0x à esquerda e tem 4 caracteres de comprimento.

Por exemplo, en-US deve ser passado como "0409" e en como "0009". A cadeia de caracteres de idioma retornada estará no

mesmo formato.

Quando MUI_LANGUAGE_ID é especificado, cada valor hexadecimal na cadeia de caracteres de idioma fornecida deve representar um identificador de idioma real. Em particular, os valores correspondentes às seguintes localidades não podem ser especificados:

Para receber informações enumeradas, o aplicativo deve chamar essa função repetidamente até retornar FALSE, deixando o conteúdo de pululEnumerator inalterado entre as chamadas. Como cada chamada recupera o caminho para um arquivo de recurso específico de idioma diferente, o aplicativo deve limpar o buffer de idioma para uma cadeia de caracteres vazia entre chamadas. Se o aplicativo não fizer isso, o valor de entrada de pwszLanguage terá precedência sobre a configuração de dwFlags.

Normalmente, o carregador de recursos é usado para localizar arquivos de recurso. No entanto, seu aplicativo também pode usar essa função para localizar os arquivos. Se o caminho do arquivo de entrada for para um arquivo LN, a função anexa um sufixo ".mui" ao procurar os arquivos de recurso específicos do idioma correspondentes.

Por exemplo, a função recupera os seguintes arquivos quando o aplicativo passa a cadeia de caracteres "C:\mydir\Example1.dll" em pcwszFilePath como o caminho do arquivo raiz, com dwFlags definido como 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

A primeira chamada para a função define pwszFileMUIPath como "C:\mydir\en-US\Example1.dll.mui". A segunda chamada define o caminho do arquivo como "C:\mydir\ja-JP\Example1.dll.mui". A função retorna FALSE quando chamada uma terceira vez e GetLastError retorna ERROR_NO_MORE_FILES.

Se o arquivo indicado por pcwszFilePath não tiver dados de configuração de recurso ou se o arquivo não existir, a função deixará o nome do arquivo como está ao procurar os arquivos de recurso específicos do idioma correspondentes.

Por exemplo, o aplicativo passa a cadeia de caracteres "C:\mydir\Example2.txt" em pcwszFilePath como o caminho do arquivo raiz, com dwFlags definido como MUI_LANGUAGE_NAME | MUI_USER_PREFERRED_UI_LANGUAGES. Vamos considerar o caso em que os idiomas de interface do usuário preferenciais do usuário (em ordem) são catalão, "ca-ES" e espanhol (Espanha), "es-ES" e onde os seguintes arquivos existem:

(nenhum arquivo correspondente em 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

A primeira chamada para a função determina que não há recursos para "ca-ES" ou para a linguagem neutra "ca". Em seguida, a função tenta a próxima opção, "es-ES", para a qual ela consegue encontrar uma correspondência. Antes de retornar, a função define pwszFileMUIPath como "C:\mydir\es-ES\Example2.txt". Uma segunda chamada de aplicativo para a função continua a enumeração definindo pwszFileMUIPath como "C:\mydir\es\Example2.txt".

Se o arquivo de destino e seus arquivos de recurso associados forem, na verdade, assemblies habilitados lado a lado, GetFileMUIPath não poderá ser usado para recuperar o caminho para o arquivo de recurso. Consulte Usando assemblies com uma interface do usuário multilanguage para obter detalhes sobre como usar assemblies lado a lado com suporte a MUI.

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

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