mbsrtowcs_s

Artykuł
02/27/2013

Konwertowanie ciągu szerokich znaków na jej reprezentację ciągu znaków wielobajtowych.Wersja z mbsrtowcs z rozszerzeń zabezpieczeń opisane w Funkcje zabezpieczeń w 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

[out]pReturnValue
Liczba znaków konwertowane.
[out]wcstr
Adres buforu dla wynikowy ciąg przekonwertowany szerokich znaków.
[out]sizeInWords
Rozmiar wcstr słowa (szerokości znaków).
[w]mbstr
Wskazuje lokalizację ciąg znaków wielobajtowych do konwersji.
[w]count
Maksymalna liczba znaków szerokości do przechowywania w wcstr buforu, nie włączając zakończeń null, lub _TRUNCATE.
[w]mbstate
Wskaźnik do mbstate_t obiekt stanu konwersji.

Wartość zwracana

Zero, jeśli kończy się pomyślnie, kod błędu w przypadku awarii.

Warunek błędu	Zwraca wartość ierrno
wcstris NULL and sizeInWords > 0	EINVAL
mbstrjestNULL	EINVAL
Bufor docelowy jest zbyt mały, aby pomieścił przekonwertowanym łańcuchem (chyba że count jest _TRUNCATE; Zobacz uwagi poniżej)	ERANGE

Jeśli występuje którykolwiek z tych warunków, wyjątek nieprawidłowy parametr jest wywoływany, jak opisano w Sprawdzanie poprawności parametru .Jeśli wykonanie może w dalszym ciągu, funkcja zwraca kod błędu i ustawia errno jak wskazano w tabeli.

Uwagi

mbsrtowcs_s Funkcja konwertuje ciąg znaków wielobajtowych wskazywanej przez mbstr do szerokości znaków przechowywanych w buforze wskazywanej przez wcstr, przy użyciu stan konwersji zawartych w mbstate.Konwersja będzie kontynuowane dla każdego znaku, dopóki jeden z tych warunków jest spełniony:

Po napotkaniu wielobajtowych znaków null
Nieprawidłowy znak wielobajtowych po napotkaniu
Liczba szerokości znaków przechowywanych w wcstr buforu równa się count.

Ciąg docelowego jest zawsze zakończony zerem (nawet w przypadku wystąpienia błędu).

Jeśli count jest specjalna wartość _TRUNCATE, następnie mbsrtowcs_s konwertuje tyle ciąg będą mieści się w bufor docelowy, pozostawiając nadal miejsca na null terminator.

Jeśli mbsrtowcs_s pomyślnie konwertuje ciąg źródłowy umieszcza rozmiar w szerokości znaków przekonwertowanym łańcuchem, łącznie z null terminator do *pReturnValue (pod warunkiem pReturnValue nie jest NULL).Dzieje się tak nawet wtedy, gdy wcstr argument jest NULL i daje możliwość określenia wymagany rozmiar buforu.Note that if wcstr is NULL, count is ignored.

Jeśli mbstate jest NULL, wewnętrznego mbstate_t stan konwersji jest używany.

Jeśli mbsrtowcs_s napotka nieprawidłowych znaków wielobajtowych umieszcza -1 w *pReturnValue, ustawia bufor docelowy ciąg pusty, ustawia errno do EILSEQi zwraca EILSEQ.

Jeśli sekwencji wskazywanej przez mbstr i wcstr nachodzą na siebie, zachowanie mbsrtowcs_s jest niezdefiniowane.mbsrtowcs_sdotyczy kategorii LC_TYPE bieżące ustawienia regionalne.

Uwaga dotycząca zabezpieczeń
Zapewnić, że wcstr i mbstr nie nakładają się i że count poprawnie odzwierciedla liczba znaków wielobajtowych do konwertowania.

mbsrtowcs_s Funkcja różni się od mbstowcs_s, _mbstowcs_s_l przez jego restartability.Stan konwersji jest przechowywany w mbstate dla kolejnych zaproszeń na to samo lub inne funkcje Przerywalne.Wyniki są niezdefiniowane, przy użyciu funkcji Przerywalne i nonrestartable.Na przykład, aplikacja będzie korzystać z mbsrlen zamiast mbslen, jeśli kolejne wywołania mbsrtowcs_s zostały użyte zamiastmbstowcs_s.

W języku C++ za pomocą tej funkcji jest uproszczona poprzez overloads szablonu; overloads można automatycznie rozpoznać długość buforu (eliminując konieczność należy określić argument rozmiar) i automatycznie można zastąpić starszych, które nie są bezpieczne funkcje z ich odpowiednikami nowsze, bezpieczne.Aby uzyskać więcej informacji, zobacz Secure, szablon Overloads.

Wyjątki

mbsrtowcs Funkcja jest wielowątkowym bezpieczne tak długo, jak długo wywoła żadnej funkcji w bieżącym wątku setlocale podczas wykonywania tej funkcji oraz mbstate ma wartość null.