Función GetNLSVersionEx (winnls.h)

Artículo
03/13/2024

Recupera información sobre la versión actual de una funcionalidad NLS especificada para una configuración regional especificada por nombre.

Nota La aplicación debe llamar a esta función en preferencia a GetNLSVersion si está diseñada para ejecutarse solo en Windows Vista y versiones posteriores.

Sintaxis

BOOL GetNLSVersionEx(
  [in]           NLS_FUNCTION       function,
  [in, optional] LPCWSTR            lpLocaleName,
  [in, out]      LPNLSVERSIONINFOEX lpVersionInformation
);

Parámetros

[in] function

La funcionalidad NLS que se va a consultar. Este valor debe ser COMPARE_STRING. Consulte la enumeración SYSNLS_FUNCTION .

[in, optional] lpLocaleName

Puntero a un nombre de configuración regional o uno de los siguientes valores predefinidos.

[in, out] lpVersionInformation

Puntero a una estructura NLSVERSIONINFOEX . La aplicación debe inicializar el miembro dwNLSVersionInfoSize en sizeof(NLSVERSIONINFOEX).

Nota En Windows Vista y versiones posteriores, la función puede proporcionar información de versión en una estructura NLSVERSIONINFO .

Valor devuelto

Devuelve TRUE si y solo si la aplicación ha proporcionado valores válidos en lpVersionInformation o FALSE en caso contrario. Para obtener información de error extendida, la aplicación puede llamar a GetLastError, que puede devolver uno de 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_INVALID_FLAGS. Los valores proporcionados para las marcas no eran válidos.
ERROR_INVALID_PARAMETER. Cualquiera de los valores de parámetro no era válido.

Comentarios

Esta función permite a una aplicación como Active Directory determinar si un cambio NLS afecta a la configuración regional utilizada para una tabla de índice determinada. Si no es así, no es necesario volver a indexar la tabla. Para obtener más información, consulte Control de la ordenación en las aplicaciones. En concreto, para indicar si ha cambiado una versión de ordenación y debe volver a indexar:

Use GetNLSVersionEx para recuperar una estructura NLSVERSIONINFOEX al realizar la indexación original de los datos.
Almacene las siguientes propiedades con el índice para identificar la versión:
- NLSVERSIONINFOEX.dwNLSVersion. Especifica la versión de la tabla de ordenación que está usando.
- NLSVERSIONINFOEX.dwEffectiveId. Esto especifica la configuración regional efectiva de la ordenación. Una configuración regional personalizada apuntará a la ordenación de una configuración regional integrada.
- NLSVERSIONINFOEX.guidCustomVersion. Se trata de un GUID que especifica una ordenación personalizada específica para las configuraciones regionales personalizadas que las tienen.
Al usar el índice, use GetNLSVersionEx para detectar la versión de los datos.
Si alguna de las tres propiedades ha cambiado, los datos de ordenación que usa podrían devolver resultados diferentes y cualquier indexación que haya podido encontrar registros.
Si sabe que los datos no contienen puntos de código Unicode no válidos (es decir, todas las cadenas pasaron una llamada a IsNLSDefinedString), puede considerarlos iguales si solo ha cambiado el byte bajo de dwNLSVersion (la versión secundaria descrita anteriormente).

Esto se trata con más detalle en la entrada de blog "Cómo saber si ha cambiado la versión de intercalación" (http://blogs.msdn.com/shawnste/archive/2007/06/01/how-to-tell-if-the-collation-version-changed.aspx).

Esta función admite configuraciones regionales personalizadas. Si lpLocaleName especifica una configuración regional complementaria, los datos recuperados son los datos correctos para el criterio de ordenación asociado a esa configuración regional complementaria.

A partir de Windows 8: si la aplicación pasa etiquetas de idioma a esta función desde el espacio de nombres Windows.Globalization, primero debe convertir las etiquetas mediante una llamada a ResolveLocaleName.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winnls.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll