mbsrtowcs_s

 

Pour obtenir la dernière documentation sur Visual Studio 2017, consultez Documentation Visual Studio 2017.

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. Une version de mbsrtowcs avec des améliorations de sécurité comme décrit dans fonctionnalités de sécurité de la bibliothèque 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
Le nombre maximal de caractères larges à stocker dans le wcstr tampon, non compris le 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.

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

Condition d'erreurValeur de retour et errno
wcstr est un pointeur null et sizeInWords > 0EINVAL
mbstr est un pointeur nullEINVAL
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 l’une des conditions suivantes 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.

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 chaîne selon tenir dans la mémoire tampon de destination, tout en laissant la place pour une marque de fin null.

Si mbsrtowcs_s convertit correctement la chaîne source, elle place la taille en caractères étendus de la chaîne convertie et la marque de fin null dans *``pReturnValue, fourni pReturnValue n’est 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 *``pReturnValue, définit la mémoire tampon de destination wcstr sur une chaîne vide, définit errno à EILSEQet 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.

System_CAPS_ICON_important.jpg Important

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

Le mbsrtowcs_s fonction 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 Secure Template Overloads.

La fonction mbsrtowcs_s est multithread-safe si aucune fonction du thread actif n'appelle setlocale aussi longtemps que cette fonction s'exécute et que l'argument mbstate n'est pas un pointeur null.

Non applicable. Pour appeler la fonction C standard, utilisez PInvoke. Pour plus d'informations, consultez Exemples d'appel de plateforme.

RoutineEn-tête requis
mbsrtowcs_s<wchar.h>

Conversion de données
Paramètres régionaux
Interprétation des séquences de caractères multioctets
mbrtowc
mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l
mbsinit

Afficher: