wcsrtombs_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 wcsrtombs com aprimoramentos de segurança sistema autônomo descrito em Aprimoramentos 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 convertida.
[out] mbstr
O endereço de um buffer para a seqüência de caractere multibyte convertido resultante.
[out] sizeInBytes
O dimensionar em bytes do mbstr buffer.
[in]wcstr
Aponta para o caractere largo seqüência de caracteres 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 retornado e errno
mbstr é NULL e sizeInBytes>0	EINVAL
wcstr é 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 wcsrtombs_s função converte uma seqüência de caracteres largos apontada por wcstr em caracteres multibyte armazenados em buffer apontado por mbstr, 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 de largo nulo
Um caractere largo não pode ser convertido é encontrado
O número de bytes armazenados no mbstr 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, wcsrtombs_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 wcsrtombs_s com êxito converte a seqüência de caracteres de fonte, ele coloca o dimensionar em bytes da seqüência de caracteres convertida, incluindo o terminador nulo, em *pReturnValue (fornecido pReturnValue não é NULL). Isso ocorre mesmo se o mbstr o argumento é NULL e fornece uma maneira para determinar o dimensionar do buffer necessário. Observe que, se mbstr é NULL, count é ignorado.

If wcsrtombs_s encounters a wide character it cannot convert to a 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 wcstr e mbstr se sobrepõem, o comportamento do wcsrtombs_s não está definida. wcsrtombs_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 largos converter corretamente.

The 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 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 wcsrlen em vez de wcslen, se uma telefonar subseqüente para wcsrtombs_s foi usado em vez de wcstombs_s.

No C++, usando essas funções é 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 wcsrtombs_s 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.

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

The string was successfully converted.