mbsrtowcs_s

Converte uma cadeia de caracteres multibyte na localidade atual para sua representação de cadeia de caracteres largos. Uma versão de mbsrtowcs com aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

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

Parâmetros

pReturnValue
O número de caracteres convertidos.

wcstr
Endereço do buffer para armazenar a cadeia de caracteres largos convertida resultante.

sizeInWords
O tamanho do wcstr em palavras (caracteres largos).

mbstr
O ponteiro indireto para o local da cadeia de caracteres multibyte a ser convertida.

count
O número máximo de caracteres largos a serem armazenados no buffer wcstr, não incluindo o caractere nulo de terminação ou _TRUNCATE.

mbstate
Um ponteiro para um objeto do estado da conversão mbstate_t. Se esse valor for um ponteiro nulo, um objeto de estado de conversão interno estático será usado. Como o objeto interno mbstate_t não é thread-safe, recomendamos que você sempre passe seu próprio mbstate parâmetro.

Retornar valor

Zero se a conversão for bem-sucedida ou um código de erro em caso de falha.

Condição de erro	Valor retornado e errno
wcstr é um ponteiro nulo e sizeInWords> 0	EINVAL
mbstr é um ponteiro nulo	EINVAL
A cadeia de caracteres apontada indiretamente por mbstr contém uma sequência multibyte que não é válida para a localidade atual.	EILSEQ
O buffer de destino é muito pequeno para conter a cadeia de caracteres convertida (a menos que count seja _TRUNCATE, para obter mais informações, consulte Comentários abaixo)	ERANGE

Se qualquer uma dessas condições ocorrer, a exceção de parâmetro inválido será invocada conforme descrito em Validação de parâmetro . Se a execução puder continuar, a função retornará um código de erro e definirá errno conforme indicado na tabela.

Comentários

A função mbsrtowcs_s converte uma cadeia de caracteres multibyte apontada indiretamente por mbstr em caracteres largos armazenados no buffer apontado por wcstr usando o estado de conversão contido em mbstate. A conversão continuará para cada caractere até que uma das seguintes condições seja atendida:

• Um caractere nulo multibyte é encontrado

• Um caractere multibyte inválido é encontrado

• O número de caracteres largos armazenados no buffer wcstr é igual a count.

A cadeia de caracteres wcstr de destino é sempre terminada em nulo, mesmo quando há um erro, a menos que wcstr seja um ponteiro nulo.

Se count for o valor _TRUNCATEespecial , converte a maior parte da cadeia de caracteres que caberá no buffer de destino, mbsrtowcs_s enquanto ainda deixa espaço para um terminador nulo.

Se mbsrtowcs_s converter com êxito a cadeia de caracteres de origem, ela colocará o tamanho em caracteres largos da cadeia de caracteres convertida e o terminador nulo em *pReturnValue, desde pReturnValue que não seja um ponteiro nulo. O tamanho é calculado mesmo se o argumento for um ponteiro nulo, o que permite determinar o wcstr tamanho do buffer necessário. Se wcstr for um ponteiro nulo, count será ignorado.

Se wcstr não for um ponteiro nulo, o objeto de ponteiro apontado por mbstr receberá um ponteiro nulo se a conversão for interrompida porque um caractere nulo de terminação foi atingido. Caso contrário, será atribuído o endereço logo após o último caractere multibyte convertido, se houver. Ele permite que uma chamada de função subsequente reinicie a conversão onde essa chamada parou.

Se mbstate for um ponteiro nulo, um objeto estático de estado de conversão mbstate_t interno da biblioteca será usado. Como esse objeto estático interno não é thread-safe, recomendamos que você passe seu próprio mbstate valor.

Se mbsrtowcs_s encontrar um caractere multibyte que não é válido na localidade atual, ele colocará -1 em *pReturnValue, define o buffer wcstr de destino como uma cadeia de caracteres vazia, define errno como EILSEQe retorna EILSEQ.

Se as sequências apontadas por mbstr e por wcstr se sobrepuserem, o comportamento de mbsrtowcs_s será indefinido. mbsrtowcs_s é afetado LC_TYPE pela categoria da localidade atual.

Importante

Verifique se wcstr e mbstr não se sobrepõem e se count reflete corretamente o número de caracteres multibyte a ser convertido.

A mbsrtowcs_s função difere de , _mbstowcs_s_l por sua capacidade de mbstowcs_sreinicialização. O estado da conversão é armazenado em mbstate para chamadas posteriores às mesmas funções ou a outras funções reiniciáveis. Os resultados são indefinidos ao combinar o uso de funções reiniciáveis e não reiniciáveis. Por exemplo, um aplicativo deve ser usado mbsrlen em vez de , se uma chamada subsequente para mbsrtowcs_s for usada em vez de mbslenmbstowcs_s.

Em C++, o uso dessa função é simplificado por sobrecargas de modelo; As sobrecargas podem inferir o comprimento do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras usando as contrapartes mais novas e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Exceções

A mbsrtowcs_s função é segura multithread se nenhuma função nas chamadas setlocale de thread atuais, desde que essa função esteja em execução e o mbstate argumento não seja um ponteiro nulo.

Requisitos

Rotina	Cabeçalho necessário
mbsrtowcs_s	<wchar.h>

Confira também

Conversão de dados
Localidade
Interpretação de sequências de caracteres multibyte
mbrtowc
mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l
mbsinit