mbsrtowcs_s

Artigo
02/25/2013

Converta uma seqüência de caracteres longa em sua representação de seqüência de caracteres multibyte.Uma versão do mbsrtowcs com aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

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

[out]pReturnValue
O número de caracteres convertidas.
[out]wcstr
Endereço do buffer para a seqüência de caracteres largos convertido resultante.
[out]sizeInWords
O tamanho do wcstr em palavras (caracteres de largura).
[in]mbstr
Aponta para o local da seqüência de caracteres multibyte a ser convertido.
[in]count
O número máximo de caracteres extensos para armazenar o wcstr buffer, não incluindo o nulo de terminação, ou _TRUNCATE.
[in]mbstate
Um ponteiro para um mbstate_t objeto de estado de conversão.

Valor de retorno

Zero se for bem-sucedido, um código de erro em caso de falha.

Condição de erro	Valor de retorno eerrno
wcstris NULL and sizeInWords > 0	EINVAL
mbstréNULL	EINVAL
O buffer de destino é muito pequeno para conter a seqüência convertida (a menos que count é _TRUNCATE; Consulte os comentários abaixo)	ERANGE

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

Comentários

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

Um caractere nulo de vários bytes é encontrado.
Um caractere inválido de vários bytes é encontrado.
O número de caracteres de largura armazenados na wcstr de buffer é igual a count.

A seqüência de caracteres de destino sempre é terminada com nulo (mesmo no caso de um erro).

Se count é o valor especial _TRUNCATE, em seguida, mbsrtowcs_s converte o máximo da seqüência de caracteres como irá cabe no buffer de destino, enquanto ainda deixa espaço para um terminador nulo.

Se mbsrtowcs_s com êxito, converte a seqüência de origem, ele coloca o tamanho em caracteres extensos da string convertido, incluindo o terminador null, em *pReturnValue (fornecidos pReturnValue não é NULL).Isso ocorre mesmo se o wcstr argumento é NULL e fornece uma maneira para determinar o tamanho do buffer necessário.Note that if wcstr is NULL, count is ignored.

Se mbstate é NULL, o interno mbstate_t estado de conversão é usado.

Se mbsrtowcs_s encontra um caractere inválido multibyte, ele coloca -1 em *pReturnValue, define o buffer de destino como uma seqüência vazia, define errno para EILSEQe retorna EILSEQ.

Se as seqüências apontada por mbstr e wcstr se sobrepõem, o comportamento de mbsrtowcs_s é indefinido.mbsrtowcs_sé afetado pela categoria de LC_TYPE da localidade atual.

Observação de segurança
Certifique-se de que wcstr e mbstr não se sobrepõem e que count corretamente reflete o número de caracteres multibyte para converter.

O mbsrtowcs_s função difere mbstowcs_s, _mbstowcs_s_l por sua capacidade de reinicialização.O estado de conversão é armazenado em mbstate para chamadas subseqüentes para o mesmo ou outras funções reinicializáveis.Os resultados são indefinidos ao combinar o uso de funções reiniciáveis e não reiniciável.Por exemplo, um aplicativo deve usar mbsrlen em vez de mbslen, se uma chamada subseqüente para mbsrtowcs_s foram usados em vez dembstowcs_s.

No C++, usar esta função é simplificada pelo sobrecargas do modelo; os métodos sobrecarregados podem inferir o comprimento do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e eles podem substituir automaticamente os funções não seguras, mais antigas, com suas contrapartes mais recentes e seguras.Para obter mais informações, consulte Proteger Overloads de modelo.

Exceções

O mbsrtowcs função é seguro com vários threads, desde que nenhuma função no segmento atual chama setlocale enquanto esta função está sendo executado e o mbstate é nulo.