mbsrtowcs_s

Convierte una cadena de caracteres multibyte en la configuración regional actual en su representación de cadena de caracteres anchos. Una versión de mbsrtowcs con mejoras de seguridad, como se describe en Características de seguridad en CRT.

Sintaxis

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

pReturnValue
El número de caracteres convertidos.

wcstr
Dirección de búfer para almacenar la cadena de caracteres anchos convertida.

sizeInWords
Tamaño de wcstr en palabras (caracteres anchos).

mbstr
Puntero indirecto a la ubicación de la cadena de caracteres multibyte a convertir.

count
Número máximo de caracteres anchos a almacenar en el búfer wcstr, sin incluir el carácter nulo de finalización, o _TRUNCATE.

mbstate
Un puntero a un objeto mbstate_t de estado de la conversión. Si este valor es un puntero nulo, se utiliza un objeto de estado de la conversión interno estático. Dado que el objeto interno mbstate_t no es seguro para subprocesos, se recomienda pasar siempre su propio mbstate parámetro.

Valor devuelto

Cero si la conversión es correcta, o un código de error en caso de error.

Condición de error	Valor devuelto y errno
wcstr es un puntero nulo y sizeInWords> 0	EINVAL
mbstr es un puntero nulo	EINVAL
La cadena a mbstr la que apunta indirectamente contiene una secuencia multibyte que no es válida para la configuración regional actual.	EILSEQ
El búfer de destino es demasiado pequeño para contener la cadena convertida (a menos que en count se use _TRUNCATE; para obtener más información, vea la sección Comentarios)	ERANGE

Si se produce alguna de estas condiciones, se invoca la excepción de parámetro no válido como se describe en Validación de parámetros . 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.

Comentarios

La función mbsrtowcs_s convierte una cadena de caracteres multibyte indirectamente señalada por mbstr en caracteres anchos almacenados en el búfer señalado por wcstr, 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 encuentra un carácter multibyte nulo

• Se encuentra un carácter multibyte no válido

• El número de caracteres anchos almacenados en el búfer wcstr es igual a count.

La cadena wcstr de destino siempre está terminada en null, incluso cuando se produce un error, a menos que wcstr sea un puntero nulo.

Si count es el valor _TRUNCATEespecial , mbsrtowcs_s convierte tanto la cadena como caberá en el búfer de destino, mientras sigue dejando espacio para un terminador nulo.

Si mbsrtowcs_s convierte correctamente la cadena de origen, coloca el tamaño en caracteres anchos de la cadena convertida y el terminador NULL en *pReturnValue, proporcionado pReturnValue no es un puntero NULO. El tamaño se calcula incluso si el wcstr argumento es un puntero nulo, lo que le permite determinar el tamaño de búfer necesario. Si wcstr es un puntero nulo, count se omite.

Si wcstr no es un puntero nulo, al objeto de puntero al que apunta mbstr se le asigna un puntero NULO si se detiene la conversión porque se alcanzó un carácter nulo de terminación. De lo contrario, se le asigna la dirección justo después del último carácter multibyte convertido, si existe. Permite que una llamada de función posterior reinicie la conversión donde se detuvo esta llamada.

Si mbstate es un puntero nulo, se utiliza el objeto de estado de la conversión estático interno de biblioteca mbstate_t. Dado que este objeto estático interno no es seguro para subprocesos, se recomienda pasar su propio mbstate valor.

Si mbsrtowcs_s encuentra un carácter multibyte que no es válido en la configuración regional actual, coloca -1 en , establece el búfer wcstr de destino en *pReturnValueuna cadena vacía, establece en errnoEILSEQy devuelve EILSEQ.

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

Importante

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

La mbsrtowcs_s función difiere de mbstowcs_s, _mbstowcs_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 debe usar mbsrlen en lugar de mbslen, si se usa una llamada posterior a mbsrtowcs_s en lugar de mbstowcs_s.

En C++, el uso de esta función se simplifica mediante sobrecargas de plantilla; Las sobrecargas pueden deducir automáticamente la longitud del búfer (eliminando el requisito de especificar un argumento de tamaño) y pueden reemplazar automáticamente las funciones antiguas y no seguras mediante los homólogos seguros más recientes. Para obtener más información, consulte Sobrecargas de plantillas seguras.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Excepciones

La mbsrtowcs_s función es segura para varios subprocesos si no hay ninguna función en las llamadas setlocale del subproceso actual siempre que esta función se ejecute y el mbstate argumento no sea un puntero nulo.

Requisitos

Routine	Encabezado necesario
mbsrtowcs_s	<wchar.h>

Consulte también

Conversión de datos
Configuración regional
Interpretación de secuencias de caracteres multibyte
mbrtowc
mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l
mbsinit