wcsrtombs_s

Artykuł
02/27/2013

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

[out]pReturnValue
Liczba znaków konwertowane.
[out]mbstr
Adres buforu dla wynikowy ciąg znaków wielobajtowych przekonwertowane.
[out]sizeInBytes
Rozmiar w bajtach mbstr buforu.
[w]wcstr
Punkty do konwertowanego łańcucha szerokich znaków.
[w]count
Maksymalna liczba bajtów, które mają być przechowywane w mbstr buforu, 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
mbstris NULL and sizeInBytes > 0	EINVAL
wcstrjestNULL	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

wcsrtombs_s Funkcja konwertuje ciąg znaków szerokości wskazywanej przez wcstr do znaków wielobajtowych, przechowywane w buforze wskazywanej przez mbstr, 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 null szerokich znaków
Po napotkaniu szerokiego znaku, który nie może zostać przekonwertowany
Liczba bajtów, przechowywane w mbstr 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 wcsrtombs_s konwertuje tyle ciąg będą mieści się w bufor docelowy, pozostawiając nadal miejsca na null terminator.

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

Jeśli wcsrtombs_s napotka szerokiego znaku nie może przekonwertować znaków wielobajtowych, umieszcza -1 w *pReturnValue, ustawia bufor docelowy ciąg pusty, ustawia errno do EILSEQi zwraca EILSEQ.

Jeśli sekwencji wskazywanej przez wcstr i mbstr nachodzą na siebie, zachowanie wcsrtombs_s jest niezdefiniowane.wcsrtombs_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 numer szerokości znaków do konwertowania.

wcsrtombs_s Funkcja różni się od wcstombs_s, _wcstombs_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 wcsrlen zamiast wcslen, jeśli kolejne wywołania wcsrtombs_s zostały użyte zamiastwcstombs_s.

W języku C++ korzystając z tych 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

wcsrtombs_s 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.

Przykład

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