Funzione FindNLSStringEx (winnls.h)

Articolo
08/27/2023

Individua una stringa Unicode (caratteri wide) o l'equivalente in un'altra stringa Unicode per le impostazioni locali specificate in base al nome.

Attenzione Poiché le stringhe con rappresentazioni binarie molto diverse possono essere confrontate come identiche, questa funzione può generare determinati problemi di sicurezza. Per altre informazioni, vedere la discussione sulle funzioni di confronto in Considerazioni sulla sicurezza: Funzionalità internazionali.

Sintassi

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

Parametri

[in, optional] lpLocaleName

Puntatore a un nome delle impostazioni locali o a uno dei valori predefiniti seguenti.

[in] dwFindNLSStringFlags

Flag che specificano i dettagli dell'operazione di ricerca. Questi flag si escludono a vicenda, con FIND_FROMSTART l'impostazione predefinita. L'applicazione può specificare solo uno dei flag di ricerca con uno dei flag di filtro definiti nella tabella successiva. Se l'applicazione non specifica un flag, la funzione usa il confronto predefinito per le impostazioni locali specificate. Come descritto in Gestione dell'ordinamento nelle applicazioni, non esiste alcuna modalità di confronto binario.

Valore	Significato
FIND_FROMSTART	Cercare la stringa, a partire dal primo carattere della stringa.
FIND_FROMEND	Cercare la stringa nella direzione inversa, a partire dall'ultimo carattere della stringa.
FIND_STARTSWITH	Verificare se il valore specificato da lpStringValue è il primo valore nella stringa di origine indicato da lpStringSource.
FIND_ENDSWITH	Verificare se il valore specificato da lpStringValue è l'ultimo valore nella stringa di origine indicata da lpStringSource.

L'applicazione può usare i flag di filtro definiti di seguito in combinazione con un flag di ricerca.

Valore	Significato
LINGUISTIC_IGNORECASE	Ignorare la distinzione tra maiuscole e minuscole nella ricerca, come appropriato in modo linguistico. Per altre informazioni, vedere la sezione Osservazioni.
LINGUISTIC_IGNOREDIACRITIC	Ignorare i segni diacritici, come appropriato in modo linguistico. Per altre informazioni, vedere la sezione Osservazioni. Nota Questo flag non produce sempre risultati prevedibili quando vengono usati con caratteri scomposti, ovvero i caratteri in cui un carattere di base e uno o più caratteri non in formatopacing hanno valori di punti di codice distinti.
NORM_IGNORECASE	Ignorare la distinzione tra maiuscole e minuscole nella ricerca. Per altre informazioni, vedere la sezione Osservazioni.
NORM_IGNOREKANATYPE	Non distinguere tra caratteri hiragana e katakana. I caratteri hiragana e katakana corrispondenti vengono confrontati come uguali.
NORM_IGNORENONSPACE	Ignorare i caratteri senza spaziatura. Per altre informazioni, vedere la sezione Osservazioni.
NORM_IGNORESYMBOLS	Ignora simboli e punteggiatura.
NORM_IGNOREWIDTH	Ignorare la differenza tra caratteri a metà larghezza e a larghezza intera, ad esempio C a t == cat. Il formato a larghezza intera è una distinzione di formattazione utilizzata negli script cinesi e giapponesi.
NORM_LINGUISTIC_CASING	Usare le regole linguistiche per l'uso di maiuscole e minuscole, anziché le regole del file system (impostazione predefinita). Per altre informazioni, vedere la sezione Osservazioni.

[in] lpStringSource

Puntatore alla stringa di origine, in cui la funzione cerca la stringa specificata da lpStringValue.

[in] cchSource

Dimensioni, in caratteri esclusi il carattere Null di terminazione, della stringa indicata da lpStringSource. L'applicazione non può specificare 0 o nessun numero negativo diverso da -1 per questo parametro. L'applicazione specifica -1 se la stringa di origine è con terminazione Null e la funzione deve calcolare automaticamente le dimensioni.

[in] lpStringValue

Puntatore alla stringa di ricerca, per cui la funzione esegue la ricerca nella stringa di origine.

[in] cchValue

Dimensioni, in caratteri esclusi il carattere Null di terminazione, della stringa indicata da lpStringValue. L'applicazione non può specificare 0 o nessun numero negativo diverso da -1 per questo parametro. L'applicazione specifica -1 se la stringa di ricerca è con terminazione Null e la funzione deve calcolare automaticamente le dimensioni.

[out, optional] pcchFound

Puntatore a un buffer contenente la lunghezza della stringa trovata dalla funzione. La stringa può essere più lunga o più breve della stringa di ricerca. Se la funzione non riesce a trovare la stringa di ricerca, questo parametro non viene modificato.

La funzione può recuperare NULL in questo parametro. In questo caso, la funzione non indica se la lunghezza della stringa trovata è diversa dalla lunghezza della stringa di origine.

Si noti che il valore di pcchFound è spesso identico al valore fornito in cchValue, ma può differire nei casi seguenti:

Il valore specificato in cchValue è negativo.
Le stringhe sono equivalenti, ma hanno lunghezze diverse. Ad esempio, "A" più "Anello combinato" (U+0041 U+030A) equivale a "A Ring" (U+00c5).

[in, optional] lpVersionInformation

Riservati; deve essere NULL.

[in, optional] lpReserved

Riservati; deve essere NULL.

[in, optional] sortHandle

Riservati; deve essere 0.

Valore restituito

Restituisce un indice in base 0 nella stringa di origine indicata da lpStringSource se l'operazione riesce. In combinazione con il valore in pcchFound, questo indice fornisce la posizione esatta dell'intera stringa trovata nella stringa di origine. Il valore restituito 0 è un indice senza errori nella stringa di origine e la stringa corrispondente si trova nella stringa di origine in corrispondenza dell'offset 0.

Se la funzione non riesce, restituisce -1. Per ottenere informazioni estese sull'errore, l'applicazione può chiamare GetLastError, che può restituire uno dei codici di errore seguenti:

ERROR_INVALID_FLAGS. I valori specificati per i flag non sono validi.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.
ERROR_SUCCESS. L'azione è stata completata correttamente, ma non ha restituito risultati.

Commenti

Questa funzione offre un'ampia gamma di opzioni di ricerca, tra cui direzione di ricerca, filtro di equivalenza dei caratteri e filtro specifico delle impostazioni locali. Si noti che l'equivalenza dipende dalle impostazioni locali e dai flag specificati nella chiamata alla funzione. I flag di filtro possono modificare i risultati della ricerca. Ad esempio, le potenziali corrispondenze aumentano quando la funzione ignora i segni di maiuscole e minuscole o segni diacritici durante l'esecuzione della ricerca.

Per impostazione predefinita, questa funzione esegue il mapping tra "i" minuscolo e "I" maiuscolo, anche quando il parametro Locale specifica turco (Turchia) o azero (Azerbaigian). Per eseguire l'override di questo comportamento per turco o azero, l'applicazione deve specificare NORM_LINGUISTIC_CASING. Se questo flag viene specificato per le impostazioni locali corrette, "ı" (i minuscolo senza punti) è la forma minuscola di "I" (i maiuscolo senza punti) e "i" (minuscolo punteggiato I) è la forma minuscola di "ı" (maiuscola punteggiata I).

Per molti script (in particolare gli script latini), NORM_IGNORENONSPACE coincide con LINGUISTIC_IGNOREDIACRITIC e NORM_IGNORECASE coincide con LINGUISTIC_IGNORECASE, con le eccezioni seguenti:

NORM_IGNORENONSPACE ignora qualsiasi distinzione secondaria, indipendentemente dal fatto che sia un diacritico. Gli script per coreano, giapponese, cinese, lingue indic e altre usano questa distinzione per scopi diversi dai segni diacritici. LINGUISTIC_IGNOREDIACRITIC ignora solo i segni diacritici effettivi, invece di ignorare semplicemente il secondo peso di ordinamento.
NORM_IGNORECASE ignora qualsiasi distinzione terziaria, indipendentemente dal fatto che sia effettivamente linguistico. Ad esempio, negli script arabi e indic, questo flag distingue forme alternative di un carattere. Tuttavia, le differenze non corrispondono al caso linguistico. LINGUISTIC_IGNORECASE ignora solo le maiuscole linguistiche effettive, invece di ignorare il terzo peso di ordinamento.

Al contrario di altre funzioni API NLS, che restituiscono 0 per errore, questa funzione restituisce -1 se ha esito negativo. In caso di esito positivo, restituisce un indice basato su 0. L'uso di questo indice consente alla funzione di evitare errori off-by-one e overrun del buffer a un carattere.

Questa funzione è una delle poche funzioni NLS che chiama SetLastError anche quando ha esito positivo. Questa chiamata consente di cancellare l'ultimo errore in un thread quando non corrisponde alla stringa di ricerca. Cancella il valore restituito da GetLastError.

A partire da Windows 8: Se l'app passa tag di lingua a questa funzione dallo spazio dei nomi Windows.Globalization , deve prima convertire i tag chiamando ResolveLocaleName.

Requisiti


Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winnls.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll