mbsrtowcs_s

Artículo
02/19/2013

Convierte una cadena de caracteres anchos en su representación de cadena de caracteres multibyte.Una versión de mbsrtowcs con mejoras de seguridad como se describe en Características de seguridad en 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
el número de caracteres convertido.
[out] wcstr
La dirección de búfer para producir convirtió la cadena de caracteres anchos.
[out] sizeInWords
El tamaño de wcstr en las palabras (caracteres anchos).
[in] mbstr
Señala a la ubicación de la cadena de caracteres multibyte que se va a convertir.
[in] count
El número máximo de caracteres anchos a almacenar en el búfer de wcstr , sin incluir la null final, o _TRUNCATE.
[in] mbstate
Un puntero a un objeto de estado de la conversión de mbstate_t .

Valor devuelto

Cero si es correcto, un código de error del error.

condición de error	valor devuelto y errno
wcstr es NULL y sizeInWords > 0	EINVAL
El valor de mbstr es NULL.	EINVAL
El búfer de destino es demasiado pequeño para contener la cadena convertida (a menos que count es _TRUNCATE; vea las notas siguiente)	ERANGE

Si cualquiera de estas condiciones aparecen, la excepción no válida de parámetros se invoca como se describe en Validación de parámetros .Si la ejecución puede continuar, la función devuelve un código de error y establece errno como se indica en la tabla.

Comentarios

La función de mbsrtowcs_s convierte una cadena de caracteres multibyte indicada por mbstr en los caracteres anchos almacenados en el búfer indicada por wcstr, utilizando el estado de conversión contenida en mbstate.La conversión continuará por cada carácter hasta que una de estas condiciones se cumple:

Se encuentra un carácter null multibyte
Se encuentra un carácter no válido multibyte
El número de caracteres anchos almacenados en el búfer de wcstr es igual a count.

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

Si count es el valor especial _TRUNCATE, después mbsrtowcs_s convierte tanto de la cadena que caben en el búfer de destino, mientras todavía deja el sitio para un carácter null final.

Si mbsrtowcs_s convierte correctamente la cadena de origen, coloca el tamaño en caracteres anchos de la cadena convertida, incluido el terminador nulo, en *pReturnValue ( pReturnValue proporcionado no es NULL).Esto hace que incluso si el argumento de wcstr es NULL y proporciona una manera de determinar el tamaño de búfer requerido.Tenga en cuenta que si wcstr es NULL, count se omite.

Si mbstate es NULL, utilizan el estado interno de la conversión de mbstate_t .

Si mbsrtowcs_s encuentra un carácter no válido multibyte, coloca -1 en *pReturnValue, establece el búfer de destino en una cadena vacía, establece errno a EILSEQ, y devuelve EILSEQ.

Si las secuencias designadas por a mbstr y la superposición de wcstr , el comportamiento de mbsrtowcs_s no están definidas.mbsrtowcs_s afecta a la categoría de LC_TYPE de la configuración regional actual.

Nota sobre la seguridad
Asegúrese de que wcstr y mbstr no se superpongan, y que count correctamente refleja el número de caracteres multibyte convertir.

la función de mbsrtowcs_s diferencia de mbstowcs_s, _mbstowcs_s_l por su restartability.Almacena el estado de la conversión en mbstate para las llamadas subsiguientes igual o a otras funciones reiniciables.Los resultados son indefinidos al mezclar el uso de funciones reiniciables y nonrestartable.Por ejemplo, una aplicación utilizaría mbsrlen en lugar de mbslen, si una llamada subsiguiente a mbsrtowcs_s se utilizó en lugar de mbstowcs_s.

En C++, mediante esta función es simplificado con sobrecargas de plantilla; las sobrecargas pueden deducir la longitud de búfer automáticamente (que elimina la necesidad de especificar un argumento de tamaño) y automáticamente pueden reemplazar anterior, funciones de no con sus más recientes, seguros homólogos.Para obtener más información, vea Sobrecargas de plantilla de seguridad.

Excepciones

La función de mbsrtowcs es seguro multiproceso a ninguna función en el subproceso actual llame a setlocale mientras esta función se ejecuta y mbstate es null.