wcsrtombs_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 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

[out]pReturnValue
O número de caracteres convertidas.
[out]mbstr
O endereço de um buffer para a seqüência de caracteres multibyte convertido resultante.
[out]sizeInBytes
O tamanho em bytes da mbstr buffer.
[in]wcstr
Aponta para a seqüência de caracteres de largura a ser convertido.
[in]count
O número máximo de bytes a ser armazenado na mbstr buffer, 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
mbstris NULL and sizeInBytes > 0	EINVAL
wcstré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 wcsrtombs_s função converte uma seqüência de caracteres de largura apontada por wcstr em caracteres multibyte armazenados no buffer apontado por mbstr, 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 de largo nulo é encontrado.
Um caractere longo que não pode ser convertido é encontrado.
O número de bytes armazenados na mbstr 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, wcsrtombs_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 wcsrtombs_s com êxito, converte a seqüência de origem, ele coloca o tamanho em bytes da seqüência de caracteres convertida, incluindo o terminador null, em *pReturnValue (fornecidos pReturnValue não é NULL).Isso ocorre mesmo se o mbstr argumento é NULL e fornece uma maneira para determinar o tamanho do buffer necessário.Note that if mbstr is NULL, count is ignored.

Se wcsrtombs_s encontra um caractere largo, ele não é possível converter um caractere 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 wcstr e mbstr se sobrepõem, o comportamento de wcsrtombs_s é indefinido.wcsrtombs_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 extensos para converter.

O wcsrtombs_s função difere wcstombs_s, _wcstombs_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 wcsrlen em vez de wcslen, se uma chamada subseqüente para wcsrtombs_s foram usados em vez dewcstombs_s.

No C++, a utilização dessas funções é simplificado pela 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 wcsrtombs_s 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.

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" );
    }
}