mbsrtowcs_s

Článek
06/09/2015

Převeďte řetězec více znaků v aktuální národní prostředí na řetězcovou reprezentaci širokého znaku.Verzi mbsrtowcs s vylepšení zabezpečení, jak je popsáno v Funkce zabezpečení v CRT.

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

Parametry

[limit]pReturnValue
Počet znaků převést.
[limit]wcstr
Adresa vyrovnávací paměti pro uložení výsledný převést řetězec širokého znaku.
[limit]sizeInWords
Velikost wcstr slovy (široké znaky).
[ve out]mbstr
Nepřímý odkaz na umístění vícebajtový řetězec, který má být převeden.
[v]count
Maximální počet široké znaky uložit wcstr vyrovnávací paměti není včetně ukončující null, nebo _TRUNCATE.
[ve out]mbstate
Ukazatel na mbstate_t převodu stavu objektu.Pokud je tato hodnota ukazatel s hodnotou null, se používá objekt statické vnitřní převod stavu.Protože interní mbstate_t objekt není vláken, doporučujeme, aby vždy předáte vlastní mbstate parametru.

Vrácená hodnota

Nula, pokud je převod úspěšný, nebo kód chyby při selhání.

Chybový stav	Vrátí hodnotu, aerrno
wcstrje ukazatel s hodnotou null a sizeInWords > 0	EINVAL
mbstrje ukazatel s hodnotou null	EINVAL
Řetězec nepřímo odkazuje mbstr obsahuje více pořadí, který není platný pro aktuální národní prostředí.	EILSEQ
Cílová vyrovnávací paměť je příliš malá tak, aby obsahovala převedený řetězec (není-li count je _TRUNCATE; Další informace naleznete v oddílu poznámky)	ERANGE

Dojde-li některou z těchto podmínek, je vyvolána neplatný parametr výjimky, jak je popsáno v Ověření parametru .Pokud je povoleno spuštění chcete-li pokračovat, vrátí funkce chybový kód a nastaví errno jak je uvedeno v tabulce.

Poznámky

mbsrtowcs_s Funkce převede řetězec středník nepřímo odkazuje mbstr do široké znaky, které jsou uloženy ve vyrovnávací paměti, na kterou odkazuje wcstr, s použitím převod stav obsažených v mbstate.Převod na pro každý znak bude pokračovat, dokud nebude splněna jedna z těchto podmínek:

Dojde k více prázdný znak
Neplatný znak více nebude nalezen.
Počet široké znaky, které jsou uloženy v wcstr vyrovnávací paměti je rovno count.

Cílový řetězec wcstr je vždy ukončený hodnotou null, dokonce i v případě chybu, pokud wcstr je ukazatel s hodnotou null.

Pokud count je speciální hodnota _TRUNCATE, mbsrtowcs_s převede co největší řetězec jako se nevejde do cílové vyrovnávací paměti stále nechejte místo pro zakončením hodnotu null.

Pokud mbsrtowcs_s úspěšně převede řetězec zdroje Vloží velikost v široké znaky převedený řetězec a null ukončení do *pReturnValue, zadané pReturnValue není ukazatel s hodnotou null.K tomu dochází i v případě, wcstr argument je ukazatel s hodnotou null a umožňuje určit velikost požadované vyrovnávací paměti.Všimněte si, že pokud wcstr je ukazatel s hodnotou null, count je ignorována.

Pokud wcstr není ukazatel s hodnotou null, objekt ukazatel na kterou odkazuje mbstr je přiřazen ukazatel s hodnotou null, pokud převod zastavena, protože bylo dosaženo ukončující znak null.Jinak je přiřazena adresa minulosti pouze poslední více znak převést, pokud existuje.To umožňuje volání funkce následné restartování převodu, kde byla zastavena toto volání.

Pokud mbstate je ukazatel s hodnotou null, interní knihovna mbstate_t převodu stavu statický objekt se používá.Vzhledem k tomu, že tento interní statický objekt není vláken, doporučujeme, aby předáte vlastní mbstate hodnotu.

Pokud mbsrtowcs_s zaznamená více znak, který není platný v aktuální národní prostředí je převádí na hodnotu -1 *pReturnValue, nastaví cílové vyrovnávací paměti wcstr na prázdný řetězec, nastaví errno k EILSEQa vrátí EILSEQ.

Pokud je sekvence na kterou odkazuje mbstr a wcstr překrývají, chování mbsrtowcs_s není definováno.mbsrtowcs_sbude mít vliv na LC_TYPE kategorii aktuální národní prostředí.

Poznámka k zabezpečení
Ujistěte se, zda wcstr a mbstr nepřekrývá a že count správně zobrazuje počet středník převést.

mbsrtowcs_s Funkce se liší od mbstowcs_s, _mbstowcs_s_l podle jeho restartability.Stav převodu je uložen v mbstate pro následné volání stejné nebo jiné funkce s možností restartování.Výsledky nedefinované při použití s možností restartování a nonrestartable funkcí.Například by měla použít aplikace mbsrlen namísto mbslen, je-li následných volání mbsrtowcs_s se používá místombstowcs_s.

V jazyce C++ pomocí této funkce je zjednodušená šablony přetíženími; přetížení může automaticky odvodit velikost vyrovnávací paměti (odstranění požadavku k určení velikosti argument) a starší, nezabezpečené funkce můžou nahradit automaticky s použitím nástroji novější, zabezpečené.Další informace naleznete v tématu Přetížení zabezpečení šablony.

Výjimky

mbsrtowcs_s Je funkce s více vlákny bezpečnost, dokud není žádná funkce v aktuální vlákno volá setlocale , dokud tato funkce je prováděna a mbstate argument není ukazatel s hodnotou null.