Funzione LCMapStringA (winnls.h)

Articolo
03/08/2023

Per le impostazioni locali specificate dall'identificatore, 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 Per motivi di interoperabilità, l'applicazione deve preferire la funzione LCMapStringEx a LCMapString perché Microsoft sta eseguendo la migrazione verso l'uso dei nomi delle impostazioni locali anziché degli identificatori delle impostazioni locali per le nuove impostazioni locali. Questa raccomandazione si applica in particolare alle impostazioni locali personalizzate, incluse quelle create da Microsoft. Qualsiasi applicazione che verrà eseguita solo in Windows Vista e versioni successive deve usare LCMapStringEx.

Sintassi

int LCMapStringA(
  [in]            LCID   Locale,
  [in]            DWORD  dwMapFlags,
  [in]            LPCSTR lpSrcStr,
  [in]            int    cchSrc,
  [out, optional] LPSTR  lpDestStr,
  [in]            int    cchDest
);

Parametri

[in] Locale

Identificatore delle impostazioni locali che specifica le impostazioni locali. È possibile utilizzare la macro MAKELCID per creare un identificatore delle impostazioni locali o usare uno dei valori predefiniti seguenti.

Sono supportati anche gli identificatori di impostazioni locali personalizzati seguenti.

[in] dwMapFlags

Flag che specificano il tipo di trasformazione da usare durante il mapping di stringhe o il tipo di chiave di ordinamento da generare. Per definizioni dettagliate, vedere il parametro dwMapFlags di LCMapStringEx.

[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 di terminazione, ma non è necessario. Se viene incluso il carattere Null di terminazione, il comportamento di mapping della funzione non viene influenzato in modo notevole perché il carattere Null di terminazione viene considerato non ordinato e viene sempre mappato a se stesso.

L'applicazione può impostare il parametro su qualsiasi valore negativo per specificare che la stringa di origine è con terminazione Null. In questo caso, se LCMapString viene usato nella modalità di mapping di stringhe, la funzione calcola la lunghezza della stringa stessa e null 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 (dispari posizionato) nella chiave di ordinamento non viene invertito.

Se il chiamante richiede in modo esplicito un subset della stringa, la stringa di destinazione non include un carattere Null di terminazione a meno che il chiamante non lo 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 una lunghezza diversa della stringa maiuscola restituita.

[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 conteggio dei caratteri per questo parametro. Se lo spazio per un carattere Null di terminazione è incluso in cchSrc, cchDest deve includere anche lo spazio per un carattere Null di terminazione.

Se l'applicazione usa la funzione per generare una chiave di ordinamento, fornisce un conteggio dei byte per le dimensioni. Questo numero 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.

Valore restituito

Se la funzione ha esito positivo 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 il mapping di stringhe, restituisce il numero di byte nella chiave di ordinamento.

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

ERROR_INSUFFICIENT_BUFFER. Le dimensioni del buffer fornite non sono sufficienti o non sono state impostate correttamente su NULL.
ERROR_INVALID_FLAGS. I valori specificati per i flag non sono validi.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.

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

ERROR_INSUFFICIENT_BUFFER. Le dimensioni del buffer fornite non sono sufficienti o non sono state impostate correttamente su NULL.
ERROR_INVALID_FLAGS. I valori specificati per i flag non sono validi.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.

Commenti

Vedere la sezione Osservazioni per LCMapStringEx.

La versione ANSI di LCMapString esegue il mapping delle stringhe da e verso Unicode in base alla tabella codici ANSI (Windows) predefinita associata alle impostazioni locali specificate. Quando la versione ANSI di questa funzione viene usata con impostazioni locali solo Unicode, la funzione può avere esito positivo perché il sistema operativo usa il valore CP_ACP, che rappresenta la tabella codici ANSI di Windows predefinita del sistema. Tuttavia, i caratteri non definiti nella tabella codici di sistema vengono visualizzati nella stringa come punto interrogativo (?).

Nota

L'intestazione winnls.h definisce LCMapString come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winnls.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll