mbsrtowcs

 

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

Convertit une chaîne de caractères multioctets dans les paramètres régionaux actuels en une chaîne de caractères larges correspondante, avec la capacité de redémarrer au milieu d'un caractère multioctet. Une version plus sécurisée de cette fonction est disponible ; consultez la page mbsrtowcs_s.

size_t mbsrtowcs(  
   wchar_t *wcstr,  
   const char **mbstr,  
   sizeof count,  
   mbstate_t *mbstate  
);  
template <size_t size>  
size_t mbsrtowcs(  
   wchar_t (&wcstr)[size],  
   const char **mbstr,  
   sizeof count,  
   mbstate_t *mbstate  
); // C++ only  

Paramètres

[out] wcstr
Adresse où stocker la chaîne de caractères larges convertie.

[in, out] mbstr
Pointeur indirect vers l'emplacement de la chaîne de caractères multioctets à convertir.

[in] count
Nombre maximal de caractères (et non pas d'octets) à convertir et à stocker dans wcstr.

[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.

Retourne le nombre de caractères correctement convertis, non compris le caractère null de fin, le cas échéant. Retourne (size_t)(-1) si une erreur s'est produite et définit errno à EILSEQ.

La fonction mbsrtowcs 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 continue pour chaque caractère jusqu'à ce que soit rencontré un caractère multioctet null de fin ou une séquence multioctet qui ne correspond pas à un caractère valide dans les paramètres régionaux actuels, ou jusqu'à ce que count caractères aient été convertis. Si mbsrtowcs rencontre le caractère null multioctet (« \0 ») avant ou au moment où count est atteint, elle le convertit en un caractère null de fin sur 16 bits et s'arrête.

Par conséquent, la chaîne de caractères larges dans wcstr est terminée par un caractère null seulement si mbsrtowcs rencontre un caractère null multioctet pendant la conversion. Si les séquences pointées par mbstr et wcstr se chevauchent, le comportement de mbsrtowcs n'est pas défini. mbsrtowcs est affecté par la catégorie LC_TYPE des paramètres régionaux actuels.

Le mbsrtowcs fonction diffère de mbstowcs, _mbstowcs_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 est utilisé à la place dembstowcs.

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 l'argument wcstr est un pointeur null, l'argument count est ignoré et mbsrtowcs retourne la taille requise en caractères larges pour la chaîne de destination. Si mbstate est un pointeur null, la fonction utilise un objet d'état de conversion mbstate_t interne statique qui n'est pas thread-safe. Si la séquence de caractères mbstr n'a pas de représentation correspondante en caractères multioctets, la valeur -1 est retournée et errno est défini à EILSEQ.

Si mbstr un pointeur null, le Gestionnaire de paramètre non valide est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, cette fonction affecte à errno la valeur EINVAL et retourne -1.

En C++, cette fonction a une surcharge de modèle qui appelle l'équivalent plus récent et sécurisé de cette fonction. Pour plus d'informations, consultez Secure Template Overloads.

La fonction mbsrtowcs 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.

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<wchar.h>

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

Afficher: