IdnToAscii 関数 (winnls.h)

  • [アーティクル]

国際化ドメイン名 (IDN) または別の国際化ラベルを、Punycode 転送エンコード構文の名前を表す ASCII 文字列の Unicode (ワイド文字) 表現に変換します。

注意 この関数は、IDN を Punycode に変換するための RFC 3490: Applications (IDNA) 標準アルゴリズムのドメイン名の国際化 を実装します。 この標準では、いくつかのセキュリティの問題が導入されています。 1 つの問題は、異なるスクリプトの特定の文字を表すグリフが似ているか、同じに見えることです。 たとえば、多くのフォントでは、キリル小文字 A ("а") はラテン小文字 A ("a") と区別できません。 "example.com" と "exа mple.com" は 2 つの異なるドメイン名であり、1 つはラテン小文字 A、もう 1 つはキリル小文字 A であることを視覚的に伝える方法はありません。IDN 関連のセキュリティ上の懸念事項の詳細については、「 国際化ドメイン名 (IDN) の処理」を参照してください。

 

構文

int IdnToAscii(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpUnicodeCharStr,
  [in]            int     cchUnicodeChar,
  [out, optional] LPWSTR  lpASCIICharStr,
  [in]            int     cchASCIIChar
);

パラメーター

[in] dwFlags

変換オプションを指定するフラグ。 次の表に、使用可能な値を示します。

値 意味
IDN_ALLOW_UNASSIGNED
メモ アプリケーションは、比較操作のように、通常の検索にクエリ文字列を使用しているだけの場合に、この値を設定できます。 ただし、アプリケーションでは、格納されている文字列 (ストレージ用に準備されている文字列) に対してこの値を設定しないでください。
 
割り当てられていないコード ポイントを入力文字列に含めることを許可します。 既定では、割り当てられていないコード ポイントを許可せず、ERROR_INVALID_NAMEの拡張エラー コードで失敗します。

このフラグを使用すると、この関数は IDN では現在有効ではないが、新しいバージョンの IDNA 標準では有効な可能性がある文字を処理できます。 アプリケーションで割り当てられていないコード ポイントが Punycode としてエンコードされている場合、結果のドメイン名は無効になります。 新しいバージョンの IDNA がこれらの名前を有効にした場合、またはアプリケーションが無効な文字を除外して法的ドメイン名を作成しようとすると、セキュリティが侵害される可能性があります。 詳細については、「 国際化ドメイン名 (IDN) の処理」を参照してください。
IDN_USE_STD3_ASCII_RULES
 STD3 名で使用できない ASCII 文字を除外します。 入力 Unicode 文字列で使用できる ASCII 文字は、文字、数字、ハイフンマイナスのみです。 文字列は、ハイフンマイナスで開始または終了できません。 入力 Unicode 文字列に、ドメイン名で使用できない ASCII 文字 ("["、"]"、"/" など) が含まれている場合、関数は失敗します。
メモ 一部のローカル ネットワークでは、コンピューター名にこれらの文字の一部を使用できます。
 

入力 Unicode 文字列に制御文字 (U+0001 から U+0020) または "delete" 文字 (U+007F) が含まれている場合、関数は失敗します。 どちらの場合も、このフラグは Unicode 文字列で許可されている ASCII 以外の文字には影響しません。
IDN_EMAIL_ADDRESS
 Windows 8以降: 電子メール アドレスのローカル部分 (local>@microsoft.com など<) に対して EAI アルゴリズム フォールバックを有効にします。 既定では、電子メール アドレスに無効なアドレスまたは構文がある場合、この関数は失敗します。

アプリケーションでは、このフラグを設定して、Email アドレス国際化 (EAI) を有効にして、可能な場合は検出可能なフォールバック アドレスを返すことができます。 詳細については、「IETF Email アドレス国際化 (eai) 憲章」を参照してください。
IDN_RAW_PUNYCODE
 Windows 8以降: Punycode の検証とマッピングを無効にします。

[in] lpUnicodeCharStr

IDN または他の国際化されたラベルを表す Unicode 文字列へのポインター。

[in] cchUnicodeChar

lpUnicodeCharStr で示される入力 Unicode 文字列内の文字数。

[out, optional] lpASCIICharStr

ASCII 文字セット内の文字のみで構成される Unicode 文字列を受け取るバッファーへのポインター。 この関数から返されたバッファーには、 lpUnicodeCharStr の Punycode で指定された文字列に相当する ASCII 文字列が含まれます。 または、cchASCIIChar が 0 に設定されている場合、このパラメーターの NULL を取得することもできます。 この場合、 関数は、このバッファーに必要なサイズを返します。

[in] cchASCIIChar

lpASCIICharStr で示されるバッファーのサイズ。 アプリケーションでは、 パラメーターを 0 に設定して、lpASCIICharStr で NULL を取得できます。

戻り値

成功した場合に lpASCIICharStr で取得された文字数を返します。 取得された文字列は、入力 Unicode 文字列が null で終わる場合にのみ null で終了します。

関数が成功し、 cchASCIIChar の値が 0 の場合、関数は必要なサイズ (入力バッファーの一部である場合は終端の null 文字を含む) を返します。

成功しなかった場合、関数は 0 を返します。 拡張エラー情報を取得するために、アプリケーションは GetLastError を呼び出すことができます。これにより、次のいずれかのエラー コードが返されます。

  • ERROR_INSUFFICIENT_BUFFER。 指定されたバッファー サイズが十分に大きくなかったか、 正しく NULL に設定されていませんでした。
  • ERROR_INVALID_FLAGS。 フラグに指定された値が無効でした。
  • ERROR_INVALID_NAME。 関数に無効な名前が指定されました。 このエラー コードは、すべての構文エラーをキャッチします。
  • ERROR_INVALID_PARAMETER。 パラメーター値のいずれかが無効です。
  • ERROR_NO_UNICODE_TRANSLATION。 文字列に無効な Unicode が見つかりました。

注釈

入力文字列の長さが終端の null 文字なしで明示的に指定されている場合、関数は出力文字列を null で終了しません。 この関数の出力文字列を null 終了するには、アプリケーションで cchUnicodeChar パラメーターに -1 を指定するか、入力文字列の終端の null 文字を明示的にカウントする必要があります。

入力文字列に制御文字 (U+0001 から U+0020) または "delete" 文字 (U+007F) が含まれている場合、関数は常に失敗します。 文字 U+0000 は終端の null 文字としてのみ表示できるため、U+0000 が入力文字列内の他の場所に表示される場合、関数は常に失敗します。

Windows XP、Windows Server 2003:

サポート対象から除外されました。

必要なヘッダー ファイルと DLL は、Microsoft 国際化ドメイン名 (IDN) 軽減 API の一部であり、ダウンロードできなくなります。

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー winnls.h (Windows.h を含む)
Library Normaliz.lib
[DLL] Normaliz.dll
再頒布可能パッケージ Microsoft Internationalized Domain Name (IDN) 軽減 API on Windows XP with SP2 以降、Windows Server 2003 SP1

こちらもご覧ください

国際化ドメイン名 (IDN) の処理

IdnToNameprepUnicode

IdnToUnicode

各国語サポート

各国語サポート関数