mbsrtowcs_s

Artikel
02/26/2013

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

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

Parameter

[out] pReturnValue
Die Anzahl von Zeichen konvertiert.
[out] wcstr
Adresse des Puffers für die resultierende konvertierte Zeichenfolge mit Breitzeichen.
[out] sizeInWords
Die Größe von wcstr in den Wörtern (Breitzeichen).
[in] mbstr
Zeigt den Speicherort der zu konvertierende zeichenkette Mehrbytezeichen.
[in] count
Die maximale Anzahl der im Puffer, wcstr ohne das abschließende NULL-Zeichen zu speichern, oder _TRUNCATEder Breitzeichen.
[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
wcstr ist NULL und sizeInWords > 0	EINVAL
mbstr 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 mbsrtowcs_s-Funktion konvertiert eine Zeichenfolge mit Mehrbytezeichen, die durch mbstr in Breitzeichen dargestellt werden, die im Puffer gespeichert werden, der durch wcstrunter 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 Mehrbytes NULL-Zeichen auftritt
Ein ungültiges Mehrbytezeichen auftritt
Die Anzahl der Breitzeichen, die in wcstr 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 mbsrtowcs_s so viel der Zeichenfolge in den Zielpuffer passt, während noch Platz für ein NULL-Abschlusszeichen.

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

Wenn mbstateNULList, wird der interne Zustand mbstate_t Konvertierung verwendet.

Wenn mbsrtowcs_s ein ungültiges Mehrbytezeichen findet, gibt sie -1 in *einpReturnValuelegt den Zielpuffer zu einer leeren Zeichenfolge errno legt diesen fest EILSEQfest und gibt an EILSEQzurück.

Wenn die Sequenzen, die über mbstr und wcstr Überlappung, das Verhalten von mbsrtowcs_s dargestellt werden, nicht definiert ist.mbsrtowcs_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 Mehrbytezeichen auf Convert widerspiegelt.

Die mbsrtowcs_s-Funktion unterscheidet sich von mbstowcs_s, _mbstowcs_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 mbsrlen statt mbslenverwenden, wenn ein nachfolgender Aufruf von mbsrtowcs_smbstowcs_s.nicht verwendet wurden

In C++ unter Verwendung dieser Funktion wird durch 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 mbsrtowcs-Funktion ist multithreadsicher, solange keine Funktion im aktuellen Thread setlocale aufgerufen, während diese Funktion ausführt und mbstate NULL ist.