mbsrtowcs_s

Artigo
08/25/2010

Converter uma seqüência de caractere longa em sua representação de seqüência de caractere multibyte.Uma versão do mbsrtowcs com aprimoramentos de segurança sistema autônomo descrito em Aprimoramentos 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 convertida.
[out] wcstr
Endereço do buffer para a seqüência de caractere largos convertido resultante.
[out] sizeInWords
O dimensionar de wcstr em palavras (caracteres de largura).
[in]mbstr
Aponta para o local da seqüência de caractere multibyte a ser convertido.
[in]count
O número máximo de caracteres largos para armazenar o wcstr buffer, não incluindo terminação nula, 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 retornado e errno
wcstr é NULL e sizeInWords>0	EINVAL
mbstr é NULL	EINVAL
O buffer de destino é muito pequeno para conter a seqüência de caracteres convertida (a menos que count é _TRUNCATEConsulte os comentários abaixo)	ERANGE

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

Comentários

The mbsrtowcs_s função converte uma seqüência de caracteres multibyte apontada por mbstr em caracteres largos armazenados em 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:

Encontrado um caractere nulo multibyte
Encontrado um caractere inválido multibyte
O número de caracteres larga armazenados no wcstr buffer é igual a count.

A seqüência de caracteres de destino sempre é terminada por caractere nulo (até mesmo no caso de erro).

If count é o valor especial _TRUNCATE, em seguida, mbsrtowcs_s Converte sistema autônomo da seqüência de caracteres sistema autônomo couberem no buffer de destino, enquanto ainda deixa espaço para um terminador nulo.

If mbsrtowcs_s Converte a seqüência de caracteres de fonte, com êxito colocará o dimensionar em caracteres largos da seqüência de caracteres convertida, incluindo o terminador nulo, em *pReturnValue (fornecido pReturnValue não é NULL). Isso ocorre mesmo se o wcstr o argumento é NULL e fornece uma maneira para determinar o dimensionar do buffer necessário. Observe que, se wcstr é NULL, count é ignorado.

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

If mbsrtowcs_s encounters an invalid multibyte character, it puts -1 in *pReturnValue, sets the destination buffer to an empty string, sets errno to EILSEQ, and returns EILSEQ.

Se as seqüências apontada por mbstr e wcstr se sobrepõem, o comportamento do mbsrtowcs_s não está definida. mbsrtowcs_s é afetado pela categoria do LC_TYPE da localidade corrente.

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

The 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 Outros funções reinicializáveis. Os resultados são indefinidos ao misturar o uso de funções nonrestartable e reinicializáveis.Por exemplo, um aplicativo utilize mbsrlen em vez de mbslen, se uma telefonar subseqüente para mbsrtowcs_s foi usado em vez de mbstowcs_s.

No C++, uso da função é simplificado pelo modelo sobrecargas; sobrecargas de podem inferir o comprimento do buffer automaticamente (eliminando a necessidade de especificar um argumento de dimensionar) e eles podem substituir automaticamente funções não seguras, mais antigas, com suas contrapartes mais recentes e seguras.For more information, see Proteger overloads de modelo.

Exceções

The mbsrtowcs função é safe com vários threads sistema autônomo longo sistema autônomo nenhuma função nas chamadas de thread corrente setlocale durante a execução dessa função e o mbstate é nulo.