wcsrtombs_s

Articolo
03/05/2013

Convertire una stringa di caratteri estesi nella relativa rappresentazione di stringa di caratteri multibyte.una versione di wcsrtombs con i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Parametri

[out] pReturnValue
il numero di caratteri convertito.
[out] mbstr
L'indirizzo di un buffer per la stringa convertita risultante di caratteri multibyte.
[out] sizeInBytes
La dimensione in byte mbstr buffer.
[in] wcstr
Punta alla stringa di caratteri estesi da convertire.
[in] count
Numero massimo di byte da archiviare in mbstr buffer, o _TRUNCATE.
[in] mbstate
Un puntatore a un oggetto mbstate_t oggetto stato di conversione.

Valore restituito

Zero se l'operazione viene completata correttamente, un codice di errore in caso di errore.

condizione di errore	valore restituito e errno
mbstr viene NULL e sizeInBytes > 0	EINVAL
wcstr è NULL.	EINVAL
Il buffer di destinazione è troppo piccolo per contenere la stringa convertita (tranne count viene _TRUNCATE; vedere le note di seguito)	ERANGE

Se tutte le condizioni si verifica, l'eccezione non valida di parametro viene richiamata come descritto in Convalida dei parametri .Se l'esecuzione è consentita per continuare, la funzione restituisce un codice di errore e set errno come indicato nella tabella.

Note

wcsrtombs_s la funzione converte una stringa di caratteri di tipo " wide " fa riferimento a da wcstr i caratteri multibyte memorizzati nel buffer indicato da mbstr, utilizzando lo stato di conversione contenuto in mbstate.La conversione continuerà per ogni carattere fino a riempire una di queste condizioni:

Un carattere di tipo " wide " null viene rilevato
Un carattere di tipo " wide " che non può essere convertito viene rilevato
Il numero di byte archiviati in mbstr uguali del buffer count.

La stringa di destinazione è sempre con terminazione null (anche nel caso di un errore).

se count è il valore speciale _TRUNCATE, quindi wcsrtombs_s conversione da parte della stringa come inserito nel buffer di destinazione, pur lasciando spazio per un terminatore null.

se wcsrtombs_s correttamente converte la stringa di origine, inserire la dimensione in byte della stringa convertita, incluso il carattere di terminazione null, in *pReturnValue (fornito pReturnValue non viene NULL).Questo accade anche se mbstr l'argomento è NULL e consente di determinare la dimensione del buffer necessarie.si noti che se mbstr viene NULL, count viene ignorato.

se wcsrtombs_s rileva un carattere di tipo " wide " che non può convertire a un carattere multibyte, viene inserito -1 in *pReturnValue, imposta il buffer di destinazione su una stringa vuota, impostare errno in EILSEQe restituisce EILSEQ.

Se le sequenze puntassero da wcstr e mbstr sovrapposizione, il comportamento di wcsrtombs_s è definito.wcsrtombs_s è interessati alla categoria di LC_TYPE delle impostazioni locali correnti.

Nota sulla sicurezza
Assicurarsi che wcstr e mbstr non si sovrappone e quello count correttamente riflette il numero di caratteri di tipo " wide " per la conversione.

wcsrtombs_s la funzione è diverso da wcstombs_s, _wcstombs_s_l dal restartability.Lo stato di conversione viene archiviato in mbstate per le chiamate successive agli stessi o ad altre funzioni restartable.I risultati vengono definiti quando si combinano l'utilizzo delle funzioni restartable e nonrestartable.Ad esempio, un'applicazione utilizzerebbe wcsrlen anziché wcslen, se una chiamata successiva a wcsrtombs_s sono stati utilizzati anziché wcstombs_s.

In C++, utilizzando queste funzioni è semplificato dagli overload del modello; gli overload possono dedurre la lunghezza del buffer automaticamente (che elimina la necessità di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni precedenti e non sicure con le più recenti, controparti sicure.Per ulteriori informazioni, vedere Assicurarsi che gli overload del modello.

Eccezioni

wcsrtombs_s la funzione è multithread-safe se nessuna funzione nelle chiamate del thread corrente setlocale questa funzione è in esecuzione e mbstate è null.

Esempio

// crt_wcsrtombs_s.cpp
// 
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

void main()
{
    const wchar_t   wcString[] = 
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else 
    {
        printf( "The string was successfully converted.\n" );
    }
}