wcsrtombs_s

Artigo
06/09/2015

Converter uma cadeia de caracteres amplas em sua representação de cadeia de caracteres de vários bytes. Uma versão de wcsrtombs com aprimoramentos de segurança conforme descrito em Recursos de segurança no CRT.

errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Parâmetros

[saída] pReturnValue
O número de caracteres convertidos.
[saída] mbstr
O endereço de um buffer resultante para converter a cadeia de caracteres de vários bytes.
[saída] sizeInBytes
O tamanho em bytes do buffer de mbstr .
[entrada] wcstr
Aponta para a cadeia de caracteres amplas a ser convertida.
[entrada] count
O número máximo de bytes a serem armazenadas no buffer de mbstr , ou _TRUNCATE.
[entrada] mbstate
Um ponteiro para um objeto do estado da conversão de mbstate_t .

Valor de retorno

Zero se tiver êxito, um código de erro ou falha.

Condição de erro	Valor de retorno e errno
mbstr é NULL e sizeInBytes > 0	EINVAL
wcstr é NULL	EINVAL
O buffer de destino for muito pequeno conter a cadeia de caracteres convertida (a menos que count é _TRUNCATE; consulte os comentários abaixo)	ERANGE

Se alguma dessas condições ocorrer, a exceção inválido do parâmetro é chamada conforme descrito em Validação do parâmetro . Se a execução for permitida continuar, a função retornará um código de erro e define errno conforme indicado na tabela.

Comentários

A função de wcsrtombs_s converte uma cadeia de caracteres de caracteres amplos apontados por wcstr em caracteres multibyte armazenados em buffer apontado por mbstr, usando o estado de conversão contido em mbstate. A conversão para cada caractere continuará até que uma destas condições seja atender:

Um caractere largo nulo é encontrado
Um caractere largo que não pode ser convertido for encontrado
O número de bytes armazenados em buffer de mbstr igual count.

A cadeia de caracteres de destino tiver terminação sempre (até mesmo no caso de um erro).

Se count é o valor especial _TRUNCATE, então wcsrtombs_s converte o máximo possível da cadeia de caracteres como caiba no buffer de destino, enquanto ainda deixar de espaço para um terminador nulo.

Se wcsrtombs_s converte a cadeia de caracteres de origem, coloca o tamanho em bytes da cadeia de caracteres convertida, incluindo o terminador nulo, em *pReturnValue ( pReturnValue fornecido não for NULL). Isso ocorre mesmo se o argumento de mbstr é NULL e fornece uma maneira de determinar o tamanho de buffer necessário. Observe que se mbstr é NULL, count será ignorado.

Se wcsrtombs_s encontrar um caractere largo que não pode converter em um caracteres multibyte, o coloca -1 em *pReturnValue, define o buffer de destino em uma cadeia de caracteres vazia, define errno a EILSEQ, e retorna EILSEQ.

Se as sequências apontadas por wcstr e a sobreposição de mbstr , o comportamento de wcsrtombs_s são indefinidas. wcsrtombs_s é afetado por categoria de LC_TYPE de localidade atual.

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

A função de wcsrtombs_s difere de wcstombs_s, _wcstombs_s_l por seu restartability. O estado da conversão é armazenado em mbstate para chamadas subsequentes à mesma ou a outras funções restartable. Os resultados são definidos ao misturar o uso de funções restartable e nonrestartable. Por exemplo, um aplicativo use wcsrlen em vez de wcslen, se uma chamada subsequente a wcsrtombs_s foi usado em vez de wcstombs_s.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo; as sobrecargas podem interpretar o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente as funções menos seguras mais antigas por correspondentes mais seguras e mais recentes. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Exceções

A função de wcsrtombs_s é seguro multi-threaded desde que nenhuma função no thread atual chama setlocale quando essa função executar e mbstate for nulo.

Exemplo

// crt_wcsrtombs_s.cpp
// 
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

void main()
{
    const wchar_t   wcString[] = 
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else 
    {
        printf( "The string was successfully converted.\n" );
    }
}