wcsrtombs_s

 

Para obtener la documentación más reciente de Visual Studio 2017 RC, consulte Documentación de Visual Studio 2017 RC.

Convertir una cadena de caracteres anchos en su representación de cadena de caracteres multibyte. Una versión de wcsrtombs con mejoras de seguridad, como se describe en características de seguridad de 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
El número de caracteres convertidos.

[out] mbstr
La dirección de un búfer para la cadena de caracteres multibyte convertido resultante.

[out] sizeInBytes
El tamaño en bytes de la mbstr búfer.

[in] wcstr
Puntos de la cadena de caracteres anchos que se va a convertir.

[in] count
El número máximo de bytes que se almacenará en el mbstr búfer, o _TRUNCATE.

[in] mbstate
Un puntero a un objeto mbstate_t de estado de la conversión.

Devuelve cero si se ejecuta correctamente; devuelve un código de error si se produce un error.

Condición de errorValor devuelto y errno
mbstris NULL and sizeInBytes > 0EINVAL
wcstr es NULLEINVAL
El búfer de destino es demasiado pequeño para contener la cadena convertida (a menos que count es _TRUNCATE; vea la sección comentarios que aparece a continuación)ERANGE

Si ocurre alguna de estas condiciones, se invoca la excepción de parámetro no válido como se describe en validación del parámetro . Si se permite que la ejecución continúe, la función devuelve un código de error y establece errno como se indica en la tabla.

El wcsrtombs_s función convierte una cadena de caracteres anchos señalada wcstr en caracteres multibyte almacenados en el búfer señalado por mbstr, utilizando el estado de conversión contenido en mbstate. La conversión continuará para cada carácter hasta que se cumpla alguna de estas condiciones:

  • Se encontró un carácter ancho nulo

  • Se encontró un carácter ancho que no se puede convertir

  • El número de bytes almacenados en el mbstr búfer es igual a count.

La cadena de destino siempre está terminada en null (incluso en el caso de un error).

Si count es el valor especial _TRUNCATE, a continuación, wcsrtombs_s convierte tanto de la cadena como caber en el búfer de destino, dejando espacio para un terminador null.

Si wcsrtombs_s convierte correctamente la cadena de origen, pone el tamaño en bytes de la cadena convertida, incluido el terminador nulo, en *``pReturnValue (proporcionan pReturnValue no es NULL). Esto ocurre incluso si la mbstr argumento es NULL y proporciona una manera de determinar el tamaño de búfer necesario. Observe que si mbstr es NULL, count se omite.

Si wcsrtombs_s encuentra un carácter ancho no se puede convertir en un carácter multibyte, pone -1 *``pReturnValue, Establece el búfer de destino en una cadena vacía, establece errno a EILSEQy devuelve EILSEQ.

Si las secuencias señaladas por wcstr y mbstr se superponen, el comportamiento de wcsrtombs_s no está definido. wcsrtombs_s se ve afectado por la categoría LC_TYPE de la configuración regional actual.

System_CAPS_ICON_important.jpg Importante

Asegúrese de que wcstr y mbstr no se superponen y que count refleja correctamente el número de caracteres anchos a convertir.

El wcsrtombs_s función difiere de wcstombs_s, _wcstombs_s_l por su capacidad de reinicio. El estado de la conversión se almacena en mbstate para llamadas posteriores a la misma o a otras funciones reiniciables. Los resultados no están definidos cuando se combina el uso de funciones reiniciables y no reiniciables. Por ejemplo, una aplicación utilizaría wcsrlen en lugar de wcslen, si una llamada subsiguiente a wcsrtombs_s se utiliza en lugar dewcstombs_s.

En C++, el uso de estas funciones se simplifica con las sobrecargas de plantilla; las sobrecargas pueden realizar una inferencia automáticamente de la longitud de búfer (lo que elimina el requisito de especificar un argumento de tamaño) y pueden reemplazar automáticamente funciones anteriores no seguras con sus homólogos seguros más recientes. Para obtener más información, consulta Secure Template Overloads.

El wcsrtombs_s función es segura para subprocesos siempre y cuando no llama a ninguna función en el subproceso actual setlocale mientras se está ejecutando esta función y el mbstate es null.

// 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.  

No es aplicable. Para llamar a la función estándar de C, use PInvoke. Para obtener más información, vea Ejemplos de invocación de plataforma.

RutinaEncabezado necesario
wcsrtombs_s<wchar.h>

Conversión de datos
Configuración regional
Interpretación de secuencias de caracteres Multibyte
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit

Mostrar: