Fonction FindNLSStringEx (winnls.h)

Article
08/27/2023

Recherche une chaîne Unicode (caractères larges) ou son équivalent dans une autre chaîne Unicode pour un paramètre régional spécifié par nom.

Attention Étant donné que les chaînes avec des représentations binaires très différentes peuvent être comparées comme identiques, cette fonction peut soulever certaines préoccupations de sécurité. Pour plus d’informations, consultez la discussion sur les fonctions de comparaison dans Considérations relatives à la sécurité : fonctionnalités internationales.

Syntaxe

int FindNLSStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFindNLSStringFlags,
  [in]            LPCWSTR          lpStringSource,
  [in]            int              cchSource,
  [in]            LPCWSTR          lpStringValue,
  [in]            int              cchValue,
  [out, optional] LPINT            pcchFound,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

Paramètres

[in, optional] lpLocaleName

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

[in] dwFindNLSStringFlags

Indicateurs spécifiant les détails de l’opération de recherche. Ces indicateurs s’excluent mutuellement, FIND_FROMSTART étant la valeur par défaut. L’application peut spécifier un seul des indicateurs de recherche avec l’un des indicateurs de filtrage définis dans le tableau suivant. Si l’application ne spécifie pas d’indicateur, la fonction utilise la comparaison par défaut pour les paramètres régionaux spécifiés. Comme indiqué dans Gestion du tri dans vos applications, il n’existe aucun mode de comparaison binaire.

Valeur	Signification
FIND_FROMSTART	Recherchez la chaîne, en commençant par le premier caractère de la chaîne.
FIND_FROMEND	Recherchez la chaîne dans le sens inverse, en commençant par le dernier caractère de la chaîne.
FIND_STARTSWITH	Testez pour déterminer si la valeur spécifiée par lpStringValue est la première valeur de la chaîne source indiquée par lpStringSource.
FIND_ENDSWITH	Testez pour déterminer si la valeur spécifiée par lpStringValue est la dernière valeur de la chaîne source indiquée par lpStringSource.

L’application peut utiliser les indicateurs de filtrage définis ci-dessous en combinaison avec un indicateur de recherche.

Valeur	Signification
LINGUISTIC_IGNORECASE	Ignorez la casse dans la recherche, selon le cas linguistiquement approprié. Pour plus d'informations, consultez la section Notes.
LINGUISTIC_IGNOREDIACRITIC	Ignorer les diacritiques, selon qu’il est linguistiquement approprié. Pour plus d'informations, consultez la section Notes. Note Cet indicateur ne produit pas toujours des résultats prévisibles lorsqu’il est utilisé avec des caractères décomposés, c’est-à-dire des caractères dans lesquels un caractère de base et un ou plusieurs caractères sans espacement ont chacun des valeurs de point de code distinctes.
NORM_IGNORECASE	Ignorer la casse dans la recherche. Pour plus d'informations, consultez la section Notes.
NORM_IGNOREKANATYPE	Ne faites pas de distinction entre les caractères hiragana et katakana. Les caractères hiragana et katakana correspondants sont égaux.
NORM_IGNORENONSPACE	Ignorez les caractères non espacés. Pour plus d'informations, consultez la section Notes.
NORM_IGNORESYMBOLS	Ignorez les symboles et la ponctuation.
NORM_IGNOREWIDTH	Ignorez la différence entre les caractères demi-largeur et pleine largeur, par exemple, C a t == cat. Le formulaire pleine largeur est une distinction de mise en forme utilisée dans les scripts chinois et japonais.
NORM_LINGUISTIC_CASING	Utilisez des règles linguistiques pour la casse au lieu de règles de système de fichiers (par défaut). Pour plus d'informations, consultez la section Notes.

[in] lpStringSource

Pointeur vers la chaîne source, dans laquelle la fonction recherche la chaîne spécifiée par lpStringValue.

[in] cchSource

Taille, en caractères à l’exclusion du caractère null de fin, de la chaîne indiquée par lpStringSource. L’application ne peut pas spécifier 0 ou un nombre négatif autre que -1 pour ce paramètre. L’application spécifie -1 si la chaîne source est terminée par null et si la fonction doit calculer automatiquement la taille.

[in] lpStringValue

Pointeur vers la chaîne de recherche, pour laquelle la fonction effectue des recherches dans la chaîne source.

[in] cchValue

Taille, en caractères à l’exclusion du caractère null de fin, de la chaîne indiquée par lpStringValue. L’application ne peut pas spécifier 0 ou un nombre négatif autre que -1 pour ce paramètre. L’application spécifie -1 si la chaîne de recherche est terminée par null et que la fonction doit calculer automatiquement la taille.

[out, optional] pcchFound

Pointeur vers une mémoire tampon contenant la longueur de la chaîne que la fonction recherche. La chaîne peut être plus longue ou plus courte que la chaîne de recherche. Si la fonction ne parvient pas à trouver la chaîne de recherche, ce paramètre n’est pas modifié.

La fonction peut récupérer null dans ce paramètre. Dans ce cas, la fonction n’indique pas si la longueur de la chaîne trouvée diffère de la longueur de la chaîne source.

Notez que la valeur de pcchFound est souvent identique à la valeur fournie dans cchValue, mais peut différer dans les cas suivants :

La valeur fournie dans cchValue est négative.
Les chaînes sont équivalentes, mais ont des longueurs différentes. Par exemple, « A » plus « Combining Ring » (U+0041 U+030A) équivaut à « A Ring » (U+00c5).

[in, optional] lpVersionInformation

Réservés au; doit avoir la valeur NULL.

[in, optional] lpReserved

Réservés au; doit avoir la valeur NULL.

[in, optional] sortHandle

Réservés au; doit être 0.

Valeur retournée

Retourne un index de base 0 dans la chaîne source indiquée par lpStringSource en cas de réussite. En combinaison avec la valeur dans pcchFound, cet index fournit l’emplacement exact de l’ensemble de la chaîne trouvée dans la chaîne source. Une valeur de retour 0 est un index sans erreur dans la chaîne source, et la chaîne correspondante se trouve dans la chaîne source au décalage 0.

La fonction retourne -1 si elle ne réussit pas. Pour obtenir des informations d’erreur étendues, l’application peut appeler GetLastError, qui peut retourner l’un des codes d’erreur suivants :

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.
ERROR_SUCCESS. L’action s’est terminée avec succès, mais n’a produit aucun résultat.

Remarques

Cette fonction fournit diverses options de recherche, notamment le sens de la recherche, le filtrage de l’équivalence des caractères et le filtrage spécifique aux paramètres régionaux. Notez que l’équivalence dépend des paramètres régionaux et des indicateurs spécifiés dans l’appel à la fonction. Les indicateurs de filtrage peuvent modifier les résultats de la recherche. Par exemple, les correspondances potentielles augmentent lorsque la fonction ignore les marques de casse ou diacritiques lors de la recherche.

Par défaut, cette fonction mappe le « i » en minuscules à la majuscule « I », même si le paramètre Locale spécifie le turc (Turquie) ou l’Azerbaïdjan (Azerbaïdjan). Pour remplacer ce comportement pour le turc ou l’azerbaïdjan, l’application doit spécifier NORM_LINGUISTIC_CASING. Si cet indicateur est spécifié pour les paramètres régionaux corrects, « ı » (minuscules pointless I) est la forme minuscule de « I » (I sans point majuscule) et « i » (I en minuscules) est la forme minuscule de « ı » (majuscules pointillées).

Pour de nombreux scripts (notamment les scripts latins), NORM_IGNORENONSPACE coïncide avec LINGUISTIC_IGNOREDIACRITIC et NORM_IGNORECASE coïncide avec LINGUISTIC_IGNORECASE, à quelques exceptions près :

NORM_IGNORENONSPACE ignore toute distinction secondaire, qu’il s’agisse ou non d’un diacritique. Les scripts pour le coréen, le japonais, le chinois, les langues indices et autres utilisent cette distinction à des fins autres que diacritiques. LINGUISTIC_IGNOREDIACRITIC ignore uniquement les diacritiques réels, au lieu d’ignorer simplement le deuxième poids de tri.
NORM_IGNORECASE ignore toute distinction tertiaire, qu’il s’agisse ou non d’une affaire linguistique. Par exemple, dans les scripts arabe et indic, cet indicateur distingue d’autres formes d’un caractère. Toutefois, les différences ne correspondent pas à la casse linguistique. LINGUISTIC_IGNORECASE ignore uniquement la casse linguistique réelle, au lieu d’ignorer le troisième poids de tri.

Contrairement à d’autres fonctions d’API NLS, qui retournent 0 en cas d’échec, cette fonction retourne -1 en cas d’échec. En cas de réussite, il retourne un index de base 0. L’utilisation de cet index permet à la fonction d’éviter les erreurs off-by-one et les dépassements de mémoire tampon d’un caractère.

Cette fonction est l’une des rares fonctions NLS qui appelle SetLastError même quand elle réussit. Il effectue cet appel pour effacer la dernière erreur d’un thread lorsqu’il ne correspond pas à la chaîne de recherche. Cela efface la valeur retournée par GetLastError.

À 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


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