mbsrtowcs_s

Przekonwertuj ciąg znaków wielobajtowych w bieżących ustawieniach regionalnych na reprezentację szerokiego ciągu znaków. Wersja z ulepszeniami zabezpieczeń mbsrtowcs zgodnie z opisem w temacie Funkcje zabezpieczeń w narzędziu CRT.

Składnia

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

pReturnValue
Liczba przekonwertowanych znaków.

wcstr
Adres buforu do przechowywania wynikowego przekonwertowanego ciągu znaków szerokiego.

sizeInWords
Rozmiar wyrazów wcstr (znaki szerokie).

mbstr
Wskaźnik pośredni do lokalizacji ciągu znaków wielobajtowych do przekonwertowania.

count
Maksymalna liczba znaków szerokich do przechowywania w buforze wcstr , w tym wartości null zakończenia lub _TRUNCATE.

mbstate
Wskaźnik do mbstate_t obiektu stanu konwersji. Jeśli ta wartość jest wskaźnikiem o wartości null, używany jest statyczny obiekt stanu konwersji wewnętrznej. Ponieważ obiekt wewnętrzny mbstate_t nie jest bezpieczny wątkowo, zalecamy, aby zawsze przekazywać własny mbstate parametr.

Wartość zwracana

Zero, jeśli konwersja zakończyła się pomyślnie, lub kod błędu w przypadku błędu.

Błąd	Wartość zwracana i errno
wcstr jest wskaźnikiem o wartości null i sizeInWords> 0	EINVAL
mbstr jest wskaźnikiem o wartości null	EINVAL
Ciąg pośrednio wskazywany przez mbstr element zawiera sekwencję wielobajtową, która nie jest prawidłowa dla bieżących ustawień regionalnych.	EILSEQ
Bufor docelowy jest zbyt mały, aby zawierać przekonwertowany ciąg (chyba że count jest _TRUNCATEto ; aby uzyskać więcej informacji, zobacz Uwagi)	ERANGE

Jeśli wystąpi którykolwiek z tych warunków, jest wywoływany nieprawidłowy wyjątek parametru zgodnie z opisem w temacie Weryfikacja parametru . Jeśli wykonywanie jest dozwolone do kontynuowania, funkcja zwraca kod błędu i ustawia je errno zgodnie z opisem w tabeli.

Uwagi

Funkcja mbsrtowcs_s konwertuje ciąg znaków wielobajtowych pośrednio wskazywanych przez mbstr na znaki szerokie przechowywane w buforze wskazywanym przez wcstrmetodę przy użyciu stanu konwersji zawartego w mbstateobiekcie . Konwersja będzie kontynuowana dla każdego znaku do momentu spełnienia jednego z następujących warunków:

• Napotkano wielobajtowy znak o wartości null

• Napotkano nieprawidłowy znak wielobajtowy

• Liczba znaków szerokich przechowywanych w buforze wcstr jest countrówna .

Ciąg wcstr docelowy jest zawsze zakończony wartością null, nawet jeśli występuje błąd, chyba że wcstr jest to wskaźnik o wartości null.

Jeśli count jest to wartość _TRUNCATEspecjalna , mbsrtowcs_s konwertuje tyle ciągu, jak będzie mieścić się w buforze docelowym, a jednocześnie pozostawiając miejsce na terminator o wartości null.

Jeśli mbsrtowcs_s pomyślnie konwertuje ciąg źródłowy, umieszcza rozmiar w szerokich znakach przekonwertowanego ciągu, a terminator o wartości null na *pReturnValuewartość nie pReturnValue jest wskaźnikiem null. Rozmiar jest obliczany nawet wtedy, gdy wcstr argument jest wskaźnikiem o wartości null, co pozwala określić wymagany rozmiar buforu. Jeśli wcstr jest wskaźnikiem o wartości null, count jest ignorowany.

Jeśli wcstr nie jest wskaźnikiem o wartości null, obiekt wskaźnika wskazywany przez mbstr element ma przypisany wskaźnik o wartości null, jeśli konwersja została zatrzymana, ponieważ osiągnięto znak null zakończenia. W przeciwnym razie zostanie przypisany adres tuż obok ostatniego przekonwertowanego znaku wielobajtowego, jeśli istnieje. Umożliwia to kolejne wywołanie funkcji w celu ponownego uruchomienia konwersji, w której zatrzymano to wywołanie.

Jeśli mbstate jest wskaźnikiem o wartości null, używany jest wewnętrzny obiekt statyczny stanu konwersji biblioteki mbstate_t . Ponieważ ten wewnętrzny obiekt statyczny nie jest bezpieczny wątkowo, zalecamy przekazanie własnej mbstate wartości.

Jeśli mbsrtowcs_s napotka znak wielobajtowy, który nie jest prawidłowy w bieżących ustawieniach regionalnych, umieszcza wartość -1 w *pReturnValueelemencie , ustawia bufor wcstr docelowy na pusty ciąg, ustawia errno wartość EILSEQi zwraca wartość EILSEQ.

Jeśli sekwencje wskazywane przez mbstr i wcstr nakładają się na siebie, zachowanie mbsrtowcs_s jest niezdefiniowane. mbsrtowcs_s ma to wpływ na kategorię LC_TYPE bieżących ustawień regionalnych.

Ważne

Upewnij się, że wcstr i mbstr nie nakładają się, i że count poprawnie odzwierciedla liczbę znaków wielobajtowych do konwersji.

Funkcja mbsrtowcs_s różni się od mbstowcs_sfunkcji , _mbstowcs_s_l dzięki możliwości ponownego uruchamiania. Stan konwersji jest przechowywany dla mbstate kolejnych wywołań do tych samych lub innych funkcji możliwych do ponownego uruchomienia. Wyniki są niezdefiniowane podczas mieszania funkcji możliwych do ponownego uruchomienia i niezwiązanych z uruchamianiem. Na przykład aplikacja powinna używać mbsrlen zamiast mbslen, jeśli kolejne wywołanie mbsrtowcs_s metody jest używane zamiast mbstowcs_s.

W języku C++używanie tej funkcji jest uproszczone przez przeciążenia szablonu; przeciążenia mogą automatycznie wnioskować długość buforu (eliminując wymaganie określenia argumentu rozmiaru) i mogą automatycznie zastępować starsze, niezabezpieczone funkcje przy użyciu nowszych, bezpiecznych odpowiedników. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Wyjątki

mbsrtowcs_s Funkcja jest bezpieczna wielowątkowość, jeśli żadna funkcja w bieżącym wątku nie wywołuje setlocale tak długo, jak ta funkcja jest wykonywana, a mbstate argument nie jest wskaźnikiem o wartości null.

Wymagania

Procedura	Wymagany nagłówek
mbsrtowcs_s	<wchar.h>

Zobacz też

Konwersja danych
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych
mbrtowc
mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l
mbsinit