mbsrtowcs_smbsrtowcs_s

• 11/04/2016
• 8 minuti per la lettura
• Autori di contributi
  • 
  • 
  • 
  • 
  • 

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

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

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

[out] sizeInWords[out] sizeInWords
Dimensioni di wcstr in parole (caratteri wide).The size of wcstr in words (wide characters).

[in, out] mbstr[in, out] mbstr
Puntatore indiretto alla posizione della stringa di caratteri multibyte da convertire.Indirect pointer to the location of the multibyte character string to be converted.

[in] count[in] count
Numero massimo di caratteri wide da archiviare nel buffer wcstr, escluso il carattere Null di terminazione o _TRUNCATE.The maximum number of wide characters to store in the wcstr buffer, not including the terminating null, or _TRUNCATE.

[in, out] mbstate[in, out] mbstate
Puntatore a un oggetto stato di conversione mbstate_t.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. Poiché l'oggetto mbstate_t interno non è thread-safe, è consigliabile passare sempre un parametro mbstate fornito dall'utente.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.

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 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 mbsrtowcs_s converte una stringa di caratteri multibyte a cui punta indirettamente mbstr in caratteri wide archiviati nel buffer a cui punta wcstr, usando 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 buffer wcstr è uguale a count.The number of wide characters stored in the wcstr buffer equals count.

  La stringa di destinazione wcstr termina sempre con Null, anche in caso di errore, a meno che wcstr non sia 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 count è il valore speciale _TRUNCATE, mbsrtowcs_s converte la porzione di stringa più ampia possibile che può essere inclusa nel buffer di destinazione, lasciando però spazio per un carattere di terminazione Null.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 carattere di terminazione Null in *pReturnValue, a condizione che pReturnValue non sia 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. Ciò si verifica anche quando l'argomento wcstr è un puntatore Null e permette di determinare le dimensioni del buffer richieste.This occurs even if the wcstr argument is a null pointer and lets you determine the required buffer size. Se wcstr è un puntatore Null, count viene ignorato.Note that if wcstr is a null pointer, count is ignored.

  Se wcstr non è un puntatore Null, all'oggetto puntatore a cui punta mbstr viene assegnato un puntatore Null se la conversione è stata arrestata in quanto è 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, viene usato l'oggetto statico dello stato di conversione mbstate_t della libreria interna.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 passare un valore mbstate fornito dall'utente.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 su una stringa vuota, imposta errno su EILSEQ e 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 non è definito.If the sequences pointed to by mbstr and wcstr overlap, the behavior of mbsrtowcs_s is undefined. mbsrtowcs_s viene influenzato dalla categoria LC_TYPE delle impostazioni locali correnti.mbsrtowcs_s is affected by the LC_TYPE category of the current locale.

La funzione mbsrtowcs_s differisce da mbstowcs_s, _mbstowcs_s_l per la possibilità di essere riavviata.The mbsrtowcs_s function differs from mbstowcs_s, _mbstowcs_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 mbsrlen anziché mbslen se viene usata una chiamata successiva a mbsrtowcs_s anziché 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

La funzione mbsrtowcs_s è multithread-safe finché nessuna funzione nel thread corrente chiama setlocale, finché questa funzione è in esecuzione e l'argomento mbstate 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

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
mbrtowc mbrtowc
mbtowc, _mbtowc_l mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l mbstowcs_s, _mbstowcs_s_l
mbsinitmbsinit