Funzione LCMapStringEx (winnls.h)

Articolo
03/04/2024

Per le impostazioni locali specificate per nome, esegue il mapping di una stringa di caratteri di input a un'altra usando una trasformazione specificata o genera una chiave di ordinamento per la stringa di input.

Nota L'applicazione deve chiamare questa funzione in preferenza a LCMapString se progettata per l'esecuzione solo in Windows Vista e versioni successive.

Sintassi

int LCMapStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwMapFlags,
  [in]            LPCWSTR          lpSrcStr,
  [in]            int              cchSrc,
  [out, optional] LPWSTR           lpDestStr,
  [in]            int              cchDest,
  [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] dwMapFlags

Flag che specifica il tipo di trasformazione da usare durante il mapping di stringhe o il tipo di chiave di ordinamento da generare. Questo parametro può avere i valori seguenti.

Contrassegno	Significato
LCMAP_BYTEREV	Usare l'inversione dei byte. Ad esempio, se l'applicazione passa 0x3450 0x4822, il risultato viene 0x5034 0x2248.
LCMAP_FULLWIDTH	Se applicabile, usare caratteri Unicode (wide). Questo flag e LCMAP_HALFWIDTH si escludono a vicenda. Con questo flag, il mapping può usare il formato di normalizzazione C anche se un carattere di input è già a larghezza intera. Ad esempio, la stringa "は゛" (che è già a larghezza intera) viene normalizzata in "ば". Vedere Unicode Normalization Forms (Formati di normalizzazione Unicode).
LCMAP_HALFWIDTH	Usare caratteri stretti, se applicabile. Questo flag e LCMAP_FULLWIDTH si escludono a vicenda.
LCMAP_HIRAGANA	Eseguire il mapping di tutti i caratteri katakana a hiragana. Questo flag e LCMAP_KATAKANA si escludono a vicenda.
LCMAP_KATAKANA	Eseguire il mapping di tutti i caratteri hiragana a katakana. Questo flag e LCMAP_HIRAGANA si escludono a vicenda.
LCMAP_LINGUISTIC_CASING	Usare le regole linguistiche per l'uso di maiuscole e minuscole, anziché le regole del file system (impostazione predefinita). Questo flag è valido solo con LCMAP_LOWERCASE o LCMAP_UPPERCASE.
LCMAP_LOWERCASE	Per le impostazioni locali e gli script in grado di gestire maiuscole e minuscole, eseguire il mapping di tutti i caratteri in lettere minuscole.
LCMAP_HASH	Restituisce un hash dei pesi di ordinamento non elaborati di una stringa. Le stringhe che appaiono equivalenti restituiscono in genere lo stesso hash (ad esempio, "hello" e "HELLO" con LCMAP_IGNORECASE). Tuttavia, alcuni casi complessi, ad esempio le lingue dell'Asia orientale, possono avere stringhe simili con pesi identici che vengono confrontati come uguali ma non restituiscono lo stesso hash. LCMAP_HASH richiede che il buffer di output sia di dimensioni sizeof(int)
LCMAP_SIMPLIFIED_CHINESE	Eseguire il mapping dei caratteri cinesi tradizionali ai caratteri cinesi semplificati. Questo flag e LCMAP_TRADITIONAL_CHINESE si escludono a vicenda.
LCMAP_SORTHANDLE L'uso di un handle di ordinamento comporta miglioramenti minimi delle prestazioni ed è sconsigliato.	Restituisce un token che rappresenta i parametri di ordinamento risolti per le impostazioni locali ,ad esempio il nome delle impostazioni locali, in modo che le chiamate future possano passare `NULL` per il nome di ordinamento e passare l'handle di ordinamento sottoposto a query in precedenza come ultimo parametro (sortHandle) nelle chiamate successive a CompareStringEx o LCMapStringEx. LCMAP_SORTHANDLE richiede che il buffer di output sia di dimensioniof(lparam)
LCMAP_SORTKEY	Produrre una chiave di ordinamento normalizzata. Se il flag LCMAP_SORTKEY non è specificato, la funzione esegue il mapping di stringhe. Per informazioni dettagliate sulla generazione di chiavi di ordinamento e sul mapping di stringhe, vedere la sezione Osservazioni.
LCMAP_TITLECASE	Windows 7: eseguire il mapping di tutti i caratteri al caso del titolo, in cui la prima lettera di ogni parola principale viene maiuscola.
LCMAP_TRADITIONAL_CHINESE	Eseguire il mapping dei caratteri cinesi semplificati ai caratteri cinesi tradizionali. Questo flag e LCMAP_SIMPLIFIED_CHINESE si escludono a vicenda.
LCMAP_UPPERCASE	Per le impostazioni locali e gli script in grado di gestire maiuscole e minuscole, eseguire il mapping di tutti i caratteri a maiuscolo.

I flag seguenti possono essere usati da soli, uno con l'altro o con i flag LCMAP_SORTKEY e/o LCMAP_BYTEREV. Tuttavia, non possono essere combinati con gli altri flag elencati in precedenza.

Contrassegno	Significato
NORM_IGNORENONSPACE	Ignorare i caratteri senza spaziatura. Per molti script (in particolare gli script latini), NORM_IGNORENONSPACE coincide con LINGUISTIC_IGNOREDIACRITIC. Nota NORM_IGNORENONSPACE ignora qualsiasi distinzione secondaria, indipendentemente dal fatto che si tratti di un diacritico o meno. Gli script per lingue coreane, giapponesi, cinesi e indic, tra gli altri, usano questa distinzione per scopi diversi dai segni diacritici. LINGUISTIC_IGNOREDIACRITIC fa sì che la funzione ignori solo i segni diacritici effettivi, anziché ignorare il secondo peso di ordinamento.
NORM_IGNORESYMBOLS	Ignora simboli e punteggiatura.

Contrassegno

Significato

NORM_IGNORENONSPACE

Ignorare i caratteri senza spaziatura. Per molti script (in particolare gli script latini), NORM_IGNORENONSPACE coincide con LINGUISTIC_IGNOREDIACRITIC.

Nota NORM_IGNORENONSPACE ignora qualsiasi distinzione secondaria, indipendentemente dal fatto che si tratti di un diacritico o meno. Gli script per lingue coreane, giapponesi, cinesi e indic, tra gli altri, usano questa distinzione per scopi diversi dai segni diacritici. LINGUISTIC_IGNOREDIACRITIC fa sì che la funzione ignori solo i segni diacritici effettivi, anziché ignorare il secondo peso di ordinamento.

NORM_IGNORESYMBOLS

Ignora simboli e punteggiatura.

I flag elencati di seguito vengono usati solo con il flag LCMAP_SORTKEY.

Contrassegno	Significato
LINGUISTIC_IGNORECASE	Ignorare la distinzione tra maiuscole e minuscole, come appropriato in modo linguistico.
LINGUISTIC_IGNOREDIACRITIC	Ignorare i caratteri senza spaziatura, come appropriato in modo linguistico. 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 Per molti script (in particolare gli script latini), NORM_IGNORECASE coincide con LINGUISTIC_IGNORECASE. Nota NORM_IGNORECASE ignora qualsiasi distinzione terziaria, indipendentemente dal fatto che si tratti di un caso linguistico o meno. Ad esempio, negli script arabi e indic, questo flag distingue forme alternative di un carattere, ma le differenze non corrispondono al case linguistico. LINGUISTIC_IGNORECASE fa sì che la funzione ignori solo le maiuscole e minuscole linguistiche effettive, invece di ignorare il terzo peso di ordinamento. Nota Per le impostazioni locali del set di caratteri a byte doppio (DBCS), NORM_IGNORECASE ha un effetto su tutti i caratteri Unicode, nonché su caratteri stretti (a un byte), inclusi i caratteri greci e cirillici.
NORM_IGNOREKANATYPE	Non distinguere tra caratteri hiragana e katakana. I caratteri hiragana e katakana corrispondenti vengono confrontati come uguali.
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).
SORT_DIGITSASNUMBERS	Windows 7: Considerare le cifre come numeri durante l'ordinamento, ad esempio ordinare "2" prima di "10".
SORT_STRINGSORT	Trattare la punteggiatura uguale ai simboli.

[in] lpSrcStr

Puntatore a una stringa di origine di cui la funzione esegue il mapping o che la funzione utilizza per la generazione di chiavi di ordinamento. Questa stringa non può avere una dimensione pari a 0.

[in] cchSrc

Dimensioni, in caratteri, della stringa di origine indicata da lpSrcStr. Le dimensioni della stringa di origine possono includere il carattere Null terminante, ma non deve essere necessario. Se il carattere null di terminazione è incluso, il comportamento di mapping della funzione non è notevolmente interessato perché il carattere Null terminante viene considerato non aggiornabile e viene sempre mappato a se stesso.

L'applicazione può impostare questo parametro su qualsiasi valore negativo per specificare che la stringa di origine è terminata con null. In questo caso, se LCMapStringEx viene usato nella modalità di mapping stringa, la funzione calcola la lunghezza della stringa stessa e termina la stringa mappata indicata da lpDestStr.

L'applicazione non può impostare questo parametro su 0.

[out, optional] lpDestStr

Puntatore a un buffer in cui questa funzione recupera la stringa mappata o una chiave di ordinamento.

Se l'applicazione usa la funzione per generare una chiave di ordinamento (LCMAP_SORTKEY):

La chiave di ordinamento viene archiviata nel buffer e considerata come matrice opaca di byte. I valori archiviati possono includere 0 byte incorporati in qualsiasi posizione.
La stringa di destinazione può contenere un numero dispari di byte. Il flag LCMAP_BYTEREV inverte solo un numero pari di byte. L'ultimo byte (posizionato dispari) nella chiave di ordinamento non viene invertito.

Se il chiamante richiede esplicitamente un subset della stringa, la stringa di destinazione non include un carattere Null terminante a meno che il chiamante l'ha specificato in cchDest.

Se questa funzione ha esito negativo, il buffer di destinazione potrebbe contenere risultati parziali o nessun risultato. In questo caso, tutti i risultati devono essere considerati non validi.

Nota

Quando si imposta LCMAP_UPPERCASE o LCMAP_LOWERCASE, la stringa di destinazione può usare lo stesso buffer della stringa di origine. Tuttavia, questo è fortemente sconsigliato, poiché alcune condizioni possono causare la stringa con maiuscole e minuscole restituite in modo che sia una lunghezza diversa.

[in] cchDest

Dimensioni, in caratteri, della stringa di destinazione indicata da lpDestStr. Se l'applicazione usa la funzione per il mapping di stringhe, fornisce un numero di caratteri per questo parametro. Se lo spazio per un carattere Null terminante è incluso in cchSrc, cchDest deve includere anche lo spazio per un carattere Null terminante.

Se l'applicazione usa la funzione per generare una chiave di ordinamento, fornisce un conteggio di byte per le dimensioni. Questo conteggio di byte deve includere spazio per la chiave di ordinamento 0x00 terminatore.

L'applicazione può impostare cchDest su 0. In questo caso, la funzione non usa il parametro lpDestStr e restituisce le dimensioni del buffer necessarie per la stringa o la chiave di ordinamento mappata.

[in, optional] lpVersionInformation

Puntatore a una struttura NLSVERSIONINFOEX che contiene le informazioni sulla versione relative alla funzionalità NLS pertinente; in genere recuperato da GetNLSVersionEx.

Windows Vista, Windows 7: Riservati; deve impostare su NULL.

[in, optional] lpReserved

Riservati; deve essere NULL.

[in, optional] sortHandle

Riservati; deve essere 0.

Nota

CompareStringEx e LCMapStringEx possono specificare un handle di ordinamento (se il nome delle impostazioni locali è Null). Questo uso è sconsigliato per la maggior parte delle app.

Valore restituito

Se la funzione riesce quando viene usata per il mapping di stringhe, restituisce il numero di caratteri nella stringa tradotta (vedere cchSrc e cchDest per altri dettagli).

Se la funzione ha esito positivo quando viene usata per generare una chiave di ordinamento, restituisce il numero di byte nella chiave di ordinamento.

Questa funzione restituisce 0 se non riesce. Per ottenere informazioni sull'errore estese, l'applicazione può chiamare GetLastError, che può restituire uno dei codici di errore seguenti:

ERROR_INSUFFICIENT_BUFFER. Una dimensione del buffer fornita non è stata sufficiente oppure è stata impostata in modo errato su NULL.
ERROR_INVALID_FLAGS. I valori forniti per i flag non sono validi.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.

Commenti

L'applicazione può usare LCMapString o LCMapStringEx per generare una chiave di ordinamento. A tale scopo, l'applicazione specifica LCMAP_SORTKEY per il parametro dwMapFlags . Per altre informazioni, vedere Gestione dell'ordinamento nelle applicazioni.

Nota

Le chiavi di ordinamento sono flussi di byte opachi. I chiamanti devono considerarli come una matrice di byte della lunghezza restituita dall'API e non basarsi su alcuna struttura interna che potrebbe sembrare presente. Zero, uno o più byte nella chiave di ordinamento restituita potrebbero essere 0. L'assenza o la presenza di un byte zero non devono essere previsti.

Un altro modo per l'uso dell'applicazione LCMapString o LCMapStringEx è in stringhe di mapping. In questo caso, l'applicazione non specifica LCMAP_SORTKEY per il parametro dwMapFlags , ma fornisce alcune altre combinazioni di flag. Per altre informazioni, vedere Gestione dell'ordinamento nelle applicazioni.

A partire da Windows Vista: Questa funzione può gestire i dati dalle impostazioni locali personalizzate. I dati non sono garantiti come uguali da computer a computer o tra esecuzioni di un'applicazione. Se l'applicazione deve mantenere o trasmettere dati, vedere Uso di dati locali persistenti.

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

Requisito	Valore
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