mbsrtowcs_smbsrtowcs_s

Convertire una stringa di caratteri multibyte nelle impostazioni locali correnti in una rappresentazione di stringa di caratteri wide.Convert a multibyte character string in the current locale to its wide character string representation. Una versione di mbsrtowcs con miglioramenti per la sicurezza. come descritto in Funzionalità di sicurezza in CRT.A version of mbsrtowcs with security enhancements as described in Security Features in the CRT.

SintassiSyntax

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

ParametriParameters

pReturnValuepReturnValue
Numero di caratteri convertiti.The number of characters converted.

wcstrwcstr
Indirizzo del buffer in cui archiviare la stringa di caratteri wide convertita risultante.Address of buffer to store the resulting converted wide character string.

sizeInWordssizeInWords
Il valore pari wcstr in parole (caratteri "wide").The size of wcstr in words (wide characters).

mbstrmbstr
Puntatore indiretto alla posizione della stringa di caratteri multibyte da convertire.Indirect pointer to the location of the multibyte character string to be converted.

countcount
Il numero massimo di caratteri "wide" per l'archiviazione nel wcstr buffer, senza includere il carattere di terminazione null, o truncate.The maximum number of wide characters to store in the wcstr buffer, not including the terminating null, or _TRUNCATE.

mbstatembstate
Un puntatore a un mbstate_t oggetto stato di conversione.A pointer to an mbstate_t conversion state object. Se questo valore è un puntatore Null, viene usato un oggetto stato di conversione interno statico.If this value is a null pointer, a static internal conversion state object is used. Perché l'interno mbstate_t oggetto non è thread-safe, è consigliabile passare sempre la propria mbstate parametro.Because the internal mbstate_t object is not thread-safe, we recommend that you always pass your own mbstate parameter.

Valore restituitoReturn Value

Se la conversione viene eseguita correttamente restituisce zero, in caso contrario un codice di errore.Zero if conversion is successful, or an error code on failure.

Condizione di erroreError condition Valore restituito e errnoReturn value and errno
wcstr è un puntatore null e sizeInWords > 0wcstr is a null pointer and sizeInWords > 0 EINVALEINVAL
mbstr è un puntatore nullmbstr is a null pointer EINVALEINVAL
La stringa indirettamente a cui punta mbstr contiene una sequenza multibyte che non è valida per le impostazioni locali correnti.The string indirectly pointed to by mbstr contains a multibyte sequence that is not valid for the current locale. EILSEQEILSEQ
Il buffer di destinazione è troppo piccolo per contenere la stringa convertita (a meno che conteggio viene truncate; per ulteriori informazioni, vedere la sezione Osservazioni)The destination buffer is too small to contain the converted string (unless count is _TRUNCATE; for more information, see Remarks) ERANGEERANGE

Se si verifica una di queste condizioni, viene richiamata l'eccezione di parametro non valido come descritto in Convalida dei parametri.If any one 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 di 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

Il mbsrtowcs_s funzione converte una stringa di caratteri multibyte indirettamente a cui puntata mbstr in caratteri wide archiviati nel buffer a cui puntato wcstr, da utilizzando lo stato di conversione contenuto in mbstate.The mbsrtowcs_s function converts a string of multibyte characters indirectly pointed to by mbstr into wide characters stored in the buffer pointed to by wcstr, by 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 multibyteA multibyte null character is encountered

  • Viene rilevato un carattere multibyte non validoAn invalid multibyte character is encountered

  • Il numero di caratteri "wide" archiviati nel wcstr uguale a un buffer conteggio.The number of wide characters stored in the wcstr buffer equals count.

La stringa di destinazione wcstr è sempre con terminazione null, anche in caso di errore, a meno che non wcstr è un puntatore null.The destination string wcstr is always null-terminated, even in the case of an error, unless wcstr is a null pointer.

Se conteggio è il valore speciale truncate, mbsrtowcs_s Converte la gran parte della stringa come rientrano nel buffer di destinazione, lasciando comunque una chat room per un valore null carattere di terminazione.If count is the special value _TRUNCATE, mbsrtowcs_s converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator.

Se mbsrtowcs_s converte correttamente la stringa di origine, inserisce la dimensione in caratteri "wide" della stringa convertita e il terminatore null in *pReturnValue, fornito pReturnValue non è un puntatore null.If mbsrtowcs_s successfully converts the source string, it puts the size in wide characters of the converted string and the null terminator into *pReturnValue, provided pReturnValue is not a null pointer. Questo errore si verifica anche se il wcstr argomento è un puntatore null e permette di determinare le dimensioni del buffer richiesto.This occurs even if the wcstr argument is a null pointer and lets you determine the required buffer size. Si noti che se wcstr è un puntatore null conteggio viene ignorato.Note that if wcstr is a null pointer, count is ignored.

Se wcstr non è un puntatore null, l'oggetto del puntatore a cui punta mbstr viene assegnato un puntatore null se la conversione è stata arrestata perché è stato raggiunto un carattere di terminazione null.If wcstr is not a null pointer, the pointer object pointed to by mbstr is assigned a null pointer if conversion stopped because a terminating null character was reached. In caso contrario, viene assegnato l'indirizzo subito dopo l'ultimo carattere multibyte convertito, se presente.Otherwise, it is assigned the address just past the last multibyte character converted, if any. Ciò consente a una chiamata di funzione successiva di riavviare la conversione nel punto in cui la chiamata è stata arrestata.This allows a subsequent function call to restart conversion where this call stopped.

Se mbstate è un puntatore null, della libreria interna mbstate_t viene utilizzato l'oggetto statico dello stato di conversione.If mbstate is a null pointer, the library internal mbstate_t conversion state static object is used. Poiché l'oggetto statico interno non è thread-safe, è consigliabile che si passa la propria mbstate valore.Because this internal static object is not thread-safe, we recommend that you pass your own mbstate value.

Se mbsrtowcs_s rileva un carattere multibyte non valido nelle impostazioni locali correnti, inserisce -1 in *pReturnValue, imposta il buffer di destinazione wcstr per una stringa vuota, imposta errno alla EILSEQe restituisce EILSEQ.If mbsrtowcs_s encounters a multibyte character that is not valid in the current locale, it puts -1 in *pReturnValue, sets the destination buffer wcstr to an empty string, sets errno to EILSEQ, and returns EILSEQ.

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

Importante

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

Il mbsrtowcs_s rispetto alla funzione mbstowcs_s, mbstowcs_s_l dal relativo riavviabilità.The mbsrtowcs_s function differs from mbstowcs_s, _mbstowcs_s_l by its restartability. Lo stato di conversione viene archiviato 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 mbsrlen anziché mbslen, se una chiamata successiva a mbsrtowcs_s utilizzato al posto del mbstowcs_s.For example, an application should use mbsrlen instead of mbslen, if a subsequent call to mbsrtowcs_s is used instead of mbstowcs_s.

In C++ l'utilizzo di questa funzione è 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 usando le controparti più recenti e sicure.In C++, using this function is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the requirement to specify a size argument) and they can automatically replace older, non-secure functions by using their newer, secure counterparts. Per altre informazioni, vedere Secure Template Overloads.For more information, see Secure Template Overloads.

EccezioniExceptions

Il mbsrtowcs_s funzione è multithread-safe finché nessuna funzione nel thread corrente chiama setlocale fino a quando questa funzione è in esecuzione e il mbstate argomento non è un puntatore null.The mbsrtowcs_s function is multithread safe if no function in the current thread calls setlocale as long as this function is executing and the mbstate argument is not a null pointer.

RequisitiRequirements

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

Vedere ancheSee also

Conversione dei datiData Conversion
Impostazioni localiLocale
Interpretazione di sequenze di caratteri multibyteInterpretation of Multibyte-Character Sequences
mbrtowcmbrtowc
mbtowc, _mbtowc_lmbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_lmbstowcs_s, _mbstowcs_s_l
mbsinitmbsinit