mbsrtowcs_s

Articolo
03/05/2013

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

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

Parametri

[out] pReturnValue
il numero di caratteri convertito.
[out] wcstr
L'indirizzo del buffer per il risultato converte la stringa con caratteri estesi.
[out] sizeInWords
la dimensione di wcstr nelle parole (caratteri di tipo " wide ").
[in] mbstr
Punti al percorso della stringa di caratteri multibyte da convertire.
[in] count
Il numero massimo di caratteri di tipo " wide " da archiviare in wcstr buffer, escluso il di terminazione null, 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
wcstr viene NULL e sizeInWords > 0	EINVAL
mbstr è 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

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

Un carattere null multibyte viene rilevato
Un carattere multibyte non valido viene rilevato
Il numero di caratteri di tipo " wide " archiviati in wcstr 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 mbsrtowcs_s conversione da parte della stringa come inserito nel buffer di destinazione, pur lasciando spazio per un terminatore null.

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

se mbstate viene NULL, l'interno mbstate_t lo stato di conversione viene utilizzato.

se mbsrtowcs_s rileva un carattere multibyte non valido, 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 mbstr e wcstr sovrapposizione, il comportamento di mbsrtowcs_s è definito.mbsrtowcs_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 multibyte per la conversione.

mbsrtowcs_s la funzione è diverso da mbstowcs_s, _mbstowcs_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 mbsrlen anziché mbslen, se una chiamata successiva a mbsrtowcs_s sono stati utilizzati anziché mbstowcs_s.

In C++, l'utilizzo di questa funzione viene semplificata 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

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