mbsrtowcs_s

Article
06/09/2015

Convertir une chaîne de caractères multioctets correspondant aux paramètres régionaux actuels en sa représentation sous forme de chaîne de caractères larges. Version de mbsrtowcs avec des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le 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

Paramètres

[out] pReturnValue
Nombre de caractères convertis.
[out] wcstr
Adresse de la mémoire tampon où stocker la chaîne de caractères larges convertie.
[out] sizeInWords
La taille de wcstr en mots (caractères étendus).
[in, out] mbstr
Pointeur indirect vers l'emplacement de la chaîne de caractères multioctets à convertir.
[in] count
Nombre maximal de caractères larges à stocker dans la mémoire tampon de wcstr, à l'exclusion du caractère null de fin, ou _TRUNCATE.
[in, out] mbstate
Un pointeur vers un objet d'état de conversion mbstate_t. Si cette valeur est un pointeur null, un objet d'état de conversion interne statique est utilisé. Comme l'objet mbstate_t interne n'est pas thread-safe, nous vous recommandons de toujours passer votre propre paramètre mbstate.

Valeur de retour

Zéro si la conversion est réussie, ou un code d'erreur en cas d'échec.

Condition d'erreur	Valeur de retour et errno
wcstr est un pointeur null et sizeInWords > 0	EINVAL
mbstr est un pointeur null	EINVAL
La chaîne indirectement pointée par mbstr contient une séquence multioctets qui n'est pas valide pour les paramètres régionaux actuels.	EILSEQ
La mémoire tampon de destination est trop petite pour contenir la chaîne convertie (à moins que count ait la valeur _TRUNCATE ; pour plus d'informations, consultez les notes ci-dessous).	ERANGE

Si une de ces conditions se produit, l'exception de paramètre non valide est appelée, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à continuer, la fonction retourne un code d'erreur et définit errno, comme indiqué dans le tableau.

Notes

La fonction mbsrtowcs_s convertit une chaîne de caractères multioctets indirectement pointée par mbstr en caractères larges stockés dans la mémoire tampon pointée par wcstr, en utilisant l'état de conversion contenu dans mbstate. La conversion se poursuit pour chaque caractère jusqu'à ce qu'une des conditions suivantes soit remplie :

Un caractère multioctet de null est rencontré.
Un caractère multioctet non valide est rencontré.
Le nombre caractères larges stockés dans la mémoire tampon de wcstr est égal à count.

La chaîne de destination wcstr est toujours terminée par un caractère null, même en cas d'erreur, sauf si wcstr est un pointeur null.

Si count est la valeur spéciale _TRUNCATE, mbsrtowcs_s convertit la plus grande partie possible de la chaîne selon ce qui peut être placé dans la mémoire tampon de destination, tout en laissant de l'espace pour une marque de fin null.

Si mbsrtowcs_s convertit correctement la chaîne source, elle place la taille en caractères larges de la chaîne convertie et la marque de fin null, dans *pReturnValue, à condition que pReturnValue ne soit pas un pointeur null). Cela se produit même si l'argument wcstr est un pointeur null et vous laisse déterminer la taille de mémoire tampon requise. Notez que si wcstr est un pointeur null, count est ignoré.

Si wcstr n'est pas un pointeur null, l'objet de pointeur pointé par mbstr est affecté d'un pointeur null si la conversion a été arrêtée, car un caractère null de fin a été atteint. Sinon, il est affecté de l'adresse qui se trouve juste après le dernier caractère multioctet converti, le cas échéant. Ceci permet à un appel de fonction ultérieur de redémarrer la conversion où cet appel s'est arrêté.

Si mbstate est un pointeur null, l'objet statique d'état de la conversion mbstate_t interne de la bibliothèque est utilisé. Comme cet objet statique interne n'est pas thread-safe, nous vous recommandons de passer votre propre valeur de mbstate.

Si mbsrtowcs_s rencontre un caractère multioctet qui n'est pas valide dans les paramètres régionaux actuels, il place -1 dans *pReturnValue, définit la mémoire tampon de destination wcstr avec une chaîne vide, définit errno à EILSEQ et retourne EILSEQ.

Si les séquences pointées par mbstr et wcstr se chevauchent, le comportement de mbsrtowcs_s n'est pas défini. mbsrtowcs_s est affecté par la catégorie LC_TYPE des paramètres régionaux actuels.

Note de sécurité
Vérifiez que wcstr et mbstr ne se chevauchent pas, et que count reflète correctement le nombre de caractères multioctets à convertir.

La fonction mbsrtowcs_s diffère de mbstowcs_s, _mbstowcs_s_l par sa capacité à redémarrer. L'état de la conversion est stocké dans mbstate pour les appels suivants à la même ou à d'autres fonctions redémarrables. Les résultats ne sont pas définis quand l'utilisation de fonctions redémarrables est combinée avec l'utilisation de fonctions non redémarrables. Par exemple, une application doit utiliser mbsrlen au lieu de mbslen, si un appel ultérieur à mbsrtowcs_s est utilisé à la place dembstowcs_s.

En C++, l'utilisation de cette fonction est simplifiée par les surcharges de modèle ; les surcharges peuvent déduire la longueur de la mémoire tampon automatiquement (ce qui évite d'avoir à spécifier un argument de taille) et elles peuvent remplacer automatiquement les fonctions plus anciennes et non sécurisées par leurs équivalents plus récents et sécurisés. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

Exceptions

La fonction mbsrtowcs_s est multithread-safe tant qu'aucune fonction dans le thread actif n'appelle setlocale dès lors que cette fonction est en cours d'exécution et que l'argument mbstate n'est pas un pointeur null.