`mbsrtowcs_s`

Articolo
10/12/2023

Convertire una stringa di caratteri multibyte nelle impostazioni locali correnti in una rappresentazione di stringa di caratteri wide. Versione di con miglioramenti della mbsrtowcs sicurezza, come descritto in Funzionalità di sicurezza in CRT.

Sintassi

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

pReturnValue
Numero di caratteri convertiti.

wcstr
Indirizzo del buffer in cui archiviare la stringa di caratteri wide convertita risultante.

sizeInWords
Dimensioni di wcstr in parole (caratteri wide).

mbstr
Puntatore indiretto alla posizione della stringa di caratteri multibyte da convertire.

count
Numero massimo di caratteri wide da archiviare nel wcstr buffer, non inclusi i valori Null di terminazione o _TRUNCATE.

mbstate
Puntatore a un oggetto stato di conversione mbstate_t. Se questo valore è un puntatore Null, viene usato un oggetto stato di conversione interno statico. Poiché l'oggetto interno mbstate_t non è thread-safe, è consigliabile passare sempre il proprio mbstate parametro.

Valore restituito

Se la conversione viene eseguita correttamente restituisce zero, in caso contrario un codice di errore.

Condizione di errore	Valore restituito e `errno`
`wcstr` è un puntatore Null e `sizeInWords`> 0	`EINVAL`
`mbstr` è un puntatore Null	`EINVAL`
La stringa a cui punta `mbstr` indirettamente contiene una sequenza multibyte non valida per le impostazioni locali correnti.	`EILSEQ`
Il buffer di destinazione è troppo piccolo per contenere la stringa convertita (a meno che `count` non sia `_TRUNCATE`. Per altre informazioni, vedere Note)	`ERANGE`

Se si verifica una di queste condizioni, l'eccezione di parametro non valida viene richiamata come descritto in Convalida dei parametri . Se l'esecuzione può continuare, la funzione restituisce un codice errore e imposta errno come indicato nella tabella.

Osservazioni:

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. La conversione continuerà per ogni carattere fino a quando non viene soddisfatta una delle seguenti condizioni:

Viene rilevato un carattere Null multibyte
Viene rilevato un carattere multibyte non valido
Il numero di caratteri wide archiviati nel buffer wcstr è uguale a count.

La stringa wcstr di destinazione è sempre con terminazione Null, anche quando si verifica un errore, a meno che wcstr non sia un puntatore Null.

Se count è il valore _TRUNCATEspeciale , mbsrtowcs_s converte la maggior parte della stringa che verrà inserita nel buffer di destinazione, lasciando comunque spazio per un carattere di terminazione Null.

Se mbsrtowcs_s la stringa di origine viene convertita correttamente, inserisce le dimensioni in caratteri wide della stringa convertita e il carattere di terminazione Null in *pReturnValue, purché pReturnValue non sia un puntatore Null. La dimensione viene calcolata anche se l'argomento wcstr è un puntatore Null, che consente di determinare le dimensioni del buffer necessarie. Se wcstr è un puntatore Null, count viene ignorato.

Se wcstr non è un puntatore Null, all'oggetto puntatore a cui mbstr punta viene assegnato un puntatore Null se la conversione è stata arrestata perché è stato raggiunto un carattere Null di terminazione. In caso contrario, all'indirizzo viene assegnato solo oltre l'ultimo carattere multibyte convertito, se presente. Consente a una chiamata di funzione successiva di riavviare la conversione in cui la chiamata è stata arrestata.

Se mbstate è un puntatore Null, viene usato l'oggetto statico dello stato di conversione mbstate_t della libreria interna. Poiché questo oggetto statico interno non è thread-safe, è consigliabile passare il proprio mbstate valore.

Se mbsrtowcs_s rileva un carattere multibyte non valido nelle impostazioni locali correnti, inserisce -1 in *pReturnValue, imposta il buffer wcstr di destinazione su una stringa vuota, imposta errno su EILSEQe restituisce EILSEQ.

Se le sequenze a cui punta mbstr e wcstr si sovrappongono, il comportamento di mbsrtowcs_s non è definito. mbsrtowcs_s è interessato dalla LC_TYPE categoria delle impostazioni locali correnti.

Importante

Verificare che wcstr e mbstr non si sovrappongano e che count rispecchi correttamente il numero di caratteri multibyte da convertire.

La mbsrtowcs_s funzione differisce da mbstowcs_s, _mbstowcs_s_l in base alla riavviibilità. Lo stato di conversione viene archiviato in mbstate per le chiamate successive alle stesse o ad altre funzioni riavviabili. I risultati non sono definiti quando si usano insieme funzioni riavviabili e non riavviabili. Ad esempio, un'applicazione deve usare mbsrlen invece di mbslen, se viene usata una chiamata successiva a mbsrtowcs_s anziché mbstowcs_s.

In C++, l'uso di questa funzione è semplificato dagli overload dei modelli; gli overload possono dedurre automaticamente la lunghezza del buffer (eliminando il requisito di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni meno recenti e non sicure usando le controparti più recenti e sicure. Per altre informazioni, vedere Proteggere gli overload dei modelli.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Eccezioni

La mbsrtowcs_s funzione è multithread safe se nessuna funzione nel thread corrente chiama setlocale finché questa funzione è in esecuzione e l'argomento mbstate non è un puntatore Null.

Requisiti

Ciclo	Intestazione obbligatoria
`mbsrtowcs_s`	<wchar.h>

Vedi anche

Conversione dati
impostazioni locali
Interpretazione di sequenze di caratteri multibyte
mbrtowc
mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l
mbsinit

Condividi tramite