wcsrtombs_swcsrtombs_s

Converte una stringa di caratteri wide nella relativa rappresentazione di stringa di caratteri multibyte.Convert a wide character string to its multibyte character string representation. Questa è una versione di wcsrtombs che include miglioramenti per la sicurezza, come descritto in Funzionalità di sicurezza in CRT.A version of wcsrtombs with security enhancements as described in Security Features in the CRT.

SintassiSyntax

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  

ParametriParameters

[out] pReturnValue[out] pReturnValue
Numero di caratteri convertiti.The number of characters converted.

[out] mbstr[out] mbstr
Indirizzo di un buffer per la stringa di caratteri multibyte convertita risultante.The address of a buffer for the resulting converted multibyte character string.

[out] sizeInBytes[out] sizeInBytes
Dimensione del buffer mbstr, in byte.The size in bytes of the mbstr buffer.

[in] wcstr[in] wcstr
Punta alla stringa di caratteri wide da convertire.Points to the wide character string to be converted.

[in] count[in] count
Numero massimo di byte da archiviare nel buffer mbstr o _TRUNCATE.The maximum number of bytes to be stored in the mbstr buffer, or _TRUNCATE.

[in] mbstate[in] mbstate
Puntatore a un oggetto stato di conversione mbstate_t.A pointer to an mbstate_t conversion state object.

Valore restituitoReturn Value

Zero in caso di esito positivo, un codice di errore in caso di esito negativo.Zero if successful, an error code on failure.

Condizione di erroreError condition Valore restituito e errnoReturn value and errno
mbstr è NULL e sizeInBytes > 0mbstr is NULL and sizeInBytes > 0 EINVAL
wcstr è NULLwcstr is NULL EINVAL
Il buffer di destinazione è troppo piccolo per contenere la stringa convertita (a meno che count non sia _TRUNCATE; vedere la sezione Note di seguito)The destination buffer is too small to contain the converted string (unless count is _TRUNCATE; see Remarks below) ERANGE

Se si verifica una di queste condizioni, viene richiamata l'eccezione di parametro non valido come descritto in Convalida dei parametri.If any of these conditions occurs, the invalid parameter exception is invoked as described in Parameter Validation . Se l'esecuzione può continuare, la funzione restituisce un codice errore e imposta errno come indicato nella tabella.If execution is allowed to continue, the function returns an error code and sets errno as indicated in the table.

NoteRemarks

La funzione wcsrtombs_s converte una stringa di caratteri wide a cui punta wcstr in caratteri multibyte archiviati nel buffer a cui punta mbstr, usando lo stato di conversione contenuto in mbstate.The wcsrtombs_s function converts a string of wide characters pointed to by wcstr into multibyte characters stored in the buffer pointed to by mbstr, using the conversion state contained in mbstate. La conversione continuerà per ogni carattere fino a quando non viene soddisfatta una delle seguenti condizioni:The conversion will continue for each character until one of these conditions is met:

  • Viene rilevato un carattere Null wideA null wide character is encountered

  • Viene rilevato un carattere wide che non può essere convertitoA wide character that cannot be converted is encountered

  • Il numero di byte archiviati nel buffer mbstr è uguale a count.The number of bytes stored in the mbstr buffer equals count.

    La stringa di destinazione termina sempre con Null, anche in caso di errore.The destination string is always null-terminated (even in the case of an error).

    Se count è il valore speciale _TRUNCATE, wcsrtombs_s converte la parte di stringa più ampia possibile che può rientrare nel buffer di destinazione, lasciando però spazio per un carattere di terminazione Null.If count is the special value _TRUNCATE, then wcsrtombs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator.

    Se wcsrtombs_s converte correttamente la stringa di origine, inserisce la dimensione in byte della stringa convertita, incluso il carattere di terminazione Null, in *pReturnValue, a condizione che pReturnValue non sia NULL.If wcsrtombs_s successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into *pReturnValue (provided pReturnValue is not NULL). Ciò si verifica anche se l'argomento mbstr è NULL e consente di determinare le dimensioni del buffer richieste.This occurs even if the mbstr argument is NULL and provides a way to determine the required buffer size. Si noti che se mbstr è NULL, count viene ignorato.Note that if mbstr is NULL, count is ignored.

    Se wcsrtombs_s rileva un carattere wide che non può convertire in carattere multibyte, inserisce -1 in *pReturnValue, imposta il buffer di destinazione su una stringa vuota, imposta errno su EILSEQ e restituisce EILSEQ.If wcsrtombs_s encounters a wide character it cannot convert to a multibyte character, it puts -1 in *pReturnValue, sets the destination buffer to an empty string, sets errno to EILSEQ, and returns EILSEQ.

    Se le sequenze a cui punta wcstr e mbstr si sovrappongono, il comportamento di wcsrtombs_s non è definito.If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcsrtombs_s is undefined. wcsrtombs_s viene influenzato dalla categoria LC_TYPE delle impostazioni locali correnti.wcsrtombs_s is affected by the LC_TYPE category of the current locale.

Importante

Verificare che wcstr e mbstr non si sovrappongano e che count rispecchi correttamente il numero di caratteri wide da convertire.Ensure that wcstr and mbstr do not overlap, and that count correctly reflects the number of wide characters to convert.

La funzione wcsrtombs_s differisce da wcstombs_s, _wcstombs_s_l per la possibilità di essere riavviata.The wcsrtombs_s function differs from wcstombs_s, _wcstombs_s_l by its restartability. Lo stato di conversione viene archiviato in mbstate per le chiamate successive alle stesse o ad altre funzioni riavviabili.The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions. I risultati non sono definiti quando si usano insieme funzioni riavviabili e non riavviabili.Results are undefined when mixing the use of restartable and nonrestartable functions. Ad esempio, un'applicazione deve usare wcsrlen anziché wcslen se viene usata una chiamata successiva a wcsrtombs_s invece di wcstombs_s..For example, an application would use wcsrlen rather than wcslen, if a subsequent call to wcsrtombs_s were used instead of wcstombs_s.

In C++ l'utilizzo di queste funzioni è semplificato dagli overload dei modelli. Gli overload possono dedurre la lunghezza del buffer automaticamente (eliminando la necessità di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni precedenti e non sicure con le controparti più recenti e sicure.In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. Per altre informazioni, vedere Secure Template Overloads.For more information, see Secure Template Overloads.

EccezioniExceptions

La funzione wcsrtombs_s è multithread-safe a condizione che nessuna funzione nel thread corrente chiami setlocale mentre questa funzione è in esecuzione e mbstate è Null.The wcsrtombs_s function is multithread safe as long as no function in the current thread calls setlocale while this function is executing and the mbstate is null.

EsempioExample

// 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" );  
    }  
}  
The string was successfully converted.  

RequisitiRequirements

RoutineRoutine Intestazione obbligatoriaRequired header
wcsrtombs_s <wchar.h><wchar.h>

Vedere ancheSee Also

Data Conversion (Conversione dei dati)Data Conversion
Locale (Impostazioni locali)Locale
Interpretazione di sequenze di caratteri multibyte Interpretation of Multibyte-Character Sequences
wcrtomb wcrtomb
wcrtomb_s wcrtomb_s
wctomb, _wctomb_l wctomb, _wctomb_l
wcstombs, _wcstombs_l wcstombs, _wcstombs_l
mbsinitmbsinit