wcsrtombs_s

Article
03/04/2013

Convertit une chaîne à caractères larges à sa représentation de chaîne à caractères multioctets.Une version de wcsrtombs avec des améliorations de sécurité comme décrit dans Fonctionnalités de sécurité du 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
Le nombre de caractères convertis.
[out] mbstr
L'adresse d'une mémoire tampon pour le résultant a converti la chaîne à caractères multioctets.
[out] sizeInBytes
la taille en octets de la mémoire tampon d' mbstr .
[in] wcstr
Pointe sur la chaîne à caractères larges à convertir.
[in] count
Nombre maximal d'octets à stocker dans la mémoire tampon d' mbstr , 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
mbstr est NULL et sizeInBytes > 0	EINVAL
wcstr 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' wcsrtombs_s convertit une chaîne de caractères larges entrées figurant dans wcstr dans des caractères multioctets stockés en mémoire tampon désignée par mbstr, à 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 élargi null est produit
Un caractère élargi qui ne peut pas être converti est produit
Le nombre d'octets stockés en mémoire tampon d' mbstr é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 wcsrtombs_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 wcsrtombs_s convertit correctement la chaîne source, il met la taille en octets 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' mbstr est NULL et fournit une méthode pour déterminer la taille de la mémoire tampon requise.notez que si mbstr est NULL, count est ignoré.

Si wcsrtombs_s rencontre un caractère élargi qu'il ne peut pas convertir en un caractère multioctets, 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 wcstr et mbstr se chevauchent, le comportement d' wcsrtombs_s n'est pas défini.wcsrtombs_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 larges pour convertir.

la fonction d' wcsrtombs_s diffère de wcstombs_s, _wcstombs_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 wcsrlen plutôt qu' wcslen, si un appel suivant à wcsrtombs_s étaient utilisés au lieu d' wcstombs_s.

En C++, à l'aide de ces fonctions 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' wcsrtombs_s 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.

Exemple

// 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" );
    }
}