Función GetFileMUIPath (winnls.h)

Artículo
03/08/2023

Recupera la ruta de acceso a todos los archivos de recursos específicos del lenguaje asociados al archivo LN proporcionado. La aplicación debe llamar a esta función repetidamente para obtener la ruta de acceso de cada archivo de recursos.

Sintaxis

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

Marcas que identifican el formato de idioma y el filtrado. Las marcas siguientes especifican el formato del idioma indicado por pwszLanguage. Las marcas son mutuamente excluyentes y el valor predeterminado es MUI_LANGUAGE_NAME.

Valor	Significado
MUI_LANGUAGE_ID	Recupere la cadena de idioma en formato de identificador de idioma .
MUI_LANGUAGE_NAME	Recupere la cadena de idioma en formato de nombre de idioma .

Las marcas siguientes especifican el filtrado de la función que se va a usar en la búsqueda de archivos de recursos específicos del lenguaje si pwszLanguage está establecido en NULL. Las marcas de filtrado son mutuamente excluyentes y el valor predeterminado es MUI_USER_PREFERRED_UI_LANGUAGES.

Valor	Significado
MUI_USE_SEARCH_ALL_LANGUAGES	Recupere todos los archivos de recursos específicos del idioma para la ruta de acceso indicada por pcwszFilePath, sin tener en cuenta las licencias de archivos. Esta marca solo es relevante si la aplicación proporciona una cadena nula para pwszLanguage.
MUI_USER_PREFERRED_UI_LANGUAGES	Recupere solo los archivos que implementan idiomas en la lista de reserva. Las llamadas sucesivas enumeran las reservas sucesivas, en el orden adecuado. El primer archivo indicado por el valor de salida de pcchFileMUIPath debe ser el mejor ajuste. Esta marca solo es relevante si la aplicación proporciona una cadena nula para pwszLanguage.
MUI_USE_INSTALLED_LANGUAGES	Recupere solo los archivos de los idiomas instalados en el equipo. Esta marca solo es relevante si la aplicación proporciona una cadena nula para pwszLanguage.

Las marcas siguientes permiten al usuario indicar el tipo de archivo especificado por pcwszFilePath para que la función pueda determinar si debe agregar ".mui" al nombre de archivo. Las marcas son mutuamente excluyentes. Si la aplicación pasa ambas marcas, se produce un error en la función. Si la aplicación no pasa ninguna marca, la función comprueba el archivo en la carpeta raíz para comprobar el tipo de archivo y decidir la nomenclatura de archivos.

Valor	Significado
MUI_LANG_NEUTRAL_PE_FILE	No compruebe el archivo pasado en pcwszFilePath y anexe ".mui" al nombre de archivo antes de procesarlo. Por ejemplo, cambie Abc.exe a Abc.exe.mui.
MUI_NON_LANG_NEUTRAL_FILE	No compruebe el archivo pasado en pcwszFilePath y no anexe ".mui" al nombre de archivo antes de procesarlo. Por ejemplo, use Abc.txt o Abc.chm.

[in] pcwszFilePath

Puntero a una cadena terminada en null que especifica una ruta de acceso de archivo. La ruta de acceso es para un archivo LN existente o para un archivo como un archivo .txt, .inf o .msc. Si el archivo es un archivo LN, la función busca los archivos que contienen los recursos específicos del idioma asociados. Para todos los demás tipos de archivos, la función busca archivos que se correspondan exactamente con el nombre de archivo y la ruta de acceso indicadas. La aplicación puede sobrescribir el comportamiento de la comprobación de tipo de archivo mediante la marca MUI_LANG_NEUTRAL_PE_FILE o MUI_NON_LANG_NEUTRAL_FILE. Para obtener más información, vea la sección Comentarios.

Nota La ruta de acceso del archivo proporcionada puede ser una ruta de acceso de red: por ejemplo, "\\machinename\c$\windows\system32\notepad.exe".

[in, out, optional] pwszLanguage

Puntero a un búfer que contiene una cadena de idioma. En la entrada, este búfer contiene el identificador de idioma o el nombre de idioma para el que la aplicación debe encontrar archivos de recursos específicos del idioma, según la configuración de dwFlags. Si la función se devuelve correctamente, este parámetro contiene el idioma del archivo de recursos específico del lenguaje que ha encontrado la función.

Como alternativa, la aplicación puede establecer este parámetro en NULL, con el valor al que hace referencia pcchLanguage establecido en 0. En este caso, la función recupera el tamaño de búfer necesario en pcchLanguage.

[in, out] pcchLanguage

Puntero al tamaño del búfer, en caracteres, para la cadena de idioma indicada por pwszLanguage. Si la aplicación establece el valor al que hace referencia este parámetro en 0 y pasa NULL para pwszLanguage, el tamaño de búfer necesario se devolverá en pcchLanguage y el tamaño del búfer devuelto siempre se LOCALE_NAME_MAX_LENGTH, ya que la función suele llamarse varias veces sucesivamente. La función no puede determinar el tamaño exacto del nombre del lenguaje para todas las llamadas sucesivas y no puede extender el búfer en llamadas posteriores. Por lo tanto, LOCALE_NAME_MAX_LENGTH es el único máximo seguro.

[out, optional] pwszFileMUIPath

Puntero a un búfer que contiene la ruta de acceso al archivo de recursos específico del idioma. Se recomienda encarecidamente asignar este búfer para que sea de tamaño MAX_PATH.

Como alternativa, este parámetro puede recuperar NULL si el valor al que hace referencia pcchFileMUIPath se establece en 0. En este caso, la función recupera el tamaño necesario para el búfer de ruta de acceso de archivo en pcchFileMUIPath.

[in, out] pcchFileMUIPath

Puntero al tamaño del búfer, en caracteres, para la ruta de acceso del archivo indicada por pwszFileMUIPath. Si la función se devuelve correctamente, este parámetro indica el tamaño de la ruta de acceso del archivo recuperado. Si la aplicación establece el valor al que hace referencia este parámetro en 0, la función recupera NULL para pwszFileMUIPath, el tamaño de búfer necesario se devolverá en pcchFileMUIPath y el tamaño del búfer devuelto siempre se MAX_PATH, ya que la función suele llamarse varias veces sucesivamente. La función no puede determinar el tamaño exacto de la ruta de acceso para todas las llamadas sucesivas y no puede extender el búfer en llamadas posteriores. Por lo tanto, MAX_PATH es el único máximo seguro.

[in, out] pululEnumerator

Puntero a una variable de enumeración. La primera vez que se llama a esta función, el valor de la variable debe ser 0. Entre las llamadas posteriores, la aplicación no debe cambiar el valor de este parámetro. Después de que la función recupere todas las posibles rutas de acceso del archivo de recursos específicas del lenguaje, devuelve FALSE.

Valor devuelto

Devuelve TRUE si es correcto o FALSE en caso contrario. Si se produce un error en la función, los parámetros de salida no cambian.

Para obtener información de error extendida, la aplicación puede llamar a GetLastError, que puede devolver los siguientes códigos de error:

ERROR_INSUFFICIENT_BUFFER. Un tamaño de búfer proporcionado no era lo suficientemente grande o se estableció incorrectamente en NULL.
ERROR_NO_MORE_FILES. No había más archivos para procesar.

Comentarios

Esta función comprueba que existen archivos de recursos específicos del lenguaje, pero no comprueba que sean correctos. Requiere que los archivos de recursos se almacenen según la convención de almacenamiento que se explica en Implementación de aplicaciones.

Si la llamada a esta función especifica la marca MUI_LANGUAGE_ID, la cadena de idioma proporcionada debe

usa un identificador de idioma hexadecimal que no incluye el 0x inicial y tiene 4 caracteres de longitud.

Por ejemplo, en-US debe pasarse como "0409" y en como "0009". La cadena de idioma devuelta estará en

mismo formato.

Cuando se especifica MUI_LANGUAGE_ID, cada valor hexadecimal de la cadena de idioma proporcionada debe representar un identificador de idioma real. En concreto, no se pueden especificar los valores correspondientes a las configuraciones regionales siguientes:

Para recibir información enumerada, la aplicación debe llamar a esta función repetidamente hasta que devuelve FALSE, dejando el contenido de pululEnumerator sin cambios entre las llamadas. Dado que cada llamada recupera la ruta de acceso a un archivo de recursos específico del idioma diferente, la aplicación debe borrar el búfer de idioma en una cadena vacía entre las llamadas. Si la aplicación no lo hace, el valor de entrada de pwszLanguage tiene prioridad sobre el valor de dwFlags.

Normalmente, el cargador de recursos se usa para buscar archivos de recursos. Sin embargo, la aplicación también puede usar esta función para buscar los archivos. Si la ruta de acceso del archivo de entrada es para un archivo LN, la función adjunta un sufijo de ".mui" al buscar los archivos de recursos específicos del idioma correspondientes.

Por ejemplo, la función recupera los siguientes archivos cuando la aplicación pasa la cadena "C:\mydir\Example1.dll" en pcwszFilePath como ruta de acceso del archivo raíz, con dwFlags establecido en 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 primera llamada a la función establece pwszFileMUIPath en "C:\mydir\en-US\Example1.dll.mui". La segunda llamada establece la ruta de acceso del archivo en "C:\mydir\ja-JP\Example1.dll.mui". La función devuelve FALSE cuando se llama a una tercera vez y GetLastError devuelve ERROR_NO_MORE_FILES.

Si el archivo indicado por pcwszFilePath no tiene datos de configuración de recursos, o si el archivo no existe, la función deja el nombre de archivo tal cual cuando busca los archivos de recursos específicos del idioma correspondientes.

Por ejemplo, la aplicación pasa la cadena "C:\mydir\Example2.txt" en pcwszFilePath como ruta de acceso del archivo raíz, con dwFlags establecido en MUI_LANGUAGE_NAME | MUI_USER_PREFERRED_UI_LANGUAGES. Consideremos el caso en el que los idiomas de interfaz de usuario preferidos por el usuario (en orden) son catalán, "ca-ES" y español (España), "es-ES" y dónde existen los siguientes archivos:

(no hay ningún archivo correspondiente en 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 primera llamada a la función determina que no hay ningún recurso para "ca-ES" o para el idioma neutro "ca". A continuación, la función intenta la siguiente opción, "es-ES", para la que se realiza correctamente la búsqueda de una coincidencia. Antes de devolverla, la función establece pwszFileMUIPath en "C:\mydir\es-ES\Example2.txt". Una segunda llamada de aplicación a la función continúa la enumeración estableciendo pwszFileMUIPath en "C:\mydir\es\Example2.txt".

Si el archivo de destino y sus archivos de recursos asociados son realmente ensamblados habilitados en paralelo, GetFileMUIPath no se puede usar para recuperar la ruta de acceso al archivo de recursos. Consulte Using Assemblies with a Multilanguage User Interface (Usar ensamblados con una interfaz de usuario multilanguage ) para obtener más información sobre cómo usar ensamblados en paralelo con compatibilidad con MUI.

Firma de 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	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winnls.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll