ConvertINetString - 葉っぱ日記

Internet Explorer に付属する MLang.DLL には、ConvertINetString という、文字コード変換のための関数が含まれています。

この関数は、Windows 標準の文字コード(コードページ)変換のための関数である MultiByteToWideChar / WideCharToMultiByte に比べ、次のような特徴を持っています。

変換前と変換後の両方のコードページを指定できる
ストリームに対して逐次入力を変換させることができる

特に後者に関しては、ファイルやソケットなどを対象に変換を行う際など、変換前の文字列の長さが不明な場合やメモリ上で保持するには大きすぎる場合などに威力を発揮します。

関数のプロトタイプ宣言は、http://msdn.microsoft.com/workshop/misc/mlang/reference/functions/convertinetstring.asp によると

HRESULT ConvertINetString(
    LPDWORD lpdwMode,
    DWORD dwSrcEncoding,
    DWORD dwDstEncoding,
    LPCSTR lpSrcStr,
    LPINT lpnSrcSize,
    LPBYTE lpDstStr,
    LPINT lpnDstSize
);

と定義されています。引数を順に説明していきましょう。

lpdwMode: 変換のコンテキストを保持する DWORD 型の変数のポインタを指定します。最初の呼び出し前にこのポインタが指す内容(DWORD)を0にしておく必要があります。
dwSrcEncoding: 変換元の文字列のコードページを指定します。CP_OEMCP や CP_ACP は利用できません。あらかじめ GetOEMCP や GetACP を使って、これらのコードページの具体的な値を求めておく必要があります。
dwDstEncoding: 変換後の文字列のコードページを指定します。これも dwSrcEncoding と同じく CP_OEMCP や CP_ACP は利用できません。
lpSrcStr: 変換前の文字列を指定します。Unicodeにおいて、BOMは受け付けませんので注意が必要です。
lpnSrcSize: 変換前の文字列の長さをバイト単位で指す int 型の変数のポインタを指定します。NULLの場合または変数が-1の場合には、文字列はヌル文字で終端しているとみなされます。正常に文字列が変換できた場合、変換した文字がバイト単位で格納されます。変換結果を格納するバッファが不足している場合でも、この値には正常に変換できるであろうバイト数が格納されますので、注意が必要です。
lpDstStr: 変換された文字列を格納するバッファを指定します。変換結果を受け取るのにバッファサイズが不足している場合でも、どこまでが変換できたかを検出することは難しいため、充分に大きいバッファを指定してやる必要があります。
lpnDstSize: 変換結果を受け取るバッファのサイズを格納した int 型の変数のポインタを指定します。正常に文字列が変換できた場合、lpDstStr にコピーされた文字数をバイト単位で格納します。

戻り値は、HRESULT 型で、以下の3種類を返します。

S_OK: 変換が正常に終了した。変換結果を受け取るバッファのサイズが不足している場合でも、この値が返ります。
S_FALSE: 指定された方法での変換は、システムでサポートされていないことを示します。
E_FAIL: その他のエラー

S_FALSE または E_FAIL のエラーが返ってきた場合でも、GetLastError は有効なエラー番号を返しません。
関数の呼び出し前に、IsConvertINetStringAvailable を使って、それぞれのコードページ間で変換が有効かを調べることもできます。
この関数とWideCharToMultiByte / MultiByteToWideChar とでは、指定できるコードページが異なっていることが確認されています。