mbsrtowcs_s

Artigo
06/09/2015

Converta uma cadeia de caracteres multibyte na localidade atual em sua representação de cadeia de caracteres de caractere largo. 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 convertida.
[out] wcstr
Endereço do buffer para armazenar resultante convertidos de cadeia de caracteres largos.
[out] sizeInWords
O tamanho do wcstr em palavras (caracteres largos).
[in, out] mbstr
Ponteiro indireto para o local da cadeia de caracteres multibyte a ser convertido.
[in] count
O número máximo de caracteres largos para armazenar no wcstr buffer, não incluindo a terminação nula, ou _TRUNCATE.
[in, out] mbstate
Um ponteiro para um mbstate_t objeto de estado de conversão. Se esse valor for um ponteiro nulo, um objeto de estado de conversão interna estático é usado. Porque o interno mbstate_t objeto não é thread-safe, recomendamos que você sempre passa seu próprio mbstate parâmetro.

Valor de retorno

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

Condição de erro	Valor de retorno eerrno
wcstré um ponteiro nulo e sizeInWords > 0	EINVAL
mbstré um ponteiro nulo	EINVAL
A cadeia de caracteres indiretamente apontada por mbstr contém uma seqüência multibyte 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 é _TRUNCATE; para obter mais informações, consulte comentários)	ERANGE

Se qualquer uma destas condições ocorrer, a exceção de parâmetro inválido é invocada como descrito em Validação do parâmetro . Se a execução puder 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 cadeia de caracteres multibyte indiretamente apontada 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 destas condições for atendida:

Um multibyte caractere nulo é encontrado
Um caractere multibyte inválido for encontrado
O número de caracteres largos armazenados no wcstr buffer é igual a count.

A cadeia de caracteres de destino wcstr sempre é terminada em nulo, mesmo no caso de um erro, a menos que wcstr é um ponteiro nulo.

Se count é o valor especial _TRUNCATE, mbsrtowcs_s converte máximo da cadeia de caracteres como serão caber no buffer de destino, enquanto ainda deixa espaço para um terminador nulo.

Se mbsrtowcs_s com êxito converte a cadeia de caracteres de origem, ele coloca o tamanho em caracteres largos de cadeia de caracteres convertida e o terminador nulo em *pReturnValue, fornecido pReturnValue não é um ponteiro nulo. Isso ocorre mesmo que o wcstr argumento é um ponteiro nulo e permite determinar o tamanho do buffer necessário. Observe que se wcstr é um ponteiro nulo, count será ignorado.

Se wcstr não é um ponteiro nulo, o objeto de ponteiro apontado por mbstr é atribuído um ponteiro nulo se a conversão foi interrompida porque foi atingido um caractere nulo de terminação. Caso contrário, ela é atribuída passado simplesmente endereço do último caractere multibyte convertido, se houver. Isso permite que uma chamada de função subsequentes reiniciar a conversão em que essa chamada é interrompido.

Se mbstate é um ponteiro nulo, a biblioteca interna mbstate_t objeto estático do estado de conversão é usado. Como esse objeto estático interno não é thread-safe, é recomendável que você passe suas próprias mbstate valor.

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

Se as sequências apontada por mbstr e wcstr se sobrepõem, o comportamento de mbsrtowcs_s é indefinido. mbsrtowcs_sé afetado pela categoria 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 reflete o número de caracteres multibyte para converter corretamente.

O mbsrtowcs_s função difere da 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. 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 subsequente mbsrtowcs_s é usado em vez dembstowcs_s.

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

Exceções

O mbsrtowcs_s função é safe multithread desde que nenhuma função no thread atual chama setlocale desde que essa função está em execução e o mbstate argumento não é um ponteiro nulo.