Funzione FoldStringA (winnls.h)

Articolo
02/01/2024

Esegue il mapping di una stringa Unicode a un'altra, eseguendo la trasformazione specificata. Per una panoramica dell'uso delle funzioni stringa, vedere Strings.

Attenzione L'uso di FoldString in modo errato può compromettere la sicurezza dell'applicazione. Le stringhe non mappate correttamente possono produrre input non validi. Testare le stringhe per assicurarsi che siano valide prima di usarle e fornire gestori di errori. Per altre informazioni, vedere Considerazioni sulla sicurezza: Funzionalità internazionali.

Sintassi

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

Parametri

[in] dwMapFlags

Flag che specificano il tipo di trasformazione da usare durante il mapping di stringhe. Questo parametro può essere una combinazione dei valori seguenti.

Contrassegno	Significato
MAP_COMPOSITE	Eseguire il mapping dei caratteri accentati ai caratteri decomposti, ovvero i caratteri in cui un carattere di base e uno o più caratteri non crittografati hanno valori di punto di codice distinti. Ad esempio, Ä è rappresentato da A + ̈: LETTERA MAIUSCOLA LATINA A (U+0041) + COMBINAZIONE DIAERESIS (U+0308). Questo flag equivale alla normalizzazione del modulo D in Windows Vista. Si noti che questo flag non può essere usato con MB_PRECOMPOSED.
MAP_EXPAND_LIGATURES	Espandere tutti i caratteri di legatura in modo che siano rappresentati dall'equivalente a due caratteri. Ad esempio, la legatura "æ" (U+00e6) si espande ai due caratteri "a" (U+0061) + "e" (U+0065). Questo valore non può essere combinato con MAP_PRECOMPOSED o MAP_COMPOSITE.
MAP_FOLDCZONE	Piegare i caratteri della zona di compatibilità in equivalenti Unicode standard. Questo flag equivale alla normalizzazione del modulo KD in Windows Vista, se il flag di MAP_COMPOSITE è impostato anche. Se il flag composito non è impostato (impostazione predefinita), questo flag equivale alla normalizzazione del modulo KC in Windows Vista.
MAP_FOLDDIGITS	Eseguire il mapping di tutte le cifre a caratteri Unicode da 0 a 9.
MAP_PRECOMPOSED	Eseguire il mapping dei caratteri accentati a caratteri precomposti, in cui il carattere accentato e di base vengono combinati in un singolo valore di carattere. Questo flag equivale alla normalizzazione del modulo C in Windows Vista. Questo valore non può essere combinato con MAP_COMPOSITE.

[in] lpSrcStr

Puntatore a una stringa di origine mappata dalla funzione.

[in] cchSrc

Dimensioni, in caratteri, della stringa di origine indicata da lpSrcStr, escluso il carattere Null terminante. L'applicazione può impostare il parametro su qualsiasi valore negativo per specificare che la stringa di origine è terminata con valore Null. In questo caso, la funzione calcola automaticamente la lunghezza della stringa e termina automaticamente la stringa mappata indicata da lpDestStr.

[out, optional] lpDestStr

Puntatore a un buffer in cui questa funzione recupera la stringa mappata.

[in] cchDest

Dimensioni, in caratteri, della stringa di destinazione indicata da lpDestStr. Se lo spazio per un carattere Null terminante è incluso in cchSrc, cchDest deve includere anche lo spazio per un carattere Null terminante.

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 mappata. Se viene specificato il flag di MAP_FOLDDIGITS, il valore restituito è la dimensione massima necessaria, anche se il numero effettivo di caratteri necessari è inferiore alla dimensione massima. Se la dimensione massima non viene passata, la funzione ha esito negativo con ERROR_INSUFFICIENT_BUFFER.

Valore restituito

Restituisce il numero di caratteri nella stringa tradotta, incluso un carattere Null terminante, se riuscito. Se la funzione ha esito positivo e il valore di cchDest è 0, il valore restituito è la dimensione del buffer necessario per contenere la stringa tradotta, incluso un carattere null terminante.

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_DATA. I dati non sono validi.
ERROR_INVALID_FLAGS. I valori forniti per i flag non sono validi.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.
ERROR_MOD_NOT_FOUND. Il modulo non è stato trovato.
ERROR_OUTOFMEMORY. L'archiviazione non è sufficiente per completare questa operazione.
ERROR_PROC_NOT_FOUND. La procedura richiesta non è stata trovata.

Commenti

I valori dei parametri lpSrcStr e lpDestStr non devono essere uguali. Se sono uguali, la funzione ha esito negativo con ERROR_INVALID_PARAMETER.

La zona di compatibilità in Unicode è costituita da caratteri nell'intervallo 0xF900 tramite 0xFFEF assegnati a caratteri da altri standard di codifica per i caratteri, ma sono in realtà varianti di caratteri già in Unicode. La zona di compatibilità viene usata per supportare il mapping round trip a questi standard. Le applicazioni possono usare il flag MAP_FOLDCZONE per evitare di supportare la duplicazione dei caratteri nella zona di compatibilità.

A partire da Windows Vista: Questa funzione supporta la normalizzazione Unicode. Tutti i caratteri di compatibilità Unicode vengono mappati.

A partire da Windows Vista: Le trasformazioni indicate dalla MAP_FOLDCZONE, MAP_PRECOMPOSED e MAP_COMPOSITE flag usano moduli di normalizzazione Unicode KC, C e D (tramite la funzione NormalString ) per eseguire i mapping.

A partire da Windows 8: la versione ANSI della funzione viene dichiarata in Winnls.h e la versione Unicode viene dichiarata in Stringapiset.h. Prima di Windows 8, entrambe le versioni sono state dichiarate in Winnls.h.

Requisiti

Requisito	Valore
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 (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll