Funzione LCMapStringW (winnls.h)

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

Sintassi

int LCMapStringW(
  [in]            LCID    Locale,
  [in]            DWORD   dwMapFlags,
  [in]            LPCWSTR lpSrcStr,
  [in]            int     cchSrc,
  [out, optional] LPWSTR  lpDestStr,
  [in]            int     cchDest
);

Parametri

[in] Locale

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

• LOCALE_INVARIANT
• LOCALE_SYSTEM_DEFAULT
• LOCALE_USER_DEFAULT

• LOCALE_CUSTOM_DEFAULT
• LOCALE_CUSTOM_UI_DEFAULT
• LOCALE_CUSTOM_UNSPECIFIED

[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 le 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 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 il parametro su qualsiasi valore negativo per specificare che la stringa di origine è terminata con valore 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 (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.

[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.

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 il mapping di stringhe, 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.

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

Vedere Osservazioni per LCMapStringEx.

La versione ANSI di LCMapString esegue il mapping delle stringhe a e da Unicode in base alla tabella codici di Windows (ANSI) 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 windows ANSI predefinita del sistema. Tuttavia, i caratteri non definiti nella tabella codici di sistema vengono visualizzati nella stringa come punto interrogativo (?).

Requisiti

Vedere anche

CompareString

FindNLSString

GetNLSVersion

Gestione dell'ordinamento nelle applicazioni

LCMapStringEx

Supporto per la lingua nazionale

Funzioni di supporto del linguaggio nazionale