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.

Valor retornado

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

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.

If count é o valor _TRUNCATEespecial , mbsrtowcs_s converte o máximo da string que couber no buffer de destino, enquanto ainda deixa espaço para um terminador nulo.

Se mbsrtowcs_s converter com êxito a cadeia de caracteres de origem, ele 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 wcstr argumento for um ponteiro nulo, o que permite determinar o tamanho do buffer necessário. Se wcstr for um ponteiro nulo, count é 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, ele será atribuído ao 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 foi interrompida.

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, definirá o buffer wcstr de destino como uma cadeia de caracteres vazia, definirá errno como EILSEQe retornará 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.

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 usar mbsrlen em vez de mbslen, se uma chamada subsequente para mbsrtowcs_s for usada em vez de mbstowcs_s.

Em C++, o uso dessa função é simplificado por sobrecargas de modelo; As sobrecargas podem inferir o comprimento do buffer automaticamente (eliminando o requisito de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras usando as contrapartes mais recentes 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, confira Estado global no CRT.

Exceções

A mbsrtowcs_s função será multithread segura se nenhuma função no thread atual chamar setlocale , desde que essa função esteja em execução e o mbstate argumento não seja um ponteiro nulo.

Requisitos

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