IdnToAscii 関数 (winnls.h)

[アーティクル]
03/13/2024

国際化ドメイン名 (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

こちらもご覧ください

次の方法で共有

IdnToAscii 関数 (winnls.h)

構文

パラメーター

戻り値

注釈

要件

こちらもご覧ください

フィードバック

その他のリソース