wcsrtombs_s

 

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

Convertir une chaîne de caractères larges en sa représentation sous forme de chaîne de caractères multioctets. Une version de wcsrtombs avec des améliorations de sécurité comme décrit dans fonctionnalités de sécurité de la bibliothèque CRT.

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

Paramètres

[out] pReturnValue
Nombre de caractères convertis.

[out] mbstr
Adresse d'une mémoire tampon pour la chaîne de caractères multioctets convertie résultante.

[out] sizeInBytes
Taille en octets de la mémoire tampon mbstr.

[in] wcstr
Pointe vers la chaîne de caractères larges à convertir.

[in] count
Le nombre maximal d’octets à stocker dans le mbstr tampon, ou _TRUNCATE.

[in] mbstate
Un pointeur vers un objet d'état de conversion mbstate_t.

Zéro si l’opération réussit, un code d’erreur en cas d’échec.

Condition d'erreurValeur de retour et errno
mbstr a la valeur NULL et sizeInBytes > 0EINVAL
wcstr a la valeur NULL.EINVAL
La mémoire tampon de destination est trop petite pour contenir la chaîne convertie (à moins que count ait la valeur _TRUNCATE ; consultez les notes ci-dessous)ERANGE

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

Le wcsrtombs_s fonction convertit une chaîne de caractères larges pointés par wcstr en caractères multioctets stockés dans la mémoire tampon vers laquelle pointée mbstr, à l’aide de 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 large null est rencontré

  • Un caractère large qui ne peut pas être converti est rencontré

  • Le nombre d'octets stockés dans la mémoire tampon mbstr est égal à count.

La chaîne de destination est toujours terminée par null (même en cas d'erreur).

Si count est la valeur spéciale _TRUNCATE, puis wcsrtombs_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 wcsrtombs_s convertit correctement la chaîne source, elle place la taille en octets de la chaîne convertie, y compris le terminateur null, en *``pReturnValue (fourni pReturnValue n’est pas NULL). Cela se produit même si l'argument mbstr a la valeur NULL, et permet de déterminer la taille de mémoire tampon requise. Notez que si mbstr a la valeur NULL, le paramètre count est ignoré.

Si wcsrtombs_s rencontre un caractère large qu’il ne peut pas convertir un caractère multioctet, il place -1 *``pReturnValue, définit la mémoire tampon de destination avec une chaîne vide, affecte errno à EILSEQet retourne EILSEQ.

Si les séquences pointées par wcstr et mbstr se chevauchent, le comportement de wcsrtombs_s n'est pas défini. wcsrtombs_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 fidèlement le nombre de caractères larges à convertir.

Le wcsrtombs_s fonction diffère de wcstombs_s, _wcstombs_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 utilise wcsrlen plutôt que wcslen, si un appel ultérieur à wcsrtombs_s ont été utilisés au lieu dewcstombs_s.

En C++, l’utilisation de ces fonctions 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 taille) et peuvent remplacer automatiquement les fonctions plus anciennes et non sécurisées par leurs équivalentes plus récentes et sécurisées. Pour plus d'informations, consultez Secure Template Overloads.

Le wcsrtombs_s fonction est multithread-safe tant qu’aucune fonction dans le thread actuel n’appelle setlocale pendant l’exécution de cette fonction et le mbstate est null.

// crt_wcsrtombs_s.cpp  
//   
// This code example converts a wide  
// character string into a multibyte  
// character string.  
//  
  
#include <stdio.h>  
#include <memory.h>  
#include <wchar.h>  
#include <errno.h>  
  
#define MB_BUFFER_SIZE 100  
  
void main()  
{  
    const wchar_t   wcString[] =   
                    {L"Every good boy does fine."};  
    const wchar_t   *wcsIndirectString = wcString;  
    char            mbString[MB_BUFFER_SIZE];  
    size_t          countConverted;  
    errno_t         err;  
    mbstate_t       mbstate;  
  
    // Reset to initial shift state  
    ::memset((void*)&mbstate, 0, sizeof(mbstate));  
  
    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,  
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);  
    if (err == EILSEQ)  
    {  
        printf( "An encoding error was detected in the string.\n" );  
    }  
    else   
    {  
        printf( "The string was successfully converted.\n" );  
    }  
}  

The string was successfully converted.  

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

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

Conversion de données
Paramètres régionaux
Interprétation des séquences de caractères multioctets
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit

Afficher: