mbsrtowcs_s

Article
03/04/2013

Convertit une chaîne à caractères larges à sa représentation de chaîne à caractères multioctets.Une version de mbsrtowcs avec des améliorations de sécurité comme décrit dans Fonctionnalités de sécurité du 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
Le nombre de caractères convertis.
[out] wcstr
L'adresse de la mémoire tampon pour le résultant a converti la chaîne à caractères larges.
[out] sizeInWords
La taille d' wcstr dans les mots (caractère élargi).
[in] mbstr
Pointe vers l'emplacement de la chaîne à caractères multioctets à convertir.
[in] count
Le nombre maximal de caractères larges à stocker dans la mémoire tampon d' wcstr , sans caractère null de fin, ou _TRUNCATE.
[in] mbstate
Un pointeur vers un objet du rapport de conversion d' mbstate_t .

Valeur de retour

Zéro en cas de réussite, le code d'erreur en cas de échec.

condition d'erreur	valeur de retour et errno
wcstr est NULL et sizeInWords > 0	EINVAL
mbstr est NULL	EINVAL
la mémoire tampon de destination est trop petite pour contenir la chaîne convertie (à moins qu' count est _TRUNCATE; voir notes ci-dessous)	ERANGE

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

Notes

La fonction d' mbsrtowcs_s convertit une chaîne de caractères multioctets entrées figurant dans mbstr dans des caractères larges stockés en mémoire tampon désignée par wcstr, à l'aide de le rapport de conversion contenu dans mbstate.La conversion continuera pour chaque caractère jusqu'à ce que l'une des conditions suivantes est remplie :

Un caractère Null multioctets est produit
Un caractère multioctets valide est produit
Le nombre de caractères larges stockés en mémoire tampon d' wcstr égale count.

La chaîne de destination est toujours se terminant par null (même dans le cas d'une erreur).

Si count est la valeur spéciale _TRUNCATE, alors mbsrtowcs_s convertit autant de la chaîne que correspondra dans la mémoire tampon de destination, tout en quittant toujours la place pour une marque de fin null.

Si mbsrtowcs_s convertit correctement la chaîne source, il met la taille du caractère élargi de la chaîne convertie, y compris le terminateur null, dans *pReturnValue ( pReturnValue fourni n'est pas NULL).Cela se produit même si l'argument d' wcstr est NULL et fournit une méthode pour déterminer la taille de la mémoire tampon requise.notez que si wcstr est NULL, count est ignoré.

Si mbstate est NULL, le rapport de conversion interne d' mbstate_t est utilisé.

Si mbsrtowcs_s rencontre un caractère multioctets valide, il met -1 dans *pReturnValue, définit la mémoire tampon de destination à 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 d' mbsrtowcs_s n'est pas défini.mbsrtowcs_s est affectée par la catégorie de LC_TYPE des paramètres régionaux.

Note de sécurité
Assurez -vous qu' wcstr et mbstr ne se chevauchent pas, et qu' count reflète correctement le nombre de caractères multioctets pour convertir.

la fonction d' mbsrtowcs_s diffère de mbstowcs_s, _mbstowcs_s_l par sa capacité à redémarrer.Le rapport de conversion est stocké dans mbstate pour les appels suivants à la même transparence ou à d'autres fonctions restartable.Les résultats sont indéfinis en combinant l'utilisation des fonctions restartable et nonrestartable.Par exemple, une application utilise mbsrlen plutôt qu' mbslen, si un appel suivant à mbsrtowcs_s étaient utilisés au lieu d' mbstowcs_s.

En C++, grâce à cette fonction est simplifié par des surcharges de modèle ; les surcharges peuvent également déduire la longueur de la mémoire tampon automatiquement (en éliminant le besoin de spécifier un argument de taille) et peuvent remplacer automatiquement des fonctions plus anciennes et non sécurisées par leurs nouvelles, sécurisées équivalents.Pour plus d'informations, consultez Surcharges sécurisées de modèle.

Exceptions

La fonction d' mbsrtowcs est multithread-safe tant qu'aucune fonction dans le thread actuel n'appelle setlocale bien que cette fonction s'exécute et mbstate est null.