wcsrtombs_s

Článek
06/09/2015

Jeho znázornění řetězec vícebajtových znaků převeďte řetězec znaků.Verze wcsrtombs s vylepšení zabezpečení popsaným v Funkce zabezpečení v 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

Parametry

[výstup]pReturnValue
Počet znaků, které jsou převedeny.
[výstup]mbstr
Adresa vyrovnávací paměti pro výsledný řetězec převedený vícebajtových znaků.
[výstup]sizeInBytes
Velikost v bajtech mbstr vyrovnávací paměti.
[v]wcstr
Body převést řetězec znaků.
[v]count
Maximální počet bajtů, které mají být uložena v mbstr vyrovnávací paměti, nebo _TRUNCATE.
[v]mbstate
Ukazatel na mbstate_t převodu stavu objektu.

Vrácená hodnota

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

Chybový stav	Vrátí hodnotu aerrno
mbstris NULL and sizeInBytes > 0	EINVAL
wcstrjeNULL	EINVAL
Cílové vyrovnávací paměti je příliš malá, obsahovat řetězec převedený (Pokud count je _TRUNCATE; viz poznámky níže)	ERANGE

Pokud dojde k některé z těchto podmínek, je neplatný parametr výjimky vyvolat popsaným v Ověření parametru .Pokud je povoleno spuštění pokračovat, vrátí kód chyby a nastaví errno jak je uvedeno v tabulce.

Poznámky

wcsrtombs_s Funkce převede řetězec znaků široký, na kterou odkazuje wcstr do vícebajtových znaků uložených ve vyrovnávací paměti, na kterou odkazuje mbstr, pomocí převodu stavu obsažené v mbstate.Převod bude pro každý znak pokračovat, dokud není splněna jedna z těchto podmínek:

Je-li zjištěna širokým znakem null
Je-li zjištěna široký znak, který nelze převést
Počet bajtů, které jsou uloženy v mbstr vyrovnávací paměti se rovná count.

Cíl řetězec je vždy zakončený (i u chyba).

Pokud count je speciální hodnota _TRUNCATE, pak wcsrtombs_s převede část řetězce jako se vejdou do vyrovnávací paměti cíl, přitom stále ponechat prostor pro zakončení null.

Pokud wcsrtombs_s úspěšně převede řetězec zdroje systémem je velikost v bajtech převedeného řetězec, včetně ukončovací null do *pReturnValue (podle pReturnValue není NULL).Dochází i v případě mbstr argument je NULL a poskytuje způsob, jak určit velikost použité vyrovnávací paměti.Note that if mbstr is NULL, count is ignored.

Pokud wcsrtombs_s nalezne širokými znaky nelze převést na vícebajtové znakové odešle -1 do *pReturnValue, nastaví cílové vyrovnávací paměti na prázdný řetězec, nastaví errno na EILSEQa vrátí EILSEQ.

Pokud na sekvence odkazuje wcstr a mbstr překrývají, chování wcsrtombs_s nedefinovaná.wcsrtombs_svliv LC_TYPE kategorie aktuální národní prostředí.

Poznámka k zabezpečení
Zajistit, aby wcstr a mbstr nepřekrývají a že count správně odráží počet znaků široké převést.

wcsrtombs_s Funkce se liší od wcstombs_s, _wcstombs_s_l podle jeho restartability.Stav převodu je uložen v mbstate pro následné volání na stejné nebo jiné funkce s možností restartování.Výsledky nedefinované při použití funkce restartování a nonrestartable.Například použít aplikaci wcsrlen namísto wcslen, pokud následné volání wcsrtombs_s byly použity namístowcstombs_s.

V jazyce C++ použití těchto funkcí je zjednodušeno díky šablony přetížení; přetížení automaticky odvodit vyrovnávací paměti (není tak nutné zadat argument velikost) a jsou automaticky nahradit starší, -secure funkce s jejich protějšky novější, zabezpečené.Další informace naleznete v tématu Přetížení zabezpečení šablony.

Výjimky

wcsrtombs_s Multithread bezpečné je funkce jako žádná funkce v aktuální podproces volá setlocale při této funkce je provádění a mbstate má hodnotu null.

Příklad

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