Funzione WideCharToMultiByte (stringapiset.h)

Esegue il mapping di una stringa UTF-16 (carattere wide) a una nuova stringa di caratteri. La nuova stringa di caratteri non è necessariamente da un set di caratteri multibyte.

Attenzione L'uso della funzione WideCharToMultiByte in modo non corretto può compromettere la sicurezza dell'applicazione. La chiamata a questa funzione può causare facilmente un sovraccarico del buffer perché le dimensioni del buffer di input indicate da lpWideCharStr equivalgono al numero di caratteri nella stringa Unicode, mentre le dimensioni del buffer di output indicate da lpMultiByteStr equivalgono al numero di byte. Per evitare un sovraccarico del buffer, l'applicazione deve specificare una dimensione del buffer appropriata per il tipo di dati ricevuto dal buffer.

I dati convertiti da UTF-16 a codifiche non Unicode sono soggetti a perdita di dati, perché una tabella codici potrebbe non essere in grado di rappresentare ogni carattere usato nei dati Unicode specifici. Per altre informazioni, vedere Considerazioni sulla sicurezza: Funzionalità internazionali.

 
Nota Le tabelle codici ANSI possono essere diverse in computer diversi o possono essere modificate per un singolo computer, causando il danneggiamento dei dati. Per i risultati più coerenti, le applicazioni devono usare Unicode, ad esempio UTF-8 o UTF-16, anziché una tabella codici specifica, a meno che gli standard legacy o i formati di dati non impediscano l'uso di Unicode. Se non è possibile usare Unicode, le applicazioni devono contrassegnarlo con il nome di codifica appropriato quando i protocolli lo consentono. I file HTML e XML consentono l'assegnazione di tag, ma i file di testo non lo fanno.
 

Sintassi

int WideCharToMultiByte(
  [in]            UINT                               CodePage,
  [in]            DWORD                              dwFlags,
  [in]            _In_NLS_string_(cchWideChar)LPCWCH lpWideCharStr,
  [in]            int                                cchWideChar,
  [out, optional] LPSTR                              lpMultiByteStr,
  [in]            int                                cbMultiByte,
  [in, optional]  LPCCH                              lpDefaultChar,
  [out, optional] LPBOOL                             lpUsedDefaultChar
);

Parametri

[in] CodePage

Tabella codici da usare per eseguire la conversione. Questo parametro può essere impostato sul valore di qualsiasi tabella codici installata o disponibile nel sistema operativo. Per un elenco delle tabelle codici, vedere Identificatori della tabella codici. L'applicazione può anche specificare uno dei valori illustrati nella tabella seguente.

Valore Significato
CP_ACP
Tabella codici ANSI di Windows predefinita del sistema.
Nota Questo valore può essere diverso in computer diversi, anche nella stessa rete. Può essere modificato nello stesso computer, con conseguente danneggiamento irreversibile dei dati archiviati. Questo valore è destinato solo all'uso temporaneo e all'archiviazione permanente deve usare UTF-16 o UTF-8, se possibile.
 
CP_MACCP
Tabella codici Macintosh di sistema corrente.
Nota Questo valore può essere diverso in computer diversi, anche nella stessa rete. Può essere modificato nello stesso computer, con conseguente danneggiamento irreversibile dei dati archiviati. Questo valore è destinato solo all'uso temporaneo e all'archiviazione permanente deve usare UTF-16 o UTF-8, se possibile.
 
Nota Questo valore viene usato principalmente nel codice legacy e in genere non deve essere necessario perché i computer Macintosh moderni usano Unicode per la codifica.
 
CP_OEMCP
Tabella codici OEM di sistema corrente.
Nota Questo valore può essere diverso in computer diversi, anche nella stessa rete. Può essere modificato nello stesso computer, con conseguente danneggiamento irreversibile dei dati archiviati. Questo valore è destinato solo all'uso temporaneo e all'archiviazione permanente deve usare UTF-16 o UTF-8, se possibile.
 
CP_SYMBOL
Windows 2000: Tabella codici simbolo (42).
CP_THREAD_ACP
Windows 2000: Tabella codici ANSI di Windows per il thread corrente.
Nota Questo valore può essere diverso in computer diversi, anche nella stessa rete. Può essere modificato nello stesso computer, con conseguente danneggiamento irreversibile dei dati archiviati. Questo valore è destinato solo all'uso temporaneo e all'archiviazione permanente deve usare UTF-16 o UTF-8, se possibile.
 
CP_UTF7
UTF-7. Utilizzare questo valore solo quando viene forzato da un meccanismo di trasporto a 7 bit. L'uso di UTF-8 è preferibile. Con questo valore impostato, lpDefaultChar e lpUsedDefaultChar devono essere impostati su NULL.
CP_UTF8
UTF-8. Con questo valore impostato, lpDefaultChar e lpUsedDefaultChar devono essere impostati su NULL.

[in] dwFlags

Flag che indicano il tipo di conversione. L'applicazione può specificare una combinazione dei valori seguenti. La funzione esegue più rapidamente quando non è impostato nessuno di questi flag. L'applicazione deve specificare WC_NO_BEST_FIT_CHARS e WC_COMPOSITECHECK con il valore specifico WC_DEFAULTCHAR per recuperare tutti i risultati di conversione possibili. Se non vengono forniti tutti e tre i valori, mancano alcuni risultati.

Valore Significato
WC_COMPOSITECHECK
Converte i caratteri compositi, costituiti da un carattere di base e da un carattere senza spaziatura, ognuno con valori di carattere diversi. Convertire questi caratteri in caratteri precomposti, che hanno un singolo valore di carattere per una combinazione di caratteri di base senza spaziatura. Ad esempio, nel carattere è, l'e è il carattere di base e il segno di gravità principale è il carattere senza spaziatura.
Nota Windows rappresenta in genere stringhe Unicode con dati precomposti, rendendo non necessario l'uso del flag di WC_COMPOSITECHECK.
 

L'applicazione può combinare WC_COMPOSITECHECK con uno dei flag seguenti, con l'impostazione predefinita WC_SEPCHARS. Questi flag determinano il comportamento della funzione quando non è disponibile alcun mapping precomposto per una combinazione di caratteri di base senza spaziatura in una stringa Unicode. Se nessuno di questi flag viene fornito, la funzione si comporta come se il flag WC_SEPCHARS sia impostato. Per altre informazioni, vedere WC_COMPOSITECHECK e flag correlati nella sezione Osservazioni .

WC_DEFAULTCHAR Sostituire le eccezioni con il carattere predefinito durante la conversione.
WC_DISCARDNS Elimina i caratteri senza spaziatura durante la conversione.
WC_SEPCHARS Valore predefinito. Generare caratteri separati durante la conversione.
 
WC_ERR_INVALID_CHARS
Windows Vista e versioni successive: Esito negativo (restituendo 0 e impostando l'ultimo codice di errore su ERROR_NO_UNICODE_TRANSLATION) se viene rilevato un carattere di input non valido. È possibile recuperare l'ultimo codice di errore con una chiamata a GetLastError. Se questo flag non è impostato, la funzione sostituisce le sequenze non valide con U+FFFD (codificato come appropriato per la tabella codici specificata) e riesce restituendo la lunghezza della stringa convertita. Si noti che questo flag si applica solo quando CodePage viene specificato come CP_UTF8 o 54936. Non può essere usato con altri valori della tabella codici.
WC_NO_BEST_FIT_CHARS
Tradurre tutti i caratteri Unicode che non vengono convertiti direttamente in equivalenti multibyte al carattere predefinito specificato da lpDefaultChar. In altre parole, se la conversione da Unicode a multibyte e nuovamente in Unicode non restituisce lo stesso carattere Unicode, la funzione usa il carattere predefinito. Questo flag può essere usato da solo o in combinazione con gli altri flag definiti.

Per le stringhe che richiedono la convalida, ad esempio file, risorse e nomi utente, l'applicazione deve usare sempre il flag WC_NO_BEST_FIT_CHARS. Questo flag impedisce alla funzione di eseguire il mapping di caratteri a caratteri simili ma con semantica molto diversa. In alcuni casi, la modifica semantica può essere estrema. Ad esempio, il simbolo per "∞" (infinito) viene mappato a 8 (otto) in alcune tabelle codici.

 

Per le tabelle codici elencate di seguito, dwFlags deve essere 0. In caso contrario, la funzione ha esito negativo con ERROR_INVALID_FLAGS.

  • 50220
  • 50221
  • 50222
  • 50225
  • 50227
  • 50229
  • Da 57002 a 57011
  • 65000 (UTF-7)
  • 42 (simbolo)
Nota Per la tabella codici 65001 (UTF-8) o la tabella codici 54936 (GB18030, Windows Vista e versioni successive), dwFlags deve essere impostato su 0 o WC_ERR_INVALID_CHARS. In caso contrario, la funzione ha esito negativo con ERROR_INVALID_FLAGS.
 

[in] lpWideCharStr

Puntatore alla stringa Unicode da convertire.

[in] cchWideChar

Dimensioni, in caratteri, della stringa indicata da lpWideCharStr. In alternativa, questo parametro può essere impostato su -1 se la stringa è con terminazione Null. Se cchWideChar è impostato su 0, la funzione ha esito negativo.

Se questo parametro è -1, la funzione elabora l'intera stringa di input, incluso il carattere null di terminazione. Pertanto, la stringa di caratteri risultante ha un carattere Null di terminazione e la lunghezza restituita dalla funzione include questo carattere.

Se questo parametro è impostato su un numero intero positivo, la funzione elabora esattamente il numero specificato di caratteri. Se le dimensioni specificate non includono un carattere Null di terminazione, la stringa di caratteri risultante non viene terminata con null e la lunghezza restituita non include questo carattere.

[out, optional] lpMultiByteStr

Puntatore a un buffer che riceve la stringa convertita.

[in] cbMultiByte

Dimensioni, in byte, del buffer indicato da lpMultiByteStr. Se questo valore è 0, la funzione restituisce le dimensioni del buffer necessarie, in byte, incluso qualsiasi carattere Null di terminazione e non usa il buffer lpMultiByteStr .

[in, optional] lpDefaultChar

Puntatore al carattere da utilizzare se non è possibile rappresentare un carattere nella tabella codici specificata. L'applicazione imposta questo parametro su NULL se la funzione deve usare un valore predefinito di sistema. Per ottenere il carattere predefinito del sistema, l'applicazione può chiamare la funzione GetCPInfo o GetCPInfoEx .

Per le impostazioni di CP_UTF7 e CP_UTF8 per CodePage, questo parametro deve essere impostato su NULL. In caso contrario, la funzione ha esito negativo con ERROR_INVALID_PARAMETER.

[out, optional] lpUsedDefaultChar

Puntatore a un flag che indica se la funzione ha usato un carattere predefinito nella conversione. Il flag è impostato su TRUE se non è possibile rappresentare uno o più caratteri nella stringa di origine nella tabella codici specificata. In caso contrario, il flag è impostato su FALSE. Questo parametro può essere impostato su NULL.

Per le impostazioni di CP_UTF7 e CP_UTF8 per CodePage, questo parametro deve essere impostato su NULL. In caso contrario, la funzione ha esito negativo con ERROR_INVALID_PARAMETER.

Valore restituito

In caso di esito positivo, restituisce il numero di byte scritti nel buffer a cui punta lpMultiByteStr. Se la funzione ha esito positivo e cbMultiByte è 0, il valore restituito è la dimensione richiesta, espressa in byte, per il buffer indicato da lpMultiByteStr. Vedi anche dwFlags per informazioni su come il flag WC_ERR_INVALID_CHARS influisce sul valore restituito quando vengono immesse sequenze non valide.

La 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.
  • ERROR_NO_UNICODE_TRANSLATION. È stato trovato Unicode non valido in una stringa.

Commenti

I puntatori lpMultiByteStr e lpWideCharStr non devono essere uguali. Se sono uguali, la funzione ha esito negativo e GetLastError restituisce ERROR_INVALID_PARAMETER.

WideCharToMultiByte non termina una stringa di output se la lunghezza della stringa di input viene specificata in modo esplicito senza un carattere Null di terminazione. Per terminare null una stringa di output per questa funzione, l'applicazione deve passare -1 o contare in modo esplicito il carattere null di terminazione per la stringa di input.

Se cbMultiByte è minore di cchWideChar, questa funzione scrive il numero di caratteri specificato da cbMultiByte nel buffer indicato da lpMultiByteStr. Tuttavia, se CodePage è impostato su CP_SYMBOL e cbMultiByte è minore di cchWideChar, la funzione non scrive caratteri in lpMultiByteStr.

La funzione WideCharToMultiByte funziona in modo più efficiente quando sia lpDefaultChar che lpUsedDefaultChar sono impostati su NULL. Nella tabella seguente viene illustrato il comportamento della funzione per le quattro possibili combinazioni di questi parametri.

lpDefaultChar lpUsedDefaultChar Risultato
NULL NULL Nessun controllo predefinito. Queste impostazioni dei parametri sono quelle più efficienti da usare con questa funzione.
Carattere non Null NULL Usa il carattere predefinito specificato, ma non imposta lpUsedDefaultChar.
NULL Carattere non Null Usa il carattere predefinito del sistema e imposta lpUsedDefaultChar , se necessario.
Carattere non Null Carattere non Null Usa il carattere predefinito specificato e imposta lpUsedDefaultChar , se necessario.
 

A partire da Windows Vista, questa funzione è completamente conforme alla specifica Unicode 4.1 per UTF-8 e UTF-16. La funzione usata nei sistemi operativi precedenti codifica o decodifica le metà dei surrogati solitari o le coppie di surrogati non corrispondenti. Il codice scritto nelle versioni precedenti di Windows che si basano su questo comportamento per codificare dati binari non di testo casuali potrebbe verificarsi problemi. Tuttavia, il codice che usa questa funzione per produrre stringhe UTF-8 valide avrà lo stesso comportamento dei sistemi operativi Windows precedenti.

A partire da Windows 8: WideCharToMultiByte viene dichiarato in Stringapiset.h. Prima di Windows 8, è stato dichiarato in Winnls.h.

WC_COMPOSITECHECK e flag correlati

Come illustrato in Uso della normalizzazione Unicode per rappresentare stringhe, Unicode consente più rappresentazioni della stessa stringa (interpretata in modo linguistico). Ad esempio, la maiuscola A con dieresi (umlaut) può essere rappresentata come un singolo punto di codice Unicode "Ä" (U+00C4) o scomposto come combinazione di maiuscole e minuscole e carattere di dieresi combinato ("A" + " ̈", ovvero U+0041 U+0308). Tuttavia, la maggior parte delle tabelle codici fornisce solo caratteri composti.

Il flag WC_COMPOSITECHECK fa sì che la funzione WideCharToMultiByte testi i caratteri Unicode scomposti e tenti di componerli prima di convertirli nella tabella codici richiesta. Questo flag è disponibile solo per la conversione in tabelle codici a byte singolo (SBCS) o a byte doppio (DBCS) (tabelle < codici 50000, esclusa la tabella codici 42). Se l'applicazione deve convertire i dati Unicode scomposti in tabelle codici a byte singolo o a doppio byte, questo flag potrebbe essere utile. Tuttavia, non tutti i caratteri possono essere convertiti in questo modo ed è più affidabile salvare e archiviare dati come Unicode.

Quando un'applicazione usa WC_COMPOSITECHECK, alcune combinazioni di caratteri potrebbero rimanere incomplete o potrebbero avere caratteri aggiuntivi senza spaziatura rimanenti. Ad esempio, A + ̈ + ̈ combina a Ä + ̈. L'uso del flag WC_DISCARDNS causa l'eliminazione di caratteri aggiuntivi senza spaziatura. L'uso del flag WC_DEFAULTCHAR fa sì che la funzione usi invece il carattere di sostituzione predefinito (in genere "?"). L'uso del flag WC_SEPCHARS fa sì che la funzione tenti di convertire ogni carattere aggiuntivo senza spaziatura nella tabella codici di destinazione. In genere questo flag causa anche l'uso del carattere di sostituzione ("?"). Tuttavia, per la tabella codici 1258 (vietnamita) e 20269, esistono caratteri senza spaziatura e possono essere usati. Le conversioni per queste tabelle codici non sono perfette. Alcune combinazioni non vengono convertite correttamente nella tabella codici 1258 e WC_COMPOSITECHECK danneggiano i dati nella tabella codici 20269. Come accennato in precedenza, è più affidabile progettare l'applicazione per salvare e archiviare dati come Unicode.

Esempio

ISDSC_STATUS DiscpUnicodeToAnsiSize(
    IN __in PWCHAR UnicodeString,
    OUT ULONG *AnsiSizeInBytes
    )
/*++
Routine Description:
    This routine will return the length needed to represent the unicode
    string as ANSI
Arguments:
    UnicodeString is the unicode string whose ansi length is returned
    *AnsiSizeInBytes is number of bytes needed to represent unicode
        string as ANSI
Return Value:
    ERROR_SUCCESS or error code
--*/
{
    _try
    {
        *AnsiSizeInBytes = WideCharToMultiByte(CP_ACP,
                                               0,
                                               UnicodeString,
                                               -1,
                                               NULL,
                                               0, NULL, NULL);
    } _except(EXCEPTION_EXECUTE_HANDLER) {
        return(ERROR_NOACCESS);
    }
    return((*AnsiSizeInBytes == 0) ? GetLastError() : ERROR_SUCCESS);
}

Requisiti

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

Vedere anche

MultiByteToWideChar

Funzioni unicode e set di caratteri

Set di caratteri e Unicode