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.

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.

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

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)

[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 è terminata con 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 terminante. Pertanto, la stringa di caratteri risultante ha un carattere Null terminante e la lunghezza restituita dalla funzione include questo carattere.

Se questo parametro è impostato su un intero positivo, la funzione elabora esattamente il numero specificato di caratteri. Se la dimensione specificata non include un carattere Null terminante, 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 terminante e non usa il buffer lpMultiByteStr .

[in, optional] lpDefaultChar

Puntatore al carattere da usare 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 del 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 necessaria, in byte, per il buffer indicato da lpMultiByteStr. Vedere anche dwFlags per informazioni su come il flag di WC_ERR_INVALID_CHARS influisce sul valore restituito quando le sequenze non valide sono di input.

La 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.
• ERROR_NO_UNICODE_TRANSLATION. Unicode non valido è stato trovato 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 terminante. Per terminare una stringa di output per questa funzione, l'applicazione deve passare in modo esplicito -1 o contare in modo esplicito il carattere null terminante per la stringa di input.

Se cbMultiByte è minore di cchWideChar, questa funzione scrive il numero di caratteri specificati da cbMultiByte nel buffer indicato da lpMultiByteStr. Tuttavia, se CodePage è impostato su CP_SYMBOL e cbMultiByte è minore di cchWideChar, la funzione scrive nessun carattere 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.

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à surrogate solitarie o coppie surrogate non corrispondenti. Il codice scritto nelle versioni precedenti di Windows che si basano su questo comportamento per codificare dati binari non testuali casuali potrebbe verificarsi problemi. Tuttavia, il codice che usa questa funzione per produrre stringhe UTF-8 valide si comporta come nei sistemi operativi Windows precedenti.

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

WC_COMPOSITECHECK e flag correlati

Il flag WC_COMPOSITECHECK causa il test della funzione WideCharToMultiByte per il test dei caratteri Unicode decomposti e tenta di componerli prima di convertirli nella tabella codici richiesta. Questo flag è disponibile solo per la conversione in byte singolo (SBCS) o doppia byte (DBCS) code pages ( code pages < 50000, escluso la tabella codici 42). Se l'applicazione deve convertire i dati Unicode decomposti in pagine codici a byte singolo o 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 non inpacing aggiuntivi lasciati. Ad esempio, A + ̈ + ̈ combina a Ä + ̈ . L'uso del flag di WC_DISCARDNS causa l'eliminazione di caratteri nonpaci aggiuntivi della funzione. L'uso del flag WC_DEFAULTCHAR causa invece l'uso del carattere di sostituzione predefinito (in genere "?"). L'uso del flag WC_SEPCHARS causa il tentativo della funzione di convertire ogni carattere nonpacing aggiuntivo nella tabella codici di destinazione. In genere questo flag causa anche l'uso del carattere di sostituzione ("?"). Tuttavia, per la tabella codici 1258 (Vietnam) e 20269, i caratteri nonpacing esistono e possono essere usati. Le conversioni per queste pagine codici non sono perfette. Alcune combinazioni non vengono convertite correttamente nella tabella codici 1258 e WC_COMPOSITECHECK danneggiati 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

Vedere anche

MultiByteToWideChar

Funzioni unicode e set di caratteri

Set di caratteri e Unicode

API Vertdll disponibili nelle enclave VBS