Funkcja API WideCharToMultiByte (...)

Funkcja WideCharToMultiByte(...) konwertuje ciąg znaków z formatu Unicode na jednobajtowy ciąg znaków zgodny z określoną stroną kodową ASCII lub na ciąg znaków w formacie wielobajtowym np. UTF8. W typowych „Accessowych” operacjach konwersja zazwyczaj nie stwarza problemów. Należy się jednak liczyć z pewnym kłopotami przy konwersji bardziej złożonych tekstów. Ciąg znaków w formacie Unicode może zawierać kilkadziesiąt tysięcy znaków, a ciąg znaków ASCII tylko 256 znaków. Jak widzimy kłopoty mogą być, ale Windows tak już ma ☺.

Opis funkcji API WideCharToMultiByte (...)

Teoretycznie deklaracja funkcji WideCharToMultiByte(...) powinna mieć postać jak poniżej. Ale tylko „teoretycznie” gdyż nie za bardzo udało mi się zastosować funkcję WideCharToMultiByte(...) zadeklarowaną w poniższy sposób.

Private Declare Function WideCharToMultiByte Lib "kernel32" ( _
	ByVal CodePage As Long, _
	ByVal dwFlags As Long, _
	ByVal lpWideCharStr As String, _
	ByVal cchWideChar As Long, _
	ByVal lpMultiByteStr As String, _
	ByVal cchMultiByte As Long, _
	ByVal lpDefaultChar As String, _
	ByVal lpUsedDefaultChar As Long) As Long

argumenty:
- CodePage
- Określa stronę kodowa na którą ma być przekonwertowany tekst. Argument można ustawić na wartość dowolnej strony kodowej, dostępnej w systemie operacyjnym. Lista stron kodowych znajduje się na stronie: Strony kodowe Można również określić jedną z wartości predefiniowanych wartości: CP_ACP, CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP, CP_UTF7, CP_UTF8.
  To co nas najbardziej interesuje:
  Przy ustawionej wartości CP_UTF8, argumenty lpDefaultChar i lpUsedDefaultChar muszą mieć wartość 0 .
- dwFlags
- flagi wskazujące typ konwersji. Dla strony kodowej 65000 (UTF-7) i 65001 (UTF-8) oraz niektórych egzotycznych stron kodowych japońskich, chńskich, indyjskich (strony kodowe:50220, 50221, 50222, 50225, 50227, 50229, 54936, 57002 do 57011, 42-symbol argument dwFlags musi być ustawiony na 0, lub na wartość WC_ERR_INVALID_CHARS.
  W zastosowaniach „Accessowych” można ustawić argument dwFlags = 0.
- lpWideCharStr
- Wskaźnik (long pointer) do wejściowego ciągu w formacie Unicode.
- cchWideChar
- Rozmiar w znakach, ciągu wskazanego przez lpWideCharStr. Przypisanie do argumentu cchWideChar wartości 0 jest nieprawidłowe i funkcja nie będzie działała poprawnie. Jeśli argument ten równy jest -1, funkcja przetwarza cały łańcuch wejściowy, w tym znak końca ciągu vbNullChar. Wynikowy ciąg znaków zawiera znak końca ciągu vbNullChar, a tym samym zwracana przez funkcję długość ciągu uwzględnia ten znak. Jeśli argument ten jest ustawiony na dodatnią liczbę całkowitą cchWideChar > 0, funkcja przetwarza dokładnie określoną liczbę znaków. Jeśli w podanej ilości znaków nie zawiera się znak końca ciągu, wynikowy ciąg znaków nie jest zakończony znakiem końca ciągu vbNullChar. W zwracanej długość ciągu nie jest więc uwzględniony znak końca ciągu.
- lpMultiByteStr
- Wskaźnik (long pointer) do buforu, do którego zostanie przekazany przekonwertowany wejściowy ciąg znaków.
- cchMultiByte
- Rozmiar, w bajtach, bufora wskazanego przez lpMultiByteStr. Jeśli argument ten jest ustawiony na 0, funkcja zwraca wymagany rozmiar bufora dla lpMultiByteStr, ale nie zwraca przekonwertowanego ciągu w argumentcie lpMultiByteStr.
- lpDefaultChar
- Wskaźnik (long pointer) do znaku, który zostanie użyty, jeśli konwertowany znak nie może być reprezentowanay w określonej stronie kodowej. Dla domyślnej strony kodowej argument ten przyjmuje wartość 0 i wyświetlany jest standardowy znak systemowy używany w takim wypadku (zwykle jest to znak zapytania (?), kwadracik, kropka). Dla ustawień argumentu CodePage CP_UTF7 i CP_UTF8 dla, argument ten musi mieć wartość 0.
- lpUsedDefaultChar
- Wskaźnik (long pointer) do flagi wskazujący, czy funkcja użyła domyślnego znaku podczas konwersji. Flaga jest ustawiona na TRUE, jeśli jeden lub więcej znaków w ciągu wejściowym nie może być reprezentowany zestawie znaków podanej stronie kodowej. W przeciwnym razie flaga jest ustawiona na FALSE. Argument ten można ustawić na wartość 0. Dla ustawień argumentu CodePage CP_UTF7 i CP_UTF8, argument ten musi mieć wartość 0.
zwraca:
Przy powodzeniu zwraca liczbę bajtów zapisanych w buforze wskazanym przez lpMultiByteStr. Dla wartości argumentu cchMultiByte = 0 i przy powodzeniu zwraca wymagany rozmiar buforu wskazanego przez lpMultiByteStr, ale nie przekazuje przekonwertowanego ciągu do argumentu lpMultiByteStr. Przy niepowodzeniu funkcja zwraca 0. Aby uzyskać rozszerzoną informację o zaistniałym błędzie, można wywołać funkcję GetLastError.