wcsrtombs_s

Artikel
02/26/2013

Konvertieren einer Zeichenfolge mit Breitzeichen zur Mehrbytezeichen zeichenfolgendarstellung.Eine Version von wcsrtombs mit unter Security Enhancements, wie in Sicherheitsfeatures im CRTbeschrieben.

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

Parameter

[out] pReturnValue
Die Anzahl von Zeichen konvertiert.
[out] mbstr
Die Adresse eines Puffers für die resultierende konvertierte Mehrbytezeichen zeichenkette.
[out] sizeInBytes
Die Größe in Byte) des Puffers mbstr .
[in] wcstr
Punkte zu konvertierende Zeichenfolge mit Breitzeichen.
[in] count
Die maximale Anzahl der im mbstr Puffer gespeichert werden soll, oder _TRUNCATEBytes.
[in] mbstate
Ein Zeiger auf einen mbstate_t Konvertierung zustands Objekt.

Rückgabewert

Beliebige wenn erfolgreich, ein Fehlercode auf Fehler.

Fehlerzustand	Rückgabewert und errno
mbstr ist NULL und sizeInBytes > 0	EINVAL
wcstr ist NULL	EINVAL
Der Zielpuffer ist zu klein, die das konvertierte Zeichenfolge aufzunehmen (es sei denn, count_TRUNCATEist. siehe Hinweise)	ERANGE

Wenn eine dieser Bedingungen auftritt, wird die ungültige Parameter ausnahme aufgerufen, wie in Parametervalidierung beschrieben.Wenn die Ausführung ermöglicht wird, um fortzufahren, gibt die Funktion einen Fehlercode zurück und legt ihn fest errno , wie in der Tabelle angegeben.

Hinweise

Die wcsrtombs_s-Funktion konvertiert eine Zeichenfolge mit Breitzeichen, die durch wcstr in die Mehrbytezeichen dargestellt werden, die im Puffer gespeichert werden, der durch mbstrunter Verwendung des zustandes Konvertierung angezeigten Text, der in mbstateenthalten ist.Die Konvertierung wird für jedes Zeichen fort, bis eine dieser Bedingungen erfüllt ist:

Ein NULL Breitzeichen auftritt
Ein Breitzeichen, das nicht konvertiert werden kann, wird gefunden
Die Anzahl der Bytes, die in mbstr Puffer gespeichert werden, entspricht count.

Die Zielzeichenfolge ist immer auf NULL endende (selbst im Falle eines Fehlers).

Wenn count um den besonderen Wert _TRUNCATEist, konvertiert wcsrtombs_s so viel der Zeichenfolge in den Zielpuffer passt, während noch Platz für ein NULL-Abschlusszeichen.

Wenn die Quellzeichenfolge wcsrtombs_s erfolgreich konvertiert, wird die Größe in Bytes der konvertierten Zeichenfolge, einschließlich des NULL-Terminators, in *pReturnValue (bereitgestelltes pReturnValue ist nicht NULL).Dies tritt auf, mbstr , selbst wenn das Argument NULL und ermöglicht die erforderliche Puffergröße zu ermitteln.Beachten Sie, dass beim mbstrNULList, count ignoriert wird.

Wenn ein Breitzeichen trifft, wcsrtombs_s nicht auf einen Mehrbytezeichen konvertieren kann, wird -1 an *einpReturnValuelegt den Zielpuffer zu einer leeren Zeichenfolge errno legt diesen fest EILSEQfest und gibt an EILSEQzurück.

Wenn die Sequenzen, die über wcstr und mbstr Überlappung, das Verhalten von wcsrtombs_s dargestellt werden, nicht definiert ist.wcsrtombs_s wurde durch die LC_TYPE-Kategorie des aktuellen Gebietsschemas betroffen.

Sicherheitshinweis
Stellen Sie sicher, dass wcstr und mbstr sich nicht überschneiden und dass count ordnungsgemäß die Anzahl der Breitzeichen, die auf Convert widerspiegelt.

Die wcsrtombs_s-Funktion unterscheidet sich von wcstombs_s, _wcstombs_s_l durch seine Neustartfähigkeit.Der Zustand der Konvertierung in mbstate für nachfolgende Aufrufe an derselben oder zu einer anderen restartable Funktionen gespeichert.Ergebnisse werden nicht definiert, wenn die Verwendung restartable und nonrestartable Funktionen kombiniert.Beispielsweise kann eine Anwendung wcsrlen statt wcslenverwenden, wenn ein nachfolgender Aufruf von wcsrtombs_swcstombs_s.nicht verwendet wurden

In C++ unter Verwendung dieser Funktionen wird von Vorlagen Operatoren vereinfacht. Die Überladungen können die Pufferlänge (die Anforderung automatisch beseitigend ableiten, die ein Argument angegeben) und können nicht-sicheren, die älteren Funktionen über ihre Äquivalente sicheren, aktuelleren automatisch ersetzen.Weitere Informationen finden Sie unter Speichern Sie Vorlagen-Überladungen.

Ausnahmen

Die wcsrtombs_s-Funktion ist multithreadsicher, solange keine Funktion im aktuellen Thread setlocale aufgerufen, während diese Funktion ausführt und mbstate NULL ist.

Beispiel

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