GetNLSVersionEx, fonction (winnls.h)

Article
08/27/2023

Récupère des informations sur la version actuelle d’une fonctionnalité NLS spécifiée pour les paramètres régionaux spécifiés par nom.

Note L’application doit appeler cette fonction de préférence à GetNLSVersion si elle est conçue pour s’exécuter uniquement sur Windows Vista et versions ultérieures.

Syntaxe

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

Paramètres

[in] function

Fonctionnalité NLS d’interrogation. Cette valeur doit être COMPARE_STRING. Consultez l’énumération SYSNLS_FUNCTION .

[in, optional] lpLocaleName

Pointeur vers un nom de paramètres régionaux ou l’une des valeurs prédéfinies suivantes.

[in, out] lpVersionInformation

Pointeur vers une structure NLSVERSIONINFOEX . L’application doit initialiser le membre dwNLSVersionInfoSize en sizeof(NLSVERSIONINFOEX).

Note Sur Windows Vista et versions ultérieures, la fonction peut également fournir des informations de version dans une structure NLSVERSIONINFO .

Valeur retournée

Retourne TRUE si et uniquement si l’application a fourni des valeurs valides dans lpVersionInformation, ou FALSE dans le cas contraire. Pour obtenir des informations d’erreur étendues, l’application peut appeler GetLastError, qui peut retourner l’un des codes d’erreur suivants :

ERROR_INSUFFICIENT_BUFFER. Une taille de mémoire tampon fournie n’était pas suffisamment grande ou a été incorrectement définie sur NULL.
ERROR_INVALID_FLAGS. Les valeurs fournies pour les indicateurs n’étaient pas valides.
ERROR_INVALID_PARAMETER. L’une des valeurs de paramètre n’était pas valide.

Remarques

Cette fonction permet à une application telle qu’Active Directory de déterminer si une modification NLS affecte les paramètres régionaux utilisés pour une table d’index particulière. Si ce n’est pas le cas, il n’est pas nécessaire de réindexer la table. Pour plus d’informations, consultez Gestion du tri dans vos applications. En particulier, pour savoir si une version de tri a changé et que vous devez réindexer :

Utilisez GetNLSVersionEx pour récupérer une structure NLSVERSIONINFOEX lors de l’indexation d’origine de vos données.
Stockez les propriétés suivantes avec votre index pour identifier la version :
- NLSVERSIONINFOEX.dwNLSVersion. Cela spécifie la version de la table de tri que vous utilisez.
- NLSVERSIONINFOEX.dwEffectiveId. Cela spécifie les paramètres régionaux effectifs de votre tri. Un paramètre régional personnalisé pointe vers le tri des paramètres régionaux dans la boîte.
- NLSVERSIONINFOEX.guidCustomVersion. Il s’agit d’un GUID spécifiant un tri personnalisé spécifique pour les paramètres régionaux personnalisés qui les contiennent.
Lorsque vous utilisez l’index, utilisez GetNLSVersionEx pour découvrir la version de vos données.
Si l’une des trois propriétés a changé, les données de tri que vous utilisez peuvent retourner des résultats différents et toute indexation que vous avez peut ne pas trouver d’enregistrements.
Si vous savez que vos données ne contiennent pas de points de code Unicode non valides (autrement dit, toutes vos chaînes ont passé un appel à IsNLSDefinedString), vous pouvez les considérer comme identiques si seul l’octet faible de dwNLSVersion a changé (la version mineure décrite ci-dessus).

Cela est abordé plus en détail dans l’entrée de blog « Comment savoir si la version de classement a changé » (http://blogs.msdn.com/shawnste/archive/2007/06/01/how-to-tell-if-the-collation-version-changed.aspx).

Cette fonction prend en charge les paramètres régionaux personnalisés. Si lpLocaleName spécifie des paramètres régionaux supplémentaires, les données récupérées sont les données correctes pour l’ordre de tri associé à ces paramètres régionaux supplémentaires.

À partir de Windows 8 : si votre application transmet des balises de langue à cette fonction à partir de l’espace de noms Windows.Globalization, elle doit d’abord convertir les balises en appelant ResolveLocaleName.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winnls.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll