メインコンテンツへジャンプする

JPNICはインターネットの円滑な運営を支えるための組織です

ロゴ:JPNIC

WHOIS 検索 サイト内検索 WHOISとは? JPNIC WHOIS Gateway
WHOIS検索 サイト内検索

idnkit ライブラリ の仕様書


機能概要

idnkit ライブラリ (libidnkit, libidnkitlite) は国際化ドメイン名の変換に関わる 各種の処理を実装するモジュールの集合です。 これらのライブラリは以下の機能を提供します。

  • エンコーディング変換
  • NAMEPREPに基づく文字列の正規化等の処理
  • 設定ファイルの読み込み

ただし、libidnkit はすべての機能を実装していますが、 libidnkitlite は「エンコーディング変換」の機能が一部省略されています。 省略されている機能について詳しくは、 エンコーディング変換 を参照して下さい。 省略されていない機能についての使用方法は、libidnkit とまったく変わりません。

特に断らない限り、本ドキュメントの記述は、libidnkit, libidnkitlite 双方に 共通のものとします。

エンコーディング変換

文字列のエンコーディングを変換し、その結果を返します。 idnkit ライブラリの内部では、文字列はすべて UCS4 エンコーディングであるとして 取り扱われます。そこで、このモジュールは以下の機能を提供します。

  • あるエンコーディングから UCS4 への変換
  • UCS4 からあるエンコーディングへの変換

エンコーディングは大きく分けて、次の2種類があります。

  • アプリケーションが使用するエンコーディング方式 (シフトJIS、EUC 等)
  • 国際化ドメイン名で使用するために設計された特別なエンコーディング方式 (Punycode等)

このうち、libidnkit は両方のエンコーディング方式に対応していますが、 libidnkitlite は後者のエンコーディング方式にだけ対応しています。

前者のエンコーディング変換のために、libidnkit では iconv() 関数を使用しています。 言い換えれば、前者のエンコーディング変換に対応していない libidnkitlite では、iconv() を使用しません。

後者のエンコーディング変換のために、libidnkit および libidnkitlite では 独自の変換関数を実装して使用しています。

NAMEPREP に基づく正規化等の処理

NAMEPREP の記述に従って、与えられたドメイン名文字列の正規化、文字の マッピング、禁止文字の検査、文字が割り当てられていないコードポイント を含んでいるかどうかの検査を行います。

ローカルルールによるドメイン名のマッピング

NAMEPREP とは別に、ローカルルールに基づいて文字のマッピングを行います。

ローカルエンコーディングの判別

アプリケーションプログラムが使用しているローカルエンコーディングを 自動判別します。判別は基本的にはアプリケーションのロケール情報を利用 しますが、環境変数で指定することも可能になっています。

設定ファイルの読み込み

idnkit ライブラリをリンクしたアプリケーションでエンコーディング 変換や NAMEPREP を行う場合、使用するエンコーディングや NAMEPREP は 設定ファイルに記述します。このファイルを読み込む機能を提供します。


モジュール一覧

idnkit ライブラリは以下のモジュールから構成されます。

aliaslistモジュール
ローカルエンコーディングのエイリアス情報を保持し、検索するための モジュール
apiモジュール
アプリケーション向けに、ドメイン名の エンコーディング変換や NAMEPREP を行うための高レベルのインタフェースを提供 するモジュール
checkerモジュール
ドメイン名に使用できない文字が含まれているかどうかを検査する モジュール
converterモジュール
文字列のエンコーディングの変換モジュール
debugモジュール
デバッグ用出力のためのユーティリティモジュール
delimitermapモジュール
ドメイン名の中の特定の文字をピリオド (`.') に マッピングするためのモジュール
filecheckerモジュール
ドメイン名に使用できない文字を定義したファイルを読み込んで、与えられた 文字列に使用できない文字が含まれているかどうかを調べるモジュール
filemapperモジュール
文字のマッピング規則を定義したファイルを読み込んで、ドメイン名文字列中 の文字のマッピングを行うモジュール
localencodingモジュール
アプリケーションの使用しているエンコーディングを推測するモジュール
logモジュール
idnkit ライブラリのログの出力処理を制御するモジュール
mapperモジュール
ドメイン名中の文字のマッピングを行うためのモジュールです。
mapselectorモジュール
与えられたドメイン名のトップレベルのドメインに応じて、異なるロー カルなマッピングを行うモジュール
nameprepモジュール
NAMEPREP に記述された、ドメインの正規化、マッピング、禁止文字の検査など を行うモジュール
normalizerモジュール
文字列の正規化を行うモジュール
punycodeモジュール
ドメイン名のエンコーディング方式の一つとして提案された Punycode エンコーディングの変換モジュール
raceモジュール
ドメイン名のエンコーディング方式の一つとして提案された RACE エンコーディングの変換モジュール
resモジュール
アプリケーションでドメイン名の エンコーディング変換や NAMEPREP を行うための低レベルのインタフェースを 提供するモジュール
resconfモジュール
アプリケーションでドメイン名の エンコーディング変換や NAMEPREP を行う際の設定ファイルを読み込むためのモジュール
resultモジュール
ライブラリの各関数が返すリザルトコードを扱うモジュール
strhashモジュール
文字列をキーとするハッシュ表を実現するモジュール
ucs4モジュール
UCS4 エンコーディング文字列の基本処理を行うモジュール
ucsmapモジュール
文字のマッピング規則の登録、およびマッピングを行うモジュール
ucssetモジュール
文字の登録を行うモジュール
unicodeモジュール
Unicode の各種文字属性を取得するモジュール
unormalizeモジュール
Unicode で定義されている標準の正規化を行うモジュール
utf8モジュール
UTF-8 エンコーディング文字列の基本処理を行うモジュール
utilモジュール
他のモジュールで使われる共用関数を提供するモジュール
versionモジュール
ライブラリのバージョン情報を取得するためのモジュール

以下にモジュールの呼び出し関係図を示します。ただしほとんどすべての モジュールから呼び出されている debugモジュールと logモジュール、また共用関数を納めた utilモジュールは割愛してあります。

libidnkit module graph


モジュール詳細

idnkit ライブラリに含まれるすべてのモジュールについて、その仕様を記述 します。 まず各モジュールで共通に使用される、関数の戻り値について説明したあと、 モジュール毎に詳細を解説します。


API関数の戻り値

IDNライブラリのほとんど全てのAPI関数は、戻り値として列挙型である idn_result_t 型の値を返します。値の一覧とその意味を示します。

idn_success
処理が成功したことを示します。
idn_notfound
検索処理などにおいて、見つからなかったことを示します。
idn_invalid_encoding
エンコーディング変換において、入力された文字列のエンコーディングが 間違っていることを示します。
idn_invalid_syntax
ファイルなどの書式に間違いがあることを示します。
idn_invalid_name
指定された名前が間違っていることを示します。
idn_invalid_message
入力されたDNSメッセージが正しくないことを示します。
idn_invalid_action
文字列の変換方法の指定に誤りがあることを示します。
idn_invalid_codepoint
入力された文字のコードポイントが、規定範囲外の値であることを示します。
idn_invalid_length
ドメイン名を変換した結果、いずれかのラベルの長さが範囲外になったこと を示します。
idn_buffer_overflow
結果を格納するバッファの大きさが足りないことを示します。
idn_noentry
指定された項目が存在しないことを示します。
idn_nomemory
メモリのアロケーションに失敗したことを示します。
idn_nofile
指定されたファイルの読み込みに失敗したことを示します。
idn_nomapping
文字列のエンコーディングを変換する際、 変換ターゲットの文字集合に含まれない文字があった (つまり 正しく変換できなかった) ことを示します。
idn_context_required
文字の大文字小文字変換の際に、正しい変換を行うには文脈情報が 必要であることを示します。
idn_prohibited
入力された文字列が、使用を禁止する文字を含んでいたことを示します。
idn_failure
上記のいずれにも当てはまらないエラーが発生したことを示します。

aliaslistモジュール

aliaslistモジュールはローカルエンコーディングの エイリアス情報を扱うためのモジュールです。

エイリアス情報は次に示す idn_aliaslist_t 型の opaque データとして 表されます。

typedef struct idn__aliaslist *idn__aliaslist_t;

このモジュールは converter モジュールの下位モジュールとして 実装されており、アプリケーションがこのモジュールを直接呼び出すことは ありません。 converter モジュールを使用する際に、エンコーディング名のエイリアスの登録や 削除、正式名の取得を行うためにこのモジュールが利用されます。

以下にモジュールの提供するAPI関数を示します。

idn__aliaslist_create

idn_result_t
idn__aliaslist_create(idn__aliaslist_t *listp)

リストを作成し、それを listp の指す領域に格納します。

返される値は idn_successidn_nomemory のいずれかです。

idn__aliaslist_destroy

void
idn__aliaslist_destroy(idn__aliaslist_t list)

idn__aliaslist_create で作成したリストを削除し、確保したメモリを解放します。

idn__aliaslist_aliasfile

idn_result_t
idn__aliaslist_aliasfile(idn__aliaslist_t list, const char *path)

ファイル path で指定されるファイルを読み込み、その内容に 従ってエイリアスを登録します。ファイルの記述方法については、 エイリアスファイルについて の項を参照してください。

idn__aliaslist_additem

idn_result_t
idn__aliaslist_additem(idn__aliaslist_t list,
        const char *alias_name, const char *real_name,
        int first_item)

エンコーディング名 real_name に対して、alias_name というエイリアスを登録します。登録したエイリアスは idn_converter_createname 引数に指定することができます。

first_item が 0 であればエイリアスリストの最後に登録されます。 それ以外の場合は、リストの最初に登録されます。 エイリアスからエンコーディング名への解決はリストの最初から行われ、 該当するものがあればその時点で解決動作は終了します。

返される値は idn_successidn_nomemory のいずれかです。

idn__aliaslist_find

idn_result_t
idn__aliaslist_find(idn__aliaslist_t list,
        const char *pattern, char **encodingp)

文字列 pattern に対応するエンコーディング名を list から検索し、見つかった場合は encodingp が指す領域にそのエンコーディング名文字列へのポインタをセットします。

検索時、リスト内のエイリアスパターンの "*" は pattern の 任意の文字列にマッチします。

返される値は idn_successidn_noentry のいずれかです。 idn_success であればマッチするパターンが発見されたことを 示します。


apiモジュール

apiモジュールは、アプリケーション向けに、 ドメイン名のエンコーディング変換や NAMEPREP を行うための高レベルの インタフェースを提供するモジュールです。

一般のアプリケーションはこのモジュールを使用することで、国際化ドメインに 関する一連の処理を容易に行うことができるように設計されています。 このモジュールでは対応できない特殊な処理を行いたいときは、 より低レベルなインターフェースを提供する resモジュールを使用します。

なお、 環境変数 IDN_DISABLE が設定されている場合は、以下に挙げられた文字列変換用の関数を使用しても 文字列の変換は行われず、元の文字列のままの結果が返されます。 IDN_DISABLE が設定されている環境で文字列の変換を強制的に行う場合や、 アプリケーションでこれらの API 関数を使用するうえで IDN_DISABLE の設定に関係なく一定の動作を保証したい場合は、 idn_enable を事前に使用しておかなければなりません。

以下にモジュールの提供するAPI関数を示します。

idn_enable

void
idn_enable(int on_off);

通常、 環境変数 IDN_DISABLE が宣言されている場合、ドメイン名変換処理は 行なわれず、元の文字列のままの結果が返されますが、 この関数はその設定をオーバーライドすることができます。

IDN_DISABLE が設定されているかどうかにかかわらず、 on_off に 0 以外の値を指定してこの関数を使用すると、 それ以降はドメイン名の変換を行うようになります。 0 を指定すると、それとは逆にドメイン名の変換を行わず、 元の文字列のままの結果を返すようになります。

idn_nameinit

idn_result_t
idn_nameinit(int load_file);

api モジュールの初期化を行います。

load_file に 0 以外の値を指定すると、設定ファイルを読み込みます。 読み込むファイルについては、 idn_resconf_loadfile を御覧ください。

load_file に 0 を指定すると、設定ファイルを全く参照せず、 標準の設定を使ってライブラリの初期化が行われます。 標準の設定内容については、 idn_resconf_setdefaults を御覧ください。

二度以上この関数を呼んでも、初期化が行わ れるのは最初の呼び出し時だけです。 この関数を呼び出す前に、後述する idn_encodenameidn_decodename もしくは idn_decodename2 が 呼び出されたときは、エンコード、デコードの処理に先だって自動的に idn_nameinit(0) による初期化が行われます。

返される値は idn_successidn_nofileidn_invalid_syntaxidn_invalid_nameidn_nomemory のいずれかです。

idn_encodename

idn_result_t
idn_encodename(idn_action_t actions, const char *from, char *to, size_t tolen);

ドメイン名のエンコードを行います。 入力文字列 from を変換し、結果を totolen で指定される領域に書き込みます。

actions には、idn_encodenameに行わせたいエンコード 動作を指定します。次に挙げるフラグの論理和の値 (例: IDN_NAMEPREP | IDN_IDNCONV) を指定するようにします。 指定された動作は、ここに挙げた順序でそれぞれ行われます。

IDN_LOCALCONV
ローカルエンコーディング (shift_JIS や Big5 など) の文字列を UTF-8 に変換する。(libidnkit でだけ使用できます。libidnkitlite では使用 できません。)
IDN_DELIMMAP
特定の文字をピリオド (U+002E FULL STOP) に変換する。
IDN_LOCALMAP
ドメイン名のトップレベルドメインに応じて、異なるローカルな マッピングを行う。
IDN_MAP
ドメイン名のマッピングを行う。
IDN_NORMALIZE
ドメイン名の正規化を行う。
IDN_PROHCHECK
ドメイン名の禁止文字チェックを行う。
IDN_UNASCHECK
未割り当てコードポイントのチェックを行う。 また、ラウンドトリップチェック時に、未割り当てコードポイントの チェックを行う。
IDN_BIDICHECK
双方向文字列のチェックを行う。
IDN_ASCCHECK
ASCII 文字に関するチェック (英数字やハイフン以外の文字の有無など) を行う。
IDN_IDNCONV
UTF-8 の文字列を国際化ドメイン用のエンコーディング (Punycode など) に変換する。
IDN_LENCHECK
ドメイン名の各ラベルの長さをチェックする。
IDN_UNDOIFERRK
処理途中に何らかの失敗があれば、from をそのまま返す。

これらに加えて、利便性を配慮して IDN_NAMEPREPIDN_ENCODE_APPIDN_ENCODE_QUERYIDN_ENCODE_STORED というフラグも用意されています。

IDN_NAMEPREP は、文字列の NAMEPREP に関連する処理を まとめて行う場合に使用します。このフラグは次の指定と等価です。

IDN_MAP | IDN_NORMALIZE | IDN_PROHCHECK | IDN_BIDICHECK

なお、ここに IDN_UNASCHECK が含まれていないのは、 未割り当てコードポイントのチェックが必要でないケースが存在するためです。 詳しくは国際化ドメイン処理のアーキテクチャである IDNA のドキュメントをごらんください。

通常、アプリケーションは actionsIDN_ENCODE_APP を指定することになります。 ライブラリとして libidnkit を使用している場合、このフラグを指定すると IDN_UNASCHECK を除いたすべてのフラグの処理を行います。 libidnkitlite を使用している場合は、IDN_LOCALCONVIDN_UNASCHECK を除いたすべてのフラグの処理を行います。

IDN_ENCODE_QUERYIDN_ENCODE_STORED は、 IDNA で明記されている、query string と stored string の使い分けのために 名称を明確化したマクロです。

IDN_ENCODE_QUERY は、IDN_ASCIIHECK を 行わないという点を除いて IDN_ENCODE_APP と同じです。 また、IDN_ENCODE_STORED は、IDN_UNASCHECK も行うという点を除いて IDN_ENCODE_APP と同じです。 (いずれも、libidnkitlite 使用時は、IDN_LOCALCONV を 行いません。)

actionsに何も指定しなければ (つまり 0 を指定した場合は)、 文字列は単にコピーされます。

この関数から返される値は idn_successidn_invalid_encodingidn_invalid_lengthidn_invalid_syntaxidn_invalid_nameidn_invalid_actionidn_buffer_overflowidn_nomemoryidn_nofileidn_prohibited のいずれかです。

libidnkitlite 使用時に IDN_LOCALCONV を指定すると、 idn_invalid_action が返ります。

idn_decodename

idn_result_t
idn_decodename(idn_action_t actions, const char *from, char *to, size_t tolen);

ドメイン名のデコードを行います。 入力文字列 from を変換し、結果を totolen で指定される領域に書き込みます。

actions には、デコードにおいて、idn_decodename に行わせたい変換動作を指定します。次に挙げるフラグの論理和の値を指定する ようにします。 指定された動作は、ここに挙げたのと同じ順序でそれぞれ行われます。

IDN_DELIMMAP
特定の文字をピリオド (U+002E FULL STOP) に変換する。
IDN_MAP
ドメイン名のマッピングを行う。
IDN_NORMALIZE
ドメイン名の正規化を行う。
IDN_PROHCHECK
ドメイン名の禁止文字チェックを行う。
IDN_UNASCHECK
未割り当てコードポイントのチェックを行う。 また、ラウンドトリップチェック時に、未割り当てコードポイントの チェックを行う。
IDN_BIDICHECK
双方向文字列のチェックを行う。
IDN_IDNCONV
国際化ドメイン用のエンコーディング (Punycode など) の文字列 を UTF-8 に変換する。
IDN_RTCHECK
ラウンドトリップチェックを行う。
IDN_ASCCHECK
ラウンドトリップチェック時に、ASCII 文字に関するチェック (英数字やハイフン以外の文字の有無など) を行う。
IDN_LOCALCONV
UTF-8 の文字列をローカルエンコーディング (shift_JIS や Big5 など) に変換する。(libidnkit でだけ使用できます。libidnkitlite では使用 できません。)

これらに加えて、利便性を配慮して IDN_NAMEPREPIDN_ENCODE_APPIDN_ENCODE_QUERYIDN_ENCODE_STORED というフラグも用意されています。

IDN_NAMEPREP は、文字列の NAMEPREP に関連する処理を まとめて行う場合に使用します。このフラグは次の指定と等価です。

IDN_MAP | IDN_NORMALIZE | IDN_PROHCHECK | IDN_BIDICHECK

なお、ここに IDN_UNASCHECK が含まれていないのは、 未割り当てコードポイントのチェックが必要でないケースが存在するためです。 詳しくは国際化ドメイン処理のアーキテクチャである IDNA のドキュメントをごらんください。

通常、アプリケーションは actionsIDN_ENCODE_APP を指定することになります。 ライブラリとして libidnkit を使用している場合、このフラグを指定すると IDN_UNASCHECK を除いたすべてのフラグの処理を行います。 libidnkitlite を使用している場合は、IDN_LOCALCONVIDN_UNASCHECK を除いたすべてのフラグの処理を行います。

IDN_ENCODE_QUERYIDN_ENCODE_STORED は、 IDNA で明記されている、query string と stored string の使い分けのために 名称を明確化したマクロです。

IDN_ENCODE_QUERY は、IDN_ASCIIHECK を 行わないという点を除いて IDN_ENCODE_APP と同じです。 また、IDN_ENCODE_STORED は、IDN_UNASCHECK も行うという点を除いて IDN_ENCODE_APP と同じです。 (いずれも、libidnkitlite 使用時は、IDN_LOCALCONV を 行いません。)

actionsに何も指定しなければ (つまり 0 を指定した場合は)、 文字列は単にコピーされます。

この関数から返される値は idn_successidn_invalid_encodingidn_invalid_lengthidn_invalid_syntaxidn_invalid_nameidn_invalid_actionidn_buffer_overflowidn_nomemoryidn_nofileidn_prohibited のいずれかです。

libidnkitlite 使用時に IDN_LOCALCONV を指定すると、 idn_invalid_action が返ります。

idn_decodename2

idn_result_t
idn_decodename2(idn_action_t actions, const char *from, char *to, size_t tolen,
                const char *auxencoding);

この関数は idn_decodename() の拡張版です。

idn_decodename() では、入力文字列 (from) が 常に UTF-8 であるものとみなされます。 idn_decodename() の入力文字列は IDN エンコーディング ですが、IDN エンコーディング が ACE であった場合、入力された ACE 文字列 そのものは UTF-8 で書かれているものとして扱われます。

これに対して、idn_decodename2() では auxencoding という引数が追加されており、入力された文字列のエンコーディングを指定する ことができます。 idn_decodename2() は、入力文字列 from をまず auxencoding で指定されたエンコーディングから UTF-8 に変換 します。 そして、その後は idn_decodename() と同じ処理を行います。

auxencodingNULL を指定した場合、 入力文字列は UTF-8 であるとみなされます。 つまり、この場合は idn_res_decodename() とまったく同じ 処理を行います。

なお libidnkitlite では、この関数を使うことはできません。 呼び出すと、エラーコード idn_failure が返ります。 これは、auxencodingNULL を指定した場合 も、例外ではありません。


checkerモジュール

checkerモジュールは、ドメイン名に使用できない文字が 含まれているかどうかを検査するためのモジュールです。

現在サポートされている検査方式は次の通りです。

  • NAMEPREPの禁止文字の検査
  • NAMEPREPの未割り当てコードポイントの検査
  • 禁止文字、未割り当てコードポイントを定義したファイルを読み込み、 その記述にしたがった検査

また別の新たな検査方式を追加登録するためのAPIも用意されています。

checkerモジュールは「検査コンテキスト」という概念を用います。 検査に先立ってまず検査コンテキストを作成し、使用する検査方式をコンテキスト に登録しておきます。 実際の検査処理の際には検査方式ではなく、 この検査コンテキストを指定します。 検査コンテキストの型は idn_checker_t 型であり、 次のような opaque 型として定義されています。

typedef struct idn_checker *idn_checker_t;

以下にモジュールの提供するAPI関数を示します。

idn_checker_initialize

idn_result_t
idn_checker_initialize(void)

モジュールの初期化処理を行います。本モジュールの他のAPI関数を呼ぶ前に 必ず呼び出してください。

返される値は idn_successidn_nomemory のいずれかです。

idn_checker_create

idn_result_t
idn_checker_create(idn_checker_t *ctxp)

検査用の空のコンテキストを作成し、ctxp の指す領域に格納します。 返されるコンテキストは空で、検査方式は一つも含まれていません。 検査方式を追加するには idn_checker_addidn_checker_addallを用います。 コンテキストで作成された時点では、コンテキストの参照カウントは 1 になって います。

返される値は idn_successidn_nomemory のいずれかです。

idn_checker_destroy

void
idn_checker_destroy(idn_checker_t ctx)

idn_checker_create で 作成した検査コンテキストの参照カウントを一つ減らします。 その結果、カウントが 0 になれば、コンテキストを削除し、アロケートされた メモリを解放します。

idn_checker_incrref

void
idn_checker_incrref(idn_checker_t ctx)

idn_checker_create で 作成した検査コンテキストの参照カウントを一つ増やします。

idn_checker_add

extern idn_result_t
idn_checker_add(idn_checker_t ctx, const char *name)

idn_checker_create で 作成した検査コンテキストに、name で指定される 検査方式を追加します。一つのコンテキストに複数の検査方式を 追加することができます。

検査方式nameの書式は次のようになります。

IDN_CHECKER_PROHIBIT_PREFIX<nameprep-version>
NAMEPREP バージョン <nameprep-version> の禁止文字検査 を行います。
IDN_CHECKER_UNASSIGNED_PREFIX<nameprep-version>
NAMEPREP バージョン <nameprep-version> の未割り当て コードポイントの検査を行います。
IDN_CHECKER_BIDI_PREFIX<nameprep-version>
NAMEPREP バージョン <nameprep-version> の双方向 文字列の検査を行います。
IDN_CHECKER_PROHIBIT_PREFIX fileset:<path>
<path>で指定されたファイルから禁止文字の定義を 読み込み、その内容に従って検査を行います。 ファイルの記述方法については、 セットファイルの形式 の項を参照してください。
IDN_CHECKER_UNASSIGNED_PREFIX fileset:<path>
ファイルから未割り当てコードポイントの定義を読み込み、その内容に 従って検査を行います。 ファイルの記述方法については、 セットファイルの形式 の項を参照してください。
<prefix>:<parameter>
idn_checker_register で登録した検査方式 <prefix> による検査を行います。 <parameter> は、登録した関数 createに対して 引数<parameter>として渡されます。

IDN_CHECKER_PROHIBIT_PREFIX および IDN_CHECKER_UNASSIGNED_PREFIX は cpp マクロで、実際 にはそのマクロの値を用います。また、その後ろの fileset<nameprep-version> との間に空白を開けてはいけません。 したがって、文字列nameは、実際には次のような方法で生成する ことになります。

sprintf(name, "%s%s", IDN_CHECKER_PROHIBIT_PREFIX, nameprep_version);
sprintf(name, "%sfileset:%s", IDN_CHECKER_UNASSIGNED_PREFIX, file_path);

返される値は idn_successidn_invalid_nameidn_nomemory のいずれかです。

idn_checker_addall

idn_result_t
idn_checker_addall(idn_checker_t ctx, const char **names, int nnames)

idn_checker_addallは一度に複数の検査方式を追加する ことを除いて、 idn_checker_addと 同じです。 長さnnamesからなる配列namesの各要素を 検査方式として登録します。 すべての方式の追加に成功するとidn_successを返します。 登録に失敗した場合、失敗した方式より先に記述されていた方式だけが コンテキスト ctx に登録された状態になります。

idn_checker_lookup

idn_result_t
idn__checker_lookup(idn__checker_t ctx, const unsigned long *ucs4,
        const unsigned long **found);

UCS4 でエンコードされたラベル ucs4ctx に 指定された検査方式で検査します。 ラベルが禁止文字、未割り当てコードポイントを含んでいた場合、 foundにその先頭位置を格納します。 含まれていない場合は、NULLを返します。

返される値は idn_successidn_nomemoryidn_buffer_overflowidn_invalid_encoding のいずれかです。

idn_checker_register

idn_result_t
idn_checker_register(const char *prefix,
        idn_checker_createproc_t create,
        idn_checker_destroyproc_t destroy,
        idn_checker_lookupproc_t lookup)

新しい検査方式を登録します。 prefixには、検査方法の名称を指定します。 idn_checker_addidn_checker_addall でコンテキストに検査方式を追加する際には、この名称で検査方法を指定 します。

createdestroylookupには、それぞれ idn_checker_createidn_checker_destroyidn_checker_lookup の処理が行われる際に、呼び出してほしい関数を指定します。 それぞれの関数は、次のような引数、戻り値でなくてはなりません。

typedef idn_result_t (*idn_checker_createproc_t)
        (const char *parameter, void **ctxp);

typedef void (*idn_checker_destroyproc_t)
        (void *ctx);

typedef idn_result_t (*idn_checker_lookupproc_t)
        (void *ctx, const char *utf8, const char **found);

返される値は idn_successidn_nomemory のいずれかです。


converterモジュール

converterモジュールは、文字列のエンコーディングを変換します。 idnkit ライブラリは内部処理に UCS4 エンコーディングの文字列を使用するため、 このモジュールはあるエンコーディングと UCS4 との間の相互変換を行います。

現在サポートされているエンコーディングは次の通りです。

  • iconv() がサポートしているエンコーディング方式
    iconv() とは汎用的なエンコーディング変換機能を提供する関数で、 この関数がサポートするエンコーディングをサポートします。

    iconv() がサポートするエンコーディングは実装依存なので、 具体的にどのエンコーディングが使用可能なのかは iconv() の ドキュメントをご覧ください。 また、このエンコーディング方式は libidnkit でだけ使用できます。 libidnkitlite では使用できません。

  • 各種の国際化ドメイン名のエンコーディング方式
    "Punycode" のみサポートしています。

また、converterモジュールはドメイン名のエンコーディング 変換のために特別に設計されたもので、一般的なエンコーディング変換には 必ずしも適しません。 例えば Punycode では、ドメイン名の区切り文字である ピリオドを特別に扱います。

converterモジュールは「コード変換コンテキスト」という概念を 用います。 あるエンコーディングと UCS4 との相互変換を行うには、まず そのエンコーディングのコード変換コンテキストを作成します。実際の コード変換にはエンコーディングを直接指定するのではなく、この コード変換コンテキストを指定します。コード変換コンテキストの型は idn_converter_t 型であり、次のような opaque 型として 定義されています。

typedef struct idn_converter *idn_converter_t;

以下にモジュールの提供するAPI関数を示します。

idn_converter_initialize

idn_result_t
idn_converter_initialize(void)

モジュールの初期化処理を行います。本モジュールの他のAPI関数を呼ぶ前に 必ず呼び出してください。

返される値は idn_successidn_nomemory のいずれかです。

idn_converter_create

idn_result_t
idn_converter_create(const char *name, idn_converter_t *ctxp,
        int flags)

name で指定されたエンコーディングと UCS4 との間の コード変換コンテキストを作成、初期化し、ctxp の指す領域に 格納します。 コンテキストで作成された時点では、コンテキストの参照カウンタは 1 になって います。

ライブラリには Punycode の変換機能が用意されています。 これ以外のエンコーディングが指定された場合には、システムの提供する iconv() ユーティリティを用いて変換が行われます。 この場合、この関数の呼び出し時にiconv_open() の 呼び出しが行われますが、 flags が真ならば実際に文字列の変換が行われるまで iconv_open() の呼び出しが遅延されます。

またidn_converter_register を用いて新たなローカルエンコーディングを追加することも可能です。

返される値は idn_successidn_invalid_nameidn_nomemoryidn_failure のいずれかです。

idn_converter_destroy

void
idn_converter_destroy(idn_converter_t ctx)

idn_converter_create で 作成したコード変換コンテキストの参照カウントを一つ減らします。 その結果、カウントが 0 になれば、コンテキストを削除し、アロケートされた メモリを解放します。

idn_converter_incrref

void
idn_converter_incrref(idn_converter_t ctx)

idn_converter_create で 作成したコード変換コンテキストの参照カウントを一つ増やします。

idn_converter_convfromucs4

idn_result_t
idn_converter_convfromucs4(idn_converter_t ctx, 
        const unsigned long *from, char *to, size_t tolen);

UCS4 の文字列 fromidn_converter_create で 指定したエンコーディングにコード変換し、結果を to に格納します。 tolento の長さです。 また、変換は毎回初期状態から始まります。

返される値は idn_successidn_buffer_overflowidn_invalid_encodingidn_invalid_nameidn_nomemoryidn_failure のいずれかです。

idn_converter_convtoucs4

idn_result_t
idn_converter_convtoucs4(idn_converter_t ctx, 
        const char *from, unsigned long *to, size_t tolen);

idn_converter_create で 指定したエンコーディングの文字列 from を UCS4 にコード変換し、結果を to に格納します。 tolento の長さです。 また、変換は毎回初期状態から始まります。

返される値は idn_successidn_buffer_overflowidn_invalid_encodingidn_invalid_nameidn_nomemoryidn_failure のいずれかです。

idn_converter_localencoding

char *
idn_converter_localencoding(idn_converter_t ctx)

コード変換コンテキスト ctx に設定さたエンコーディング名 を返します。

idn_converter_encodingtype

int
idn_converter_encodingtype(idn_converter_t ctx);

コード変換コンテキスト ctx に設定さたエンコーディング名 の種類を返します。

返される値は

  • IDN_NOACE -- ACE ではないエンコーディング
  • IDN_ACE_STRICTCASE -- エンコーディングは ACE であり、 ASCII 英字 (A-Z, a-z) の大文字/小文字の違いがエンコード後も識別できる。
  • IDN_ACE_LOOSECASE -- エンコーディングは ACE であり、 ASCII 英字 (A-Z, a-z) の大文字/小文字の違いがエンコード後は識別できない。

のいずれかです。

idn_converter_isasciicompatible

int
idn_converter_isasciicompatible(idn_converter_t ctx)

コード変換コンテキスト ctx のローカルエンコーディングが ASCII互換エンコーディングかどうかを返します。ASCII互換エンコーディングなら 1が、そうでないなら0が返ります。

ASCII互換エンコーディング(ASCII-compatible Encoding) とは、 そのエンコーディングでエンコードされたドメイン名が 通常のASCIIのドメイン名と区別できない、つまり英数字および ハイフンのみで構成されるようなエンコーディングのことで、 具体的には Punycode が相当します。

idn_converter_addalias

idn_result_t
idn_converter_addalias(const char *alias_name, const char *real_name,
                       int first_item)

エンコーディング名 real_name に対して、alias_name というエイリアスを登録します。登録したエイリアスは idn_converter_createname 引数に指定することができます。

first_item が 0 であればエイリアスリストの最後に登録されます。 それ以外の場合は、リストの最初に登録されます。 エイリアスからエンコーディング名への解決はリストの最初から行われ、 該当するものがあればその時点で解決動作は終了します。

返される値は idn_failureidn_successidn_nomemory のいずれかです。

idn_converter_aliasfile

idn_result_t
idn_converter_aliasfile(const char *path)

ファイル path で指定されるファイルを読み込み、その内容に 従ってエイリアスを登録します。ファイルの記述方法については、 エイリアスファイルの形式 の項を参照してください。

返される値は idn_successidn_nofileidn_invalid_syntaxidn_nomemory のいずれかです。

idn_converter_resetalias

idn_result_t
idn_converter_resetalias(void)

idn_converter_addaliasidn_converter_aliasfile で登録したエイリアスをリセットし、エイリアスが全く登録されていない初期状態に 戻します。

返される値は idn_successidn_nomemory のいずれかです。

idn_converter_getrealname

const char *
idn_converter_getrealname(const char *name)

name という文字列にもとづき、エイリアス情報を検索し、 マッチするものがあればその正式名の文字列を返します。 マッチしなければ、元の文字列がそのまま返されます。

idn_converter_register

idn_result_t
idn_converter_register(const char *name,
           idn_converter_openproc_t openfromucs4,
           idn_converter_openproc_t opentoucs4,
           idn_converter_convfromucs4proc_t convfromucs4,
           idn_converter_convtoucs4proc_t convtoucs4,
           idn_converter_closeproc_t close,
           int encoding_type)

name という名前のローカルエンコーディングと UCS4との 間のエンコーディング変換機能を追加します。openfromucs4opentoucs4convfromucs4convtoucs4close は変換等の処理関数へのポインタです。 encoding_type にはこのローカルエンコーディングのタイプを 指定します。エンコーディングタイプについては、 idn_converter_encodingtype を御覧ください。

返される値は idn_successidn_nomemory のいずれかです。


debugモジュール

debugモジュールはデバッグ用出力のためのユーティリティ モジュールです。以下にモジュールの提供するAPI関数を示します。

idn__debug_hexstring

char *
idn_debug_hexstring(const char *s, int maxbytes)

文字列 s を16進数表示した文字列を返します。 maxbytes は表示する最大の長さで、sが これを超えた場合には最後に「...」という文字列が付加 されます。

返される文字列のメモリ領域は本関数の保持するスタティック変数の もので、その内容は本関数の次の呼び出し時まで有効です。

idn__debug_xstring

char *
idn_debug_xstring(const char *s, int maxbytes)

文字列 s の中で、コードが128以上のものを\x{HH}形式で 表示した文字列を返します。 maxbytes は表示する最大の長さで、s が これを超えた場合には最後に ...が追加されます。

返される文字列のメモリ領域は本関数の保持するスタティック変数の もので、その内容は本関数の次の呼び出し時まで有効です。

idn__debug_ucs4xstring

char
*idn__debug_ucs4xstring(const unsigned long *s, int maxbytes)

長さ length の UCS4 文字列 s を16進表示した文字列を 返します。

maxbytes は表示する最大のバイト長で、 length がこれを超えた場合には最後に ...が追加されます。

返される文字列のメモリ領域は本関数の保持するスタティック変数の もので、その内容は本関数の次の呼び出し時まで有効です。

idn__debug_hexdata

char *
idn_debug_hexdata(const char *s, int length, int maxlength)

長さ length のバイト列 s を16進表示した文字列を 返します。

maxbytes は表示する最大のバイト長で、 length がこれを超えた場合には最後に ...が追加されます。

返される文字列のメモリ領域は本関数の保持するスタティック変数の もので、その内容は本関数の次の呼び出し時まで有効です。

idn__debug_hexdump

void
idn_debug_hexdump(const char *s, int length)

長さ length のバイト列 s の16進ダンプを 標準エラー出力に表示します。


delimitermapモジュール

通常、ドメイン名の区切りとして用いるデリミタはピリオド(`.') だけですが、このdelimitermapモジュールは ピリオド以外の文字をデリミタとして使用できるようにするために、他の文字から ピリオドへのマッピングを行います。

idnkit ライブラリの使用者が設定するものとは別に、デフォルトでいくつか のデリミタが登録されています。登録されているのは、 U+002E (FULL STOP)、U+3002 (IDEOGRAPHIC FULL STOP)、 U+FF0E (FULLWIDTH FULL STOP)、U+FF61 (HALFWIDTH IDEOGRAPHIC FULL STOP) です。 これらの文字は、どんな場合でもピリオドにマッピングされます。

delimitermapモジュールは「デリミタマップコンテキスト」 という概念を用います。 マッピングに先立ってまずデリミタマップコンテキストを作成し、デリミタとして 使用する文字を登録しておきます。 実際のマッピング処理の際にはマッピング方式ではなく、この マップコンテキストを指定します。 マップコンテキストの型はidn_delimitermap_t 型であり、 次のような opaque 型として定義されています。

typedef struct idn_delimitermap *idn_delimitermap_t;

以下にモジュールの提供するAPI関数を示します。

idn_delimitermap_create

idn_result_t
idn_delimitermap_create(idn_delimitermap_t *ctxp)

空のデリミタマップコンテキストを作成し、ctxp の指す領域に格納 します。 返されるコンテキストは空で、デリミタは一つも含まれていません。 デリミタを追加するには idn_delimitermap_addidn_delimitermap_addall を用います。 コンテキストで作成された時点では、コンテキストの参照カウントは 1 になって います。

返される値は idn_successidn_nomemory のいずれかです。

idn_delimitermap_destroy

void
idn_delimitermap_destroy(idn_delimitermap_t ctx)

idn_delimitermap_create で 作成したマップコンテキストの参照カウントを一つ減らします。 その結果、カウントが 0 になれば、コンテキストを削除し、アロケートされた メモリを解放します。

idn_delimitermap_incrref

void
idn_delimitermap_incrref(idn_delimitermap_t ctx)

idn_delimitermap_create で 作成したコンテキストの参照カウントを一つ増やします。

idn_delimitermap_add

extern idn_result_t
idn_delimitermap_add(idn_delimitermap_t ctx, unsigned long delimiter)

idn_delimitermap_create で作成したコンテキストに、UCS コードポイント delimiter を ドメイン名のデリミタ (区切り文字)として追加します。

この関数から返される値は idn_successidn_nomemoryidn_invalid_codepoint、 のいずれかです。

idn_delimitermap_addall

idn_result_t
idn_delimitermap_addall(idn_delimitermap_t ctx, unsigned long *delimiters,
        int ndelimiters)

idn_delimitermap_addallは一度に複数のデリミタ (区切り文字) を追加することを除いて、 idn_delimitermap_addと 同じです。 長さnnamesからなる配列namesの各要素をデリミタとして 登録します。 すべてのデリミタの追加に成功するとidn_successを返します。 登録に失敗した場合、失敗した方式より先に記述されていたデリミタだけが コンテキスト ctx に登録された状態になります。

idn_delimitermap_map

idn_result_t
idn_delimitermap_map(idn_delimitermap_t ctx, const char *from, char *to,
        size_t tolen)

UCS4 でエンコードされた文字列 fromctxによる マッピングを適用します。 idnkit ライブラリにデフォルトで登録されているデリミタと ctxに登録されているデリミタ (区切り文字) をピリオド (`.')にマッピングし、結果を totolen で指定される領域に書き込みます。

この関数から返される値は idn_successidn_buffer_overflowidn_invalid_encoding、 のいずれかです。


filecheckerモジュール

filecheckerモジュールは、ドメイン名に使用できない文字を定義 したファイルを読み込み、その定義にしたがったドメイン名を検査を行うす るためのモジュールです。

このモジュールはcheckerモジュール の下位モジュールとして実装されており、 アプリケーションがこのモジュールを直接呼び出すことはありません。 checkerモジュールに対して filecsetによる検査を要求すると、このモジュールが間接的 に呼び出されることになります。

ファイルの記述方法については、 セットファイルの形式 の項を参照してください。

以下にモジュールの提供するAPI関数を示します。

idn__filechecker_create

idn_result_t
idn__filechecker_create(const char *file, idn_filechecker_t *ctxp)

検査ファイルコンテキストを一つ作成します。 ドメイン名に使用できない文字を定義したファイル fileを読み 込み、生成した検査コンテキストに追加します。

返される値は idn_successidn_nomemoryidn_nofileidn_invalid_syntax のいずれかです。

idn__filechecker_destroy

void
idn__filechecker_destroy(idn_filechecker_t ctx)

idn__filechecker_create で 作成したコンテキストを削除し、アロケートされたメモリを解放します。

idn__filechecker_lookup

idn_result_t
idn__filechecker_lookup(idn__filechecker_t ctx, const unsigned long *str,
        const unsigned long **found)

UCS4 でエンコードされたラベル strctx に 指定された検査方式で検査します。 文字列が禁止文字、未割り当てコードポイントを含んでいた場合、 foundにその先頭位置を格納します。 含まれていない場合は、NULLを返します。

返される値は idn_successidn_nomemoryidn_buffer_overflowidn_invalid_encoding のいずれかです。


filemapperモジュール

filemapperモジュールは、ドメイン名中の各文字のマッピング規則 を定義したファイルを読み込み、その定義にしたがってマッピングを行うための モジュールです。

このモジュールはmapperモジュール の下位モジュールとして実装されており、 アプリケーションがこのモジュールを直接呼び出すことはありません。 mapperモジュールに対して filecmapによる検査を要求すると、このモジュールが間接的 に呼び出されることになります。

ファイルの記述方法については、 マップファイルの形式 の項を参照してください。

以下にモジュールの提供するAPI関数を示します。

idn__filemapper_create

idn_result_t
idn__filemapper_create(const char *file, idn_filemapper_t *ctxp)

マップファイルコンテキストを一つ作成します。 マッピング規則を定義したファイル fileを読み 込み、生成した検査コンテキストに追加します。

返される値は idn_successidn_nomemoryidn_nofileidn_invalid_syntax のいずれかです。

idn__filemapper_destroy

void
idn__filemapper_destroy(idn_filemapper_t ctx)

idn__filemapper_create で 作成したコンテキストを削除し、アロケートされたメモリを解放します。

idn__filemapper_map

idn_result_t
idn__filemapper_map(idn__filemapper_t ctx, const unsigned long *from,
        unsigned long *to, size_t tolen)

UCS4 でエンコードされたラベル fromctx で 指定されるマッピングを適用し、その結果を totolen で 指定される領域に書き込みます。

返される値は idn_successidn_nomemoryidn_buffer_overflowidn_invalid_encoding のいずれかです。


localencodingモジュール

localencodingモジュールはロケール情報を利用して、 アプリケーションの使用しているエンコーディングを推測するモジュールです。

以下にモジュールの提供するAPI関数を示します。

idn_localencoding_name

const char *
idn_localencoding_name(void)

現在のロケール情報を元に、アプリケーションの使用しているエンコーディング名 (idn_converter_create() に渡す 名前) を推測して返します。

推測は、システムがnl_langinfo() を備えていればそれを利用し、 そうでなければsetlocale() や環境変数の情報から行われます。 後者の場合には必ずしも正しいエンコーディング名が得られるとは限りません。

ロケール情報から正しい推測ができない場合、もしくはアプリケーションが ロケールと異なるエンコーディングを用いて動作している場合のために、 もし環境変数 IDN_LOCAL_CODESET が定義されていれば、 アプリケーションのロケールに関わらず、その変数の値をエンコーディング名として 返すようになっています。


logモジュール

logモジュールはidnkit ライブラリのログの出力処理を制御する モジュールです。 ログはデフォルトでは標準エラー出力に書き出されますが、ハンドラを登録する ことで、別の出力方法に変更することも可能です。

またログレベルを設定することも可能です。ログレベルは次の5段階が 定義されています。 ただし idn_log_level_dump レベルのログを採取するには、 idnkit ライブラリをデバッグオプション付きで作成する必要があります。 詳細は idn_log_dump を 参照してください。

enum {
        idn_log_level_fatal   = 0,
        idn_log_level_error   = 1,
        idn_log_level_warning = 2,
        idn_log_level_info    = 3,
        idn_log_level_trace   = 4,
        idn_log_level_dump    = 5
};

以下にモジュールの提供するAPI関数を示します。

idn_log_fatal

void
idn_log_fatal(const char *fmt, ...)

fatal レベルのログを出力します。このレベルは、プログラムの実行が 不可能であるような致命的なエラーの際に用いられます。 引数はprintf と同じ形式で指定します。

idn_log_error

void
idn_log_error(const char *fmt, ...)

error レベルのログを出力します。このレベルは、 致命的ではないエラーの際に用いられます。 引数はprintf と同じ形式で指定します。

idn_log_warning

void
idn_log_warning(const char *fmt, ...)

warning レベルのログを出力します。このレベルは警告メッセージを 表示するために用いられます。 引数はprintf と同じ形式で指定します。

idn_log_info

void
idn_log_info(const char *fmt, ...)

info レベルのログを出力します。このレベルはエラーではなく、 有用と思われる情報を出力するのに用いられます。 引数はprintf と同じ形式で指定します。

idn_log_trace

void
idn_log_trace(const char *fmt, ...)

trace レベルのログを出力します。このレベルはAPI関数のトレース 情報を出力するのに用いられます。一般にライブラリのデバッグ目的以外で このレベルのログを記録する必要はないでしょう。 引数はprintf と同じ形式で指定します。

idn_log_dump

void
idn_log_dump(const char *fmt, ...)

dump レベルのログを出力します。このレベルはさらにデバッグ用の パケットデータダンプなどを出力するのに用いられます。 一般にライブラリのデバッグ目的以外でこのレベルのログを記録する 必要はないでしょう。 引数は printf と同じ形式で指定します。

dump レベルはライブラリ内部のデバッグのために設けられたものであり、 idn_log_setlevel 等で ログレベルを適切に設定しても通常は出力されません。 出力するためには idnkit ライブラリをデバッグオプション付きで作成する必要が あります。このためには configure の実行時に --enable-debug オプションを 指定してください。

idn_log_setlevel

void
idn_log_setlevel(int level)

ログ出力のレベルを設定します。設定したレベルを超えるレベルの ログは出力されません。この関数でログレベルを設定しない場合、 環境変数 IDN_LOG_LEVEL に設定された整数値が使用されます。

idn_log_getlevel

int
idn_log_getlevel(void)

現在のログ出力のレベルを表す整数値を取得して返します。

idn_log_setproc

void
idn_log_setproc(idn_log_proc_t proc)

ログの出力ハンドラを設定します。proc はハンドラ関数への ポインタです。もしハンドラを指定しない場合、あるいは procNULL を指定した場合には、ログは標準エラー出力に出力されます。

ハンドラの型 idn_log_proc_t は次のように定義されています。

typedef void  (*idn_log_proc_t)(int level, const char *msg);

level にはログのレベルが、また msg には表示すべき メッセージ文字列が渡されます。


mapperモジュール

mapperモジュールは、ドメイン名中の文字のマッピングを 行うためのモジュールです。

現在サポートされているマッピング方式は次の通りです。

  • NAMEPREPマッピング
  • マッピング規則を定義したファイルを読み込み、その記述にしたがった マッピング

また、別の新たなマッピング方式を追加登録するためのAPIも用意されています。

mapperモジュールは「マップコンテキスト」という概念を用います。 マッピングの実行に先立ってまずマップコンテキストを作成し、使用する マッピング方式をコンテキストに登録しておきます。 実際のマッピング処理の際にはマッピング方式ではなく、 このマップコンテキストを指定します。 マップコンテキストの型は idn_mapper_t 型であり、 次のような opaque 型として定義されています。

typedef struct idn_mapper *idn_mapper_t;

以下にモジュールの提供するAPI関数を示します。

idn_mapper_initialize

idn_result_t
idn_mapper_initialize(void)

モジュールの初期化処理を行います。本モジュールの他のAPI関数を呼ぶ前に 必ず呼び出してください。

返される値は idn_successidn_nomemory のいずれかです。

idn_mapper_create

idn_result_t
idn_mapper_create(idn_mapper_t *ctxp)

マッピング用の空のコンテキストを作成し、ctxp の指す領域に格納 します。 返されるコンテキストは空で、マッピング方式は一つも含まれていません。 マッピング方式を追加するには idn_mapper_addidn_mapper_addallを用います。 コンテキストで作成された時点では、コンテキストの参照カウントは 1 になって います。

返される値は idn_successidn_nomemory のいずれかです。

idn_mapper_destroy

void
idn_mapper_destroy(idn_mapper_t ctx)

idn_mapper_create で 作成したマップコンテキストの参照カウントを一つ減らします。 その結果、カウントが 0 になれば、コンテキストを削除し、アロケートされた メモリを解放します。

idn_mapper_incrref

void
idn_mapper_incrref(idn_mapper_t ctx)

idn_mapper_create で 作成したコンテキストの参照カウントを一つ増やします。

idn_mapper_add

extern idn_result_t
idn_mapper_add(idn_mapper_t ctx, const char *name)

idn_mapper_create で 作成したコンテキストに、name で指定される マッピング方式を追加します。一つのコンテキストに複数のマッピング方式を 追加することができます。

マッピング方式nameの書式は次のようになります。

<nameprep-version>
NAMEPREP バージョン <nameprep-version> のマッピング 規則。
filemap:<path>
<path>で指定されたファイルから、マッピング規則を 読み込み、その内容に従ってマッピングを行います。 ファイルの記述方法については、 マップファイルの形式 の項を参照してください。
<prefix>:<parameter>
idn_mapper_register で登録したマッピング方式 <prefix> によるマッピングを 行います。 <parameter> は、登録した関数 createに対して 引数<parameter>として渡されます。

返される値は idn_successidn_nomemoryidn_buffer_overflowidn_invalid_encoding のいずれかです。

idn_mapper_addall

idn_result_t
idn_mapper_addall(idn_mapper_t ctx, const char **names, int nnames)

idn_mapper_addallは一度に複数のマッピング方式を追加する ことを除いて、 idn_mapper_addと 同じです。 長さnnamesからなる配列namesの各要素を マッピング方式として登録します。 すべての方式の追加に成功するとidn_successを返します。 登録に失敗した場合、失敗した方式より先に記述されていた方式だけが コンテキスト ctx に登録された状態になります。

idn_mapper_map

idn_result_t
idn_mapper_map(idn_mapper_t ctx, const unsigned long *from,
        unsigned long *to, size_t tolen)

UCS4 でエンコードされたラベル fromctx で 指定されるマッピング方式を適用し、その結果を totolen で指定される領域に書き込みます。 ctx に複数のマッピング方式が含まれている場合、それらが idn_mapper_add で 追加した順番に適用されます。

返される値は idn_successidn_nomemoryidn_buffer_overflowidn_invalid_encoding のいずれかです。

idn_mapper_register

idn_result_t
idn_mapper_register(const char *prefix,
        idn_mapper_createproc_t create,
        idn_mapper_destroyproc_t destroy,
        idn_mapper_mapproc_t map)

新しいマッピング方式を登録します。 prefixには、マッピング方法の名称を指定します。 idn_mapper_addidn_mapper_addall でコンテキストにマッピング方式を登録する際に、この名称でマッピング方法を 指定します。

createdestroymapには、それぞれ idn_mapper_createidn_mapper_destroyidn_mapper_map の処理が行われる際に、呼び出してほしい関数を指定します。 それぞれの関数は、次のような引数、戻り値でなくてはなりません。

typedef idn_result_t (*idn_mapper_createproc_t)
        (const char *parameter, void **ctxp);

typedef void (*idn_mapper_destroyproc_t)
        (void *ctx);

typedef idn_result_t (*idn_mapper_mapproc_t)
        (void *ctx, const unsigned long *from, unsigned long *, size_t);

返される値は idn_successidn_nomemory のいずれかです。


mapselectorモジュール

mapselectorモジュールは、 mapperモジュールと同様に、 ドメイン名中の文字のマッピングを行います。 mapselectorは、ドメイン名のトップレベルドメイン毎に異なった マッピング規則を適当させることができるように mapperを拡張 したものです。

mapselectorモジュールは「マップ選択コンテキスト」という概念を 用います。 マッピングを行うに先立ってまずマップコンテキストを作成し、使用する マッピング方式をコンテキストに登録しておきます。 実際のマッピング処理の際にはマッピング方式ではなく、 このマップコンテキストを指定します。 マップコンテキストの型は idn_mapselector_t 型であり、 次のような opaque 型として定義されています。

typedef struct idn_mapselector *idn_mapselector_t;

以下にモジュールの提供するAPI関数を示します。

idn_mapselector_initialize

idn_result_t
idn_mapselector_initialize(void)

モジュールの初期化処理を行います。本モジュールの他のAPI関数を呼ぶ前に 必ず呼び出してください。

返される値は idn_successidn_nomemory のいずれかです。

idn_mapselector_create

idn_result_t
idn_mapselector_create(idn_mapselector_t *ctxp)

マップ選択用の空のコンテキストを作成し、ctxp の指す領域に格納 します。 返されるコンテキストは空で、マッピング方式は一つも含まれていません。 マッピング方式を追加するには idn_mapselector_addidn_mapselector_addallを用います。 コンテキストで作成された時点では、コンテキストの参照カウントは 1 になって います。

返される値は idn_successidn_nomemory のいずれかです。

idn_mapselector_destroy

void
idn_mapselector_destroy(idn_mapselector_t ctx)

idn_mapselector_create で 作成したマップコンテキストの参照カウントを一つ減らします。 その結果、カウントが 0 になれば、コンテキストを削除し、アロケートされた メモリを解放します。

idn_mapselector_incrref

void
idn_mapselector_incrref(idn_mapselector_t ctx)

idn_mapselector_create で 作成したコンテキストの参照カウントを一つ増やします。

idn_mapselector_mapper

idn_mapper_t
idn_mapselector_mapper(idn_mapselector_t ctx, const char *tld)

マップ選択コンテキストctxは、マッピング規則を トップレベルドメイン毎に1個のmapperモジュールのコンテキストに 格納して管理しています。 この関数は、ctxが保持している、 トップレベルドメインtldに対する mapperコンテキストを取り出します。

取り出したコンテキストの参照カウントは 2 になっています。 取り出したコンテキストを使い終わったら、必ず idn_mapper_destroy を呼び出して参照カウントを減らして下さい。

idn_mapselector_add

extern idn_result_t
idn_mapselector_add(idn_mapselector_t ctx, const char *tld, const char *name)

idn_mapselector_create で 作成したコンテキストに、トップレベルドメインがtldのドメイン名 に対するマッピング方式として name を追加します。 一つのコンテキストの各トップドメインに対して、複数のマッピング方式を追加 することができます。

tldには .jp.tw のようなトップレベル ドメイン名を指定します。(先頭の `.' は省略可能です。)

加えて、tldに `.' を指定すると、 マッピング規則が定義されていないトップレベルドメインに対する、デフォルト のマッピング規則を追加します。 同様に`-' を指定すると、トップレベルドメインを持たない ドメイン名 (`.' を含まないドメイン名) に適当するマッピング 規則を追加します。

マッピング方式nameの書式は、 idn_mapper_map のものと 変わりません。 idn_mapper_registerで 登録したマッピング方式も指定することができます。

返される値は idn_successidn_nomemoryidn_buffer_overflowidn_invalid_encoding のいずれかです。

idn_mapselector_addall

idn_result_t
idn_mapselector_addall(idn_mapselector_t ctx, const char *tld,
        const char **names, int nnames)

idn_mapselector_addallは一度に複数のマッピング方式を追加する ことを除いて、 idn_mapselector_addと 同じです。 長さnnamesからなる配列namesの各要素を マッピング方式として登録します。 すべての方式の追加に成功するとidn_successを返します。 登録に失敗した場合、失敗した方式より先に記述されていた方式だけが コンテキスト ctx に登録された状態になります。

idn_mapselector_map

idn_result_t
idn_mapselector_map(idn_mapselector_t ctx, const unsigned long *from,
        const char *tld, unsigned long *to, size_t tolen)

UCS4 でエンコードされたラベル from に対して、ローカルマッピング を行います。 そのラベルを含むドメイン名のトップレベルドメインを tld に指定 します。 マッピングには、ctx で指定されたマッピング方式を適用し、結果は totolen で指定される領域に書き込みます。 ctx に、そのトップレベルドメイン向けのマッピング方式が複数個 含まれている場合、それらが idn_mapselector_add で 追加した順番に適用されます。

返される値は idn_successidn_nomemoryidn_buffer_overflowidn_invalid_encoding のいずれかです。

idn_mapselector_map2

idn_result_t
idn_mapselector_map2(idn_mapselector_t ctx, const unsigned long *from,
        unsigned long *tld, unsigned long *to, size_t tolen)

この関数は idn_mapselector_map とほとんど同じですが、 トップレベルドメイン tld を UCS4 文字列で指定する点が 異なります。


nameprepモジュール

nameprepモジュールは、NAMEPREP の記述にしたがってドメイン名の 正規化とチェックを行うためのモジュールです。

現在サポートされているNAMEPREPのバージョンは次の通りです。

  • nameprep-03
  • nameprep-10
  • nameprep-11

nameprepモジュールは「NAMEPREPコンテキスト」という概念を 用います。 正規化に先立ってまずNAMEPREPコンテキストを作成し、使用する バージョンをコンテキストに登録しておきます。 実際の正規化・チェック処理の際には、NAMEPREPバージョンではなく、コンテキストを 指定します。 NAMEPREPコンテキストの型は idn_nameprep_t 型であり、 次のような opaque 型として定義されています。

typedef struct idn_nameprep *idn_nameprep_t;

以下にモジュールの提供するAPI関数を示します。

idn_nameprep_create

idn_result_t
idn_nameprep_create(const char *version, idn_nameprep_t *handlep)

指定されたバージョンversion のNAMEPREPコンテキストを 作成し、handlep の指す領域に格納します。

返される値は idn_successidn_notfound のいずれかです。

idn_nameprep_destroy

void
idn_nameprep_destroy(idn_nameprep_t handle)

idn_nameprep_create で 作成したNAMEPREPコンテキストを削除し、アロケートされたメモリを解放します。

idn_nameprep_map

idn_result_t
idn_nameprep_map(idn_nameprep_t handle, const unsigned long *from,
        unsigned long *to, size_t tolen)

UCS4 でエンコードされたラベル fromhandle で 指定されるマッピング方式を適用し、その結果を totolen で指定される領域に書き込みます。

返される値は idn_successidn_buffer_overflowidn_invalid_encoding のいずれかです。

idn_nameprep_isprohibited

idn_result_t
idn_nameprep_isprohibited(idn_nameprep_t handle, const unsigned long *s,
        const unsigned long **found)

UCS4 でエンコードされたラベル shandle に 指定された検査方式で検査します。 文字列が使用を禁止されている文字を含んでいた場合、 foundにその先頭位置を格納します。 含まれていない場合は、NULLを返します。

返される値は idn_successidn_invalid_encoding のいずれかです。

idn_nameprep_isunassigned

idn_result_t
idn_nameprep_isunassigned(idn_nameprep_t handle, const unsigned long *s,
        const unsigned long **found)

UCS4 でエンコードされたラベル shandle に 指定された検査方式で検査します。 文字列が未割り当てコードポイントを含んでいた場合、 foundにその先頭位置を格納します。 含まれていない場合は、NULLを返します。

返される値は idn_successidn_invalid_encoding のいずれかです。

idn_nameprep_isvalidbidi

idn_result_t
idn_nameprep_isvalidbidi(idn_nameprep_t handle, const unsigned long *str,
        const unsigned long **found)

UCS4 でエンコードされたラベル shandle に 指定された検査方式で検査します。 文字列が双方向文字列の記述ルールに反していた場合、 foundにその先頭位置を格納します。 反していない場合は、NULLを返します。

返される値は idn_successidn_invalid_encoding のいずれかです。


normalizerモジュール

normalizerモジュールは文字列の正規化を行うモジュールです。 正規化の方式としては現在次のものが用意されています。

  • unicode-form-c
    Unicode のバージョンの中で、idnkit が対応している最も新しい バージョンによる Unicode normalization form C (Unicode normalization form C については、 Unicode Normalization Forms を参照のこと)
  • unicode-form-kc
    Unicode のバージョンの中で、idnkit が対応している最も新しい バージョンによる Unicode normalization form KC (Unicode normalization form KC については、 Unicode Normalization Forms を参照のこと)
  • unicode-form-c/3.0.1
    Unicode バージョン 3.0.1 による Unicode normalization form C
  • unicode-form-kc/3.0.1
    Unicode バージョン 3.0.1 による Unicode normalization form KC
  • unicode-form-c/3.1.0
    Unicode バージョン 3.1.0 による Unicode normalization form C
  • unicode-form-kc/3.1.0
    Unicode バージョン 3.1.0 による Unicode normalization form KC
  • unicode-form-c/3.2.0
    Unicode バージョン 3.2.0 による Unicode normalization form C
  • unicode-form-kc/3.2.0
    Unicode バージョン 3.2.0 による Unicode normalization form KC
  • nameprep-03
    unicode-form-kc/3.0.1 の別名
  • nameprep-10
    unicode-form-kc/3.1.0 の別名。
  • nameprep-11
    unicode-form-kc/3.2.0 の別名。

正規化方式は複数併用することも可能で、この場合指定した順に適用されます。 また別の新たな正規化方式を追加登録するためのAPIも用意されています。

normalizerモジュールは「正規化コンテキスト」という概念を用います。 正規化を行うに先立ってまず正規化コンテキストを作成し、使用する 正規化方式をコンテキストに登録しておきます。 実際の正規化処理の際には正規化方式ではなく、 この正規化コンテキストを指定します。 正規化コンテキストの型は idn_normalizer_t 型であり、 次のような opaque 型として定義されています。

typedef struct idn_normalizer *idn_normalizer_t;

以下にモジュールの提供するAPI関数を示します。

idn_normalizer_initialize

idn_result_t
idn_normalizer_initialize(void)

モジュールの初期化処理を行います。本モジュールの他のAPI関数を呼ぶ前に 必ず呼び出してください。

返される値は idn_successidn_nomemory のいずれかです。

idn_normalizer_create

idn_result_t
idn_normalizer_create(idn_normalizer_t *ctxp)

正規化用の空のコンテキストを作成し、ctxp の指す領域に格納します。 返されるコンテキストは空で、正規化方式は一つも含まれていません。 正規化方式を追加するには idn_normalizer_addidn_normalizer_addall を用います。 コンテキストで作成された時点では、コンテキストの参照カウントは 1 になって います。

返される値は idn_successidn_nomemory のいずれかです。

idn_normalizer_destroy

void
idn_normalizer_destroy(idn_normalizer_t ctx)

idn_normalizer_create で 作成した正規化コンテキストの参照カウントを一つ減らします。 その結果、カウントが 0 になれば、コンテキストを削除し、アロケートされた メモリを解放します。

idn_nomalizer_incrref

void
idn_normalizer_incrref(idn_normalizer_t ctx)

idn_normalizer_create で 作成した正規化コンテキストの参照カウントを一つ増やします。

idn_normalizer_add

idn_result_t
idn_normalizer_add(idn_normalizer_t ctx, const char *scheme_name)

idn_normalizer_create で 作成した正規化コンテキストに、scheme_name で指定される 正規化方式を追加します。一つのコンテキストに複数の正規化方式を 追加することができます。

返される値は idn_successidn_invalid_nameidn_nomemory のいずれかです。

idn_normalizer_addall

idn_result_t
idn_normalizer_addall(idn_normalizer_t ctx, const char **scheme_names,
        int nschemes)

idn_normalizer_addallは一度に複数の正規化方式を追加する ことを除いて、 idn_normalizer_addと 同じです。 長さnschemesからなる配列scheme_namesの各要素を 正規化方式として登録します。 すべての方式の追加に成功するとidn_successが返ります。 登録に失敗した場合、失敗した方式より先に記述されていた方式だけが コンテキスト ctx に登録された状態になります。

idn_normalizer_normalize

idn_result_t
idn_normalizer_normalize(idn_normalizer_t ctx, const unsigned long *from,
        unsigned long *to, size_t tolen)

UCS4 でエンコードされたラベル fromctx で 指定される正規化方式を適用し、その結果を totolen で 指定される領域に書き込みます。 ctx に複数の正規化方式が含まれている場合、それらが idn_normalizer_add で 追加した順番に適用されます。

返される値は idn_successidn_invalid_encodingidn_nomemory のいずれかです。

idn_normalizer_register

idn_result_t
idn_normalizer_register(const char *scheme_name,
        idn_normalizer_proc_t proc)

新しい正規化方式を scheme_name という名前で登録します。 proc はその正規化方式の処理関数へのポインタです。

返される値は idn_successidn_nomemory のいずれかです。


punycodeモジュール

punycodeモジュールは、国際化ドメイン名のエンコーディング方式の 一つとして提案された Punycode と UCS4 との間の変換を行うモジュールです。

このモジュールは converterモジュールの 下位モジュールとして実装されており、 アプリケーションがこのモジュールを直接呼び出すことはありません。 converterモジュールに対して Punycode エンコーディング との変換を要求すると、このモジュールが間接的に呼び出されることになります。

以下にモジュールの提供するAPI関数を示します。

idn__punycode_decode

idn_result_t
idn__punycode_decode(idn_converter_t ctx, void *privdata,
        const char *from, unsigned long *to, size_t tolen);

Punycodeエンコードされたラベルを UCS4 に変換 (デコード) します。 入力ラベル from を変換し、結果を totolen で指定される領域に書き込みます。

返される値は idn_successidn_buffer_overflowidn_invalid_encodingidn_nomemory のいずれかです。

idn__punycode_encode

idn_result_t
idn__punycode_encode(idn_converter_t ctx, void *privdata,
        const unsigned long *from, char *to, size_t tolen);

UCS4 エンコードされたラベルを Punycode に変換 (エンコード) します。 入力ラベル from を変換し、結果を totolen で指定される領域に書き込みます。

返される値は idn_successidn_buffer_overflowidn_invalid_encodingidn_nomemory のいずれかです。


raceモジュール

raceモジュールは、国際化ドメイン名のエンコーディング方式の 一つとして提案された RACE エンコーディング とUCS4との間の変換を行うモジュールです。

Punycode と同様、RACE も ACE の一種ですが、すでに廃れた存在となって おり、idnkit を標準の手順でインストールしても、RACE は使用できない ようになっています。 idnkit で RACE を使用するには、インストールする際に、 configure--enable-extra-ace オプション を与えてください。

race モジュールは converterモジュールの下位モジュール として実装されており、 アプリケーションがこのモジュールを直接呼び出すことはありません。 converterモジュールに対して RACEエンコーディングとの変換を要求すると、このモジュールが 間接的に呼び出されることになります。

以下にモジュールの提供するAPI関数を示します。

idn__race_encode

idn_result_t
idn__race_encode(idn_converter_t ctx, void *privdata,
        const unsigned long *from, char *to, size_t tolen)

UCS4エンコードされたラベルをRACE に変換します。 入力ラベル from を変換し、結果を totolen で指定される領域に書き込みます。

返される値は idn_successidn_buffer_overflowidn_invalid_encodingidn_nomemory のいずれかです。

idn__race_decode

idn_result_t
idn__race_decode(idn_converter_t ctx, void *privdata,
        const char *from, unsigned long *to, size_t tolen)

RACEエンコードされたラベルを UCS4 に変換します。 入力ラベル from を変換し、結果を totolen で指定される領域に書き込みます。

返される値は idn_successidn_buffer_overflowidn_invalid_encodingidn_nomemory のいずれかです。


resモジュール

resモジュールはクライアント側 (アプリケーション)で国際化ドメイン名の処理、つまり ドメイン名のエンコーディング変換や正規化等を行う際の低レベル API を提供します。 このモジュールはあとで説明する resconfモジュール とともに用いることを前提に設計されています。

なお、 環境変数 IDN_DISABLE が設定されている場合は、以下に挙げられた文字列変換用の関数を使用しても 文字列の変換は行われず、元の文字列のままの結果が返されます。 IDN_DISABLE が設定されている環境で文字列の変換を強制的に行う場合や、 アプリケーションでこれらの API 関数を使用するうえで IDN_DISABLE の設定に関係なく一定の動作を保証したい場合は、 idn_res_enable を事前に使用しておかなければなりません。

以下にモジュールの提供するAPI関数を示します。

idn_res_enable

void
idn_res_enable(int on_off);

通常、 環境変数 IDN_DISABLE が宣言されている場合、 ドメイン名変換処理は行われず、元の文字列のままの結果が返されますが、 この関数はその設定をオーバーライドすることができます。

IDN_DISABLE が設定されているかどうかにかかわらず、 on_off に 0 以外の値を指定してこの関数を使用すると、 それ以降はドメイン名の変換を行うようになります。 0 を指定すると、それとは逆にドメイン名の変換を行なわず、 元の文字列のままの結果を返すようになります。

idn_res_encodename

idn_result_t
idn_res_encodename(idn_resconf_t ctx, idn_action_t actions, const char *from,
        char *to, size_t tolen)

文字列fromに対して、国際化ドメイン名に関する変換や検査 を行い、IDN エンコーディングとなった結果を toおよびtolenで指定された領域に格納します。 変換や検査は、設定コンテキストctxにしたがって行われます。

actions には、idn_res_encodenameに行わせたい エンコード動作を指定します。次に挙げるフラグの論理和の値 (例: IDN_NAMEPREP | IDN_IDNCONV) を指定するようにします。 指定された動作は、ここに挙げた順序でそれぞれ行われます。

IDN_LOCALCONV
ローカルエンコーディング (shift_JIS や Big5 など) の文字列を UTF-8 に変換する。(libidnkit でだけ使用できます。libidnkitlite では 使用できません。)
IDN_DELIMMAP
特定の文字をピリオド (U+002E FULL STOP) に変換する。
IDN_LOCALMAP
ドメイン名のトップレベルドメインに応じて、異なるローカルな マッピングを行う。
IDN_MAP
ドメイン名のマッピングを行う。
IDN_NORMALIZE
ドメイン名の正規化を行う。
IDN_PROHCHECK
ドメイン名の禁止文字チェックを行う。
IDN_UNASCHECK
未割り当てコードポイントのチェックを行う。
IDN_BIDICHECK
双方向文字列のチェックを行う。
IDN_ASCCHECK
ASCII 文字に関するチェック (英数字やハイフン以外の文字の有無など) を行う。
IDN_IDNCONV
UTF-8 の文字列を国際化ドメイン用のエンコーディング (Punycode, など) に変換する。
IDN_LENCHECK
ドメイン名の各ラベルの長さをチェックする。
IDN_UNDOIFERRK
処理途中に何らかの失敗があれば、from をそのまま返す。

これらに加えて、利便性を配慮して IDN_NAMEPREPIDN_ENCODE_APPIDN_ENCODE_QUERYIDN_ENCODE_STORED というフラグも用意されています。

IDN_NAMEPREP は、文字列の NAMEPREP に関連する処理を まとめて行う場合に使用します。このフラグは次の指定と等価です。

IDN_MAP | IDN_NORMALIZE | IDN_PROHCHECK | IDN_BIDICHECK

なお、ここに IDN_UNASCHECK が含まれていないのは、 未割り当てコードポイントのチェックが必要でないケースが存在するためです。 詳しくは国際化ドメイン処理のアーキテクチャである IDNA のドキュメントをごらんください。

通常、アプリケーションは actionsIDN_ENCODE_APP を指定することになります。 ライブラリとして libidnkit を使用している場合、このフラグを指定すると IDN_UNASCHECK を除いたすべてのフラグの処理を行います。 libidnkitlite を使用している場合は、IDN_LOCALCONVIDN_UNASCHECK を除いたすべてのフラグの処理を行います。

IDN_ENCODE_QUERYIDN_ENCODE_STORED は、 IDNA で明記されている、query string と stored string の使い分けのために 名称を明確化したマクロです。

IDN_ENCODE_QUERY は、IDN_ASCIIHECK を 行わないという点を除いて IDN_ENCODE_APP と同じです。 また、IDN_ENCODE_STORED は、IDN_UNASCHECK も行うという点を除いて IDN_ENCODE_APP と同じです。 (いずれも、libidnkitlite 使用時は、IDN_LOCALCONV を 行いません。)

actionsに何も指定しなければ (つまり 0 を指定した場合は)、 文字列は単にコピーされます。

この関数から返される値は idn_successidn_invalid_encodingidn_invalid_lengthidn_invalid_syntaxidn_invalid_nameidn_invalid_actionidn_buffer_overflowidn_nomemoryidn_nofileidn_prohibited のいずれかです。

libidnkitlite 使用時に IDN_LOCALCONV を指定すると、 idn_invalid_action が返ります。

idn_res_decodename

idn_result_t
idn_res_decodename(idn_resconf_t ctx, idn_action_t actions, const char *from,
        char *to, size_t tolen)

ドメイン名のデコードを行います。 入力文字列 from を変換し、結果を totolen で指定される領域に書き込みます。 変換や検査は、設定コンテキストctxにしたがって行われます。

actions には、デコードにおいて、idn_res_decodename に行わせたい変換動作を指定します。次に挙げるフラグの論理和の値を指定する ようにします。 指定された動作は、ここに挙げたのと同じ順序でそれぞれ行われます。

IDN_MAP
ドメイン名のマッピングを行う。
IDN_NORMALIZE
ドメイン名の正規化を行う。
IDN_PROHCHECK
ドメイン名の禁止文字チェックを行う。
IDN_UNASCHECK
未割り当てコードポイントのチェックを行う。 また、ラウンドトリップチェック時に、未割り当てコードポイントの チェックを行う。
IDN_BIDICHECK
双方向文字列のチェックを行う。
IDN_IDNCONV
国際化ドメイン用のエンコーディング (Punycode など) の文字列 を UTF-8 に変換する。
IDN_RTCHECK
ラウンドトリップチェックを行う。
IDN_ASCCHECK
ラウンドトリップチェック時に、ASCII 文字に関するチェック (英数字やハイフン以外の文字の有無など) を行う。
IDN_LOCALCONV
UTF-8 の文字列をローカルエンコーディング (shift_JIS や Big5 など) に変換する。(libidnkit でだけ使用できます。libidnkitlite では使用できません。)

これらに加えて、利便性を配慮して IDN_NAMEPREPIDN_ENCODE_APPIDN_ENCODE_QUERYIDN_ENCODE_STORED というフラグも用意されています。

IDN_NAMEPREP は、文字列の NAMEPREP に関連する処理を まとめて行う場合に使用します。このフラグは次の指定と等価です。

IDN_MAP | IDN_NORMALIZE | IDN_PROHCHECK | IDN_BIDICHECK

なお、ここに IDN_UNASCHECK が含まれていないのは、 未割り当てコードポイントのチェックが必要でないケースが存在するためです。 詳しくは国際化ドメイン処理のアーキテクチャである IDNA のドキュメントをごらんください。

通常、アプリケーションは actionsIDN_ENCODE_APP を指定することになります。 ライブラリとして libidnkit を使用している場合、このフラグを指定すると IDN_UNASCHECK を除いたすべてのフラグの処理を行います。 libidnkitlite を使用している場合は、IDN_LOCALCONVIDN_UNASCHECK を除いたすべてのフラグの処理を行います。

IDN_ENCODE_QUERYIDN_ENCODE_STORED は、 IDNA で明記されている、query string と stored string の使い分けのために 名称を明確化したマクロです。

IDN_ENCODE_QUERY は、IDN_ASCIIHECK を 行わないという点を除いて IDN_ENCODE_APP と同じです。 また、IDN_ENCODE_STORED は、IDN_UNASCHECK も行うという点を除いて IDN_ENCODE_APP と同じです。 (いずれも、libidnkitlite 使用時は、IDN_LOCALCONV を 行いません。)

この関数から返される値は idn_successidn_invalid_encodingidn_invalid_lengthidn_invalid_syntaxidn_invalid_nameidn_invalid_actionidn_buffer_overflowidn_nomemoryidn_nofileidn_prohibited のいずれかです。

libidnkitlite 使用時に IDN_LOCALCONV を指定すると、 idn_invalid_action が返ります。

idn_res_decodename2

idn_result_t
idn_res_decodename2(idn_action_t actions, const char *from, char *to, size_t tolen,
                    const char *auxencoding);

この関数は idn_res_decodename() の拡張版です。

idn_res_decodename() では、入力文字列 (from) が 常に UTF-8 であるものとみなされます。 idn_res_decodename() の入力文字列は IDN エンコーディング ですが、IDN エンコーディング が ACE であった場合、入力された ACE 文字列 そのものは UTF-8 で書かれているものとして扱われます。

これに対して、idn_res_decodename2() では auxencoding という引数が追加されており、入力された文字列のエンコーディングを指定する ことができます。 idn_res_decodename2() は、入力文字列 from をまず auxencoding で指定されたエンコーディングから UTF-8 に変換 します。 そして、その後は idn_res_decodename() と同じ処理を行います。

auxencodingNULL を指定した場合、 入力文字列は UTF-8 であるとみなされます。 つまり、この場合は idn_res_decodename() とまったく同じ 処理を行います。

なお libidnkitlite では、この関数を使うことはできません。 呼び出すと、エラーコード idn_failure が返ります。 これは auxencodingNULL を指定した場合 も、例外ではありません。


resconfモジュール

resconfモジュールはクライアント側 (idnkit ライブラリやアプリケーション)で国際化ドメイン名の処理を行う際に 参照される idnkit設定ファイルを読み込み、 ファイルの設定にしたがった初期化を実行します。また設定情報を取り出す 機能を提供します。

resconfモジュールは「設定コンテキスト」という概念を用います。 設定ファイルに記述された設定はこの設定コンテキストに格納され、この コンテキストを引数にして API 関数を呼び出すことによって 設定された値を取り出すことができます。 設定コンテキストの型は idn_resconf_t 型であり、次のような opaque 型として定義されています。

typedef struct idn_resconf *idn_resconf_t;

このモジュールは単体でも使用できますが、 resモジュールと組み合わせることによって、 クライアント側での国際化ドメイン名の処理を簡単に行うことができるように 設計されています。

以下にモジュールの提供するAPI関数を示します。

idn_resconf_initialize

idn_result_t
idn_resconf_initialize(void)

国際化ドメイン名の処理を行う際に必要な初期化を実行します。 本モジュールの他のAPI関数を呼ぶ前に必ず呼び出してください。 本モジュールが使用する他のモジュールの初期化もすべて行うので、これ以外の初期化 関数を呼び出す必要はありません。

返される値は idn_successidn_nomemory のいずれかです。

idn_resconf_create

idn_result_t
idn_resconf_create(idn_resconf_t *ctxp)

設定コンテキストを作成、初期化し、ctxp の指す領域に格納します。 初期状態では、まだ設定ファイルの内容は読み込まれていません。 読み込むためには idn_resconf_loadfile を実行する必要があります。

返される値は idn_successidn_nomemory のいずれかです。

idn_resconf_destroy

void
idn_resconf_destroy(idn_resconf_t ctx)

idn_resconf_create で 作成した設定コンテキストの参照カウントを一つ減らします。 その結果、カウントが 0 になれば、コンテキストを削除し、アロケートされた メモリを解放します。

idn_resconf_incrref

void
idn_resconf_incrref(idn_resconf_t ctx)

idn_resconf_create で 作成した検査コンテキストの参照カウントを一つ増やします。

idn_resconf_loadfile

idn_result_t
idn_resconf_loadfile(idn_resconf_t ctx, const char *file)

file で指定される idnkit設定ファイルの内容を読み込み、 設定内容を設定コンテキスト ctx に格納します。

すでに設定ファイルが読み込まれているコンテキストに対して、 別の設定ファイルの内容を読み込むこともできます。その場合には、 設定コンテキストに格納されていた前の設定ファイルの内容はすべて消え、 新たに読み込んだ設定ファイルの内容で置き換わります。

fileNULL の場合にはデフォルトの設定ファイルの 内容を読み込みます。そのとき、ユーザの設定ファイル (.idnrc) が 存在する場合はそのファイルを読み込みます。存在しない場合は システムの設定ファイルが読み込まれます。システムの設定ファイルも 存在しない場合、 idn_resconf_setdefaults が 呼ばれ、標準的な設定が行われます。

返される値は idn_successidn_nofileidn_invalid_syntaxidn_invalid_nameidn_nomemory のいずれかです。

idn_resconf_setdefaults

idn_result_t
idn_resconf_setdefaults(idn_resconf_t ctx)

IDN 変換に必要な標準的な設定を行い、 設定内容を設定コンテキスト ctx に格納します。

ここでいう標準的な設定とは、

  • NAMEPREP に idnkit がサポートする最新のバージョン
  • IDN エンコーディングに Punycode

を指定することを意味します。

すでに設定ファイルが読み込まれているコンテキストに対して この関数を使用した場合、 設定コンテキストに格納されていた前の設定ファイルの内容はすべて消え、 新たに設定する内容で置き換わります。

返される値は idn_successidn_nomemory のいずれかです。

idn_resconf_defaultfile

char *
idn_resconf_defaultfile(void)

デフォルトのシステム設定ファイルのパス名を返します。 これは idnkit のコンパイル時の設定によって決まりますが、特に指定しなければ

/usr/local/etc/idn.conf

です。

idn_resconf_getdelimitermap

idn_delimitermap_t
idn_resconf_getdelimitermap(idn_resconf_t ctx)

設定コンテキスト ctx の情報を元に、デリミタのマッピングを 行うためのデリミタマップコンテキストを返します。コンテキストにデリミタが 指定されていない場合には NULL を返します。

デリミタマップコンテキストについては delimitermapモジュール の項を ご覧ください。

idn_resconf_getidnconverter

idn_converter_t
idn_resconf_getidnconverter(idn_resconf_t ctx)

設定コンテキスト ctx の情報を元に、IDNエンコーディングと UCS4との間の文字コード変換を行うためのコード変換コンテキストを返します。 コンテキストにIDNエンコーディングが指定されていない場合には NULL を返します。

コード変換コンテキストについては converterモジュール の項をご覧ください。

idn_resconf_getlocalconverter

idn_converter_t
idn_resconf_getlocalconverter(idn_resconf_t ctx)

設定コンテキスト ctx の情報を元に、ローカルエンコーディングと UCS4 との間の文字コード変換を行うためのコード変換コンテキストを返します。 ローカルエンコーディングが判別できなかった場合には NULL を 返します。 なお libidnkitlite でこの関数を使うと、常に NULL が返ります。

通常、設定コンテキストは、呼び出した時点でのロケール情報から ローカルエンコーディングを決定するようになっていますが、 idn_resconf_setlocalconverter() ないし idn_resconf_setlocalconvertername() を使うことで、任意のローカルエンコーディングを設定コンテキストに 対して強制的にセットすることもできます。

コード変換コンテキストについては converterモジュール の項をご覧ください。

idn_resconf_getmapper

idn_mapper_t
idn_resconf_getmapper(idn_resconf_t ctx)

設定コンテキスト ctx の情報を元に、マップ処理を行うための マップコンテキストを返します。コンテキストにマッピング方式が 指定されていない場合には NULL を返します。

マップコンテキストについては mapperモジュール の項をご覧ください。

idn_resconf_getnormalizer

idn_normalizer_t
idn_resconf_getnormalizer(idn_resconf_t ctx)

設定コンテキスト ctx の情報を元に、正規化処理を行うための 正規化コンテキストを返します。コンテキストに正規化方式が指定されていない 場合には NULL を返します。

正規化変換コンテキストについては normalizerモジュール の項を ご覧ください。

idn_resconf_getprohibitchecker

idn_checker_t
idn_resconf_getprohibitchecker(idn_resconf_t ctx)

設定コンテキスト ctx の情報を元に、禁止文字の検査処理を 行うための検査コンテキストを返します。コンテキストに禁止文字の検査方式が 指定されていない場合には NULL を返します。

検査コンテキストについては checkerモジュール の項を ご覧ください。

idn_resconf_getunassignedchecker

idn_checker_t
idn_resconf_getunassignedchecker(idn_resconf_t ctx)

設定コンテキスト ctx の情報を元に、未割り当てコードポイントの 検査処理を行うためのチェッカーコンテキストを返します。コンテキストに 未割り当てコードポイントの検査方式が指定されていない場合には NULL を返します。

検査コンテキストについては checkerモジュール の項を ご覧ください。

idn_resconf_getbidichecker

idn_checker_t
idn_resconf_getbidichecker(idn_resconf_t ctx)

設定コンテキスト ctx の情報を元に、双方向文字列の検査処理を 行うためのチェッカーコンテキストを返します。コンテキストに 双方向文字列の検査方式が指定されていない場合には NULL を返します。

検査コンテキストについては checkerモジュール の項を ご覧ください。

idn_resconf_setdelimitermap

idn_result_t
idn_resconf_setdelimitermap(idn_resconf_t ctx,
        idn_delimitermap_t delimiter_mapper)

デリミタマップコンテキストdelimiter_mapperの情報をもとに、 デリミタを設定コンテキストctxにセットします。 delimiter_mapperNULL を渡した場合、 デリミタは未指定の状態となります。

デリミタマップコンテキストについては delimitermapモジュール の項を ご覧ください。

idn_resconf_setidnconverter

idn_result_t
idn_resconf_setidnconverter(idn_resconf_t ctx,
        idn_converter_t idn_converter)

コード変換コンテキストidn_converterの情報をもとに、 IDN エンコーディングを設定コンテキストctxにセットします。 idn_converterNULL を渡した場合、変換方式 は未指定の状態となります。

コード変換コンテキストについては converterモジュール の項をご覧ください。

idn_resconf_setlocalconverter

idn_result_t
idn_resconf_setlocalconverter(idn_resconf_t ctx,
        idn_converter_t local_converter)

コード変換コンテキストlocal_converterの情報をもとに、 ローカルエンコーディングを設定コンテキストctxにセットします。 local_converterNULL を渡すと、 ローカルエンコーディングは自動判別されます。 この場合、その後でロケール情報が変化すると、ローカルエンコーディングも それに合わせて変わります。

反対に NULL 以外の場合は、ロケール情報が変化しても ローカルエンコーディングは変わりません。

なお libidnkitlite でこの関数を使うことはできません。 呼び出すと、エラーコード idn_failure が返ります。

コード変換コンテキストについては converterモジュール の項をご覧ください。

idn_resconf_setlocalmapselector

idn_result_t
idn_resconf_setlocalmapselector(idn_resconf_t ctx,
        idn_mapselector_t map_selector)

マップ選択コンテキストmap_selectorの情報をもとに、 ローカルなマッピング方式を設定コンテキストctxにセットします。 map_selectorNULL を渡した場合、 マッピング方式は未指定の状態となります。

マップ選択コンテキストについては mapselectorモジュール の項を ご覧ください。

idn_resconf_setmapper

idn_result_t
idn_resconf_setmapper(idn_resconf_t ctx, idn_mapper_t mapper)

マップコンテキストmapperの情報をもとに、マッピングを行うための 方式を設定コンテキストctxにセットします。mapperNULL を渡した場合、マッピング方式は未指定の状態となります。

マップコンテキストについては mapperモジュール の項をご覧ください。

idn_resconf_setnormalizer

idn_result_t
idn_resconf_setnormalizer(idn_resconf_t ctx,
        idn_normalizer_t normalizer)

正規化コンテキストnormalizerの情報をもとに、正規化方式を 設定コンテキストctxにセットします。normalizerNULL を渡した場合、正規化方式は未指定の状態となります。

正規化変換コンテキストについては normalizerモジュール の項を ご覧ください。

idn_resconf_setprohibitchecker

idn_result_t
idn_resconf_setprohibitchecker(idn_resconf_t ctx,
        idn_checker_t prohibit_checker)

検査コンテキストprohibit_checkerの情報をもとに、 禁止文字の検査を行うための検査方式を設定コンテキストctxに セットします。prohibit_checkerNULL を 渡した場合、検査方式は未指定の状態となります。

検査コンテキストについては checkerモジュール の項を ご覧ください。

idn_resconf_setunassignedchecker

idn_result_t
idn_resconf_setunassignedchecker(idn_resconf_t ctx,
        idn_checker_t unassigned_checker)

検査コンテキストunassigned_checkerの情報をもとに、 未割り当てコードポイントの検査を行うための検査方式を設定コンテキスト ctxにセットします。 unassigned_checkerNULL を渡した場合、 検査方式は未指定の状態となります。

検査コンテキストについては checkerモジュール の項を ご覧ください。

idn_resconf_setbidichecker

idn_result_t
idn_resconf_setbidichecker(idn_resconf_t ctx,
        idn_checker_t bidi_checker)

検査コンテキストbidi_checkerの情報をもとに、 双方向文字列の検査を行うための検査方式を設定コンテキスト ctxにセットします。 bidi_checkerNULL を渡した場合、 検査方式は未指定の状態となります。

検査コンテキストについては checkerモジュール の項を ご覧ください。

idn_resconf_setidnconvertername

idn_result_t
idn_resconf_setidnconvertername(idn_resconf_t ctx, const char *name,
        int flags)

IDN エンコーディングを設定コンテキストctxにセットします。 idn_converterNULL を渡した場合、 IDN エンコーディングは未指定の状態となります。

idn_resconf_addalldelimitermapucs

idn_result_t
idn_resconf_addalldelimitermapucs(idn_resconf_t ctx,
        unsigned long *v, int nv);

コードポイントの配列vとその長さnvで表された デリミタをすべて設定コンテキストctxに追加します。

idn_resconf_setlocalconvertername

idn_result_t
idn_resconf_setlocalconvertername(idn_resconf_t ctx, const char *name,
        int flags)

name で指定したローカルエンコーディング名称を設定コンテキスト ctxにセットします。 name として NULL を指定すると、自動判別した ローカルエンコーディングがセットされます。 この場合、その後でロケール情報が変化すると、ローカルエンコーディングも それに応じて変わります。 反対に NULL 以外の値だと、ロケール情報が変化しても ローカルエンコーディングは name のまま変わりません。

なお libidnkitlite でこの関数を使うことはできません。 呼び出すと、エラーコード idn_failure が返ります。

idn_resconf_addalllocalmapselectornames

idn_result_t
idn_resconf_addalllocalmapselectornames(idn_resconf_t ctx, const char *tld,
        const char **names, int nnames)

トップレベルドメインtld に対するローカルなマッピング方式と して、namesnnamesに記されたものをすべて 設定コンテキストctxに追加します。

idn_resconf_addallmappernames

idn_result_t
idn_resconf_addallmappernames(idn_resconf_t ctx, const char **names,
        int nnames)

namesnnamesに記されたマッピング方式を、すべて 設定コンテキストctxに追加します。

idn_resconf_addallnormalizernames

idn_result_t
idn_resconf_addallnormalizernames(idn_resconf_t ctx, const char **names,
        int nnames)

namesnnamesに記された正規化方式を、すべて 設定コンテキストctxに追加します。

idn_resconf_addallprohibitcheckernames

idn_result_t
idn_resconf_addallprohibitcheckernames(idn_resconf_t ctx, const char **names,
        int nnames)

namesnnamesに記された禁止文字の検査方式を、すべて 設定コンテキストctxに追加します。

idn_resconf_addallunassignedcheckernames

idn_result_t
idn_resconf_addallunassignedcheckernames(idn_resconf_t ctx,
         const char **names, int nnames)

namesnnamesに記された未割り当てコードポイントの 検査方式をすべて設定コンテキストctxに追加します。

idn_resconf_addallbidicheckernames

idn_result_t
idn_resconf_addallbidicheckernames(idn_resconf_t ctx,
         const char **names, int nnames)

namesnnamesに記された双方向文字列の 検査方式をすべて設定コンテキストctxに追加します。

idn_resconf_setnameprepversion

idn_result_t
idn_resconf_setnameprepversion(idn_resconf_t ctx,
        const char *version)

設定コンテキストctxのNAMEPREPのバージョンをversion にセットします。


resultモジュール

resultモジュールはライブラリの各関数が返す idn_result_t型の値を扱うモジュールで、 値からそのコードに対応するメッセージへの変換を提供します。

以下にモジュールの提供するAPI関数を示します。

idn_result_tostring

char *
idn_result_tostring(idn_result_t result)

idn_result_t型の値 result に対応する メッセージ文字列を返します。

未定義のコードに対しては unknown result code という文字列が 返されます。


strhashモジュール

strhashモジュールは文字列をキーとするハッシュ表を実現する モジュールです。 ハッシュ表は converterモジュールnormalizerモジュールなどライブラリの 他のモジュールで使用されます。 非常に一般的なハッシュ表の実装であり、特筆すべき点はありません… 一つだけあります。登録はできますが削除の機能がありません。本ライブラリでは 必要ないからです。

ハッシュ表のサイズは要素の総数が増えるに従って大きくなります。

ハッシュ表は次に示す idn_strhash_t 型の opaque データとして 表されます。

typedef struct idn__strhash *idn__strhash_t;

以下にモジュールの提供するAPI関数を示します。

idn__strhash_create

idn_result_t
idn__strhash_create(idn__strhash_t *hashp)

空のハッシュ表を作成し、そのハンドルを hashp の指す領域に 格納します。

返される値は idn_successidn_nomemory のいずれかです。

idn__strhash_destroy

void
idn__strhash_destroy(idn__strhash_t hash)

idn__strhash_create で作成した ハッシュ表を削除し、確保したメモリを解放します。

idn__strhash_put

idn_result_t
idn__strhash_put(idn__strhash_t hash, const char *key,
        void *value)

idn__strhash_create で作成した ハッシュ表 hash にキー key、値 value の組を 登録します。 文字列 key はコピーされますので、この関数の呼び出し後 key の指すメモリを解放しても、文字列の内容を書き換えても 影響はありません。これに対して value の内容はコピーされないので 注意してください (もちろんよく考えてみればコピーされないことは自明ですが)。

同じキーを使用して複数回登録した場合、最後に登録されたものだけが 有効です。

返される値は idn_successidn_nomemory のいずれかです。

idn__strhash_get

idn_result_t
idn__strhash_get(idn__strhash_t hash,
        const char *key, void **valuep)

ハッシュ表 hash からキー key を持つ要素を検索し、 対応する要素があればその値を valuep に格納します。

返される値は idn_successidn_noentry のいずれかです。

idn__strhash_exists

int
idn__strhash_exists(idn__strhash_t hash, const char *key)

ハッシュ表 hash にキー key を持つ要素があれば 1を、なければ 0 を返します。


ucs4モジュール

ucs4モジュールはUCS4でエンコードされた文字列の基本処理を 行うモジュールです。UTF-8 または UTF-16 文字列との相互変換と、UCS4 文 字列自体に対して使用する基本的な関数が含まれます。

以下にモジュールの提供するAPI関数を示します。

idn_ucs4_ucs4toutf16

idn_result_t
idn_ucs4_ucs4toutf16(const unsigned long *ucs4, unsigned short *utf16,
         size_t tolen)

UCS4 の文字列を UTF-16 に変換します。 入力文字列 ucs4 を変換し、結果を utf16tolen で指定される領域に書き込みます。

返される値は idn_successidn_buffer_overflowidn_invalid_encoding のいずれかです。

idn_ucs4_utf16toucs4

idn_result_t
idn_ucs4_utf16toucs4(const unsigned short *utf16, unsigned long *ucs4,
         size_t tolen)

UTF-16 の文字列を UCS4 に変換します。 入力文字列 utf16 を変換し、結果を ucs4tolen で指定される領域に書き込みます。

返される値は idn_successidn_buffer_overflowidn_invalid_encoding のいずれかです。

idn_ucs4_utf8toucs4

idn_result_t
idn_ucs4_utf8toucs4(const char *utf8, unsigned long *ucs4, size_t tolen)

UTF-8 の文字列を UCS4 に変換します。 入力文字列 utf8 を変換し、結果を ucs4tolen で指定される領域に書き込みます。

返される値は idn_successidn_buffer_overflowidn_invalid_encoding のいずれかです。

idn_ucs4_ucs4toutf8

idn_result_t
idn_ucs4_ucs4toutf8(const unsigned long *ucs4, char *utf8, size_t tolen)

UCS4 の文字列を UTF-8 に変換します。 入力文字列 ucs4 を変換し、結果を utf8tolen で指定される領域に書き込みます。

返される値は idn_successidn_buffer_overflowidn_invalid_encoding のいずれかです。

idn_ucs4_strlen

size_t
idn_ucs4_strlen(const unsigned long *ucs4)

UCS4 文字列の長さを返します。

idn_ucs4_strcpy

unsigned long *
idn_ucs4_strcpy(unsigned long *to, const unsigned long *from)

UCS4 文字列 fromto にコピーします。

idn_ucs4_strcat

unsigned long *
idn_ucs4_strcat(unsigned long *to, const unsigned long *from)

UCS4 である文字列 from を同じく UCS4 である文字列 to の末尾に連結します。

idn_ucs4_strcmp

int
idn_ucs4_strcmp(const unsigned long *str1, const unsigned long *str2)

UCS4 の文字列である str1str2 を比較します。 str1str2 に較べて

  • 小さい場合は 0 よりも小さい整数を
  • 等しい場合は 0 を
  • 大きい場合は 0 よりも大きい整数を

返します。

idn_ucs4_strcasecmp

int
idn_ucs4_strcasecmp(const unsigned long *str1, const unsigned long *str2)

UCS4 の文字列である str1str2 を、 大文字/小文字の区別せずに比較します。 ここで言う「大文字/小文字」とは、ロケールの設定に関係なく常に A~Z (U+0041 ~ U+005A) および a~z (U+0061 ~ U+007A) の範囲となります。

str1str2 に較べて

  • 小さい場合は 0 よりも小さい整数を
  • 等しい場合は 0 を
  • 大きい場合は 0 よりも大きい整数を

返します。

idn_ucs4_strdup

unsigned long *
idn_ucs4_strdup(const unsigned long *str)

UCS4 の文字列である str を複製し、その複製した文字列への ポインタを返します。文字列のメモリは malloc() で確保されます。 メモリが確保できなかった場合は NULL を返します。


ucsmapモジュール

ucsmapモジュールは、文字のマッピング規則を登録するための モジュールです。

このモジュールは、 filemapperモジュール の下位モジュールとして実装されています。

以下にモジュールの提供するAPI関数を示します。

idn_ucsmap_create

idn_result_t
idn_ucsmap_create(idn_ucsmap_t *ctxp)

UCSマップコンテキストを一つ作成します。 ただし、作成した時点のコンテキストには、マッピング規則は一つも登録されて いません。

返される値は idn_successidn_nomemory のいずれかです。

idn_ucsmap_destroy

void
idn_ucsmap_destroy(idn_ucsmap_t ctx)

idn_ucsmap_create で 作成したUCSマップコンテキストの参照カウントを一つ減らします。 その結果、カウントが 0 になれば、コンテキストを削除し、アロケートされた メモリを解放します。

idn_ucsmap_incrref

void
idn_ucsmap_incrref(idn_ucsmap_t ctx)

idn_ucsmap_create で 作成したUCSマップコンテキストの参照カウントを一つ増やします。

idn_ucsmap_add

void
idn_ucsmap_add(idn_ucsmap_t ctx, unsigned long v, unsigned long *map,
        size_t maplen)

idn_ucsmap_create で 作成したコンテキストに Unicode コードポイントvのマッピング 規則を登録します。 マップ後のシーケンスを mapmaplenで指定します。 ただし、idn_ucsmap_fixを を呼ぶ前でないと、マッピング規則を登録することはできません。 idn_ucsmap_fixを既に呼んだ状態でこの関数を呼ぶと、 idn_failureを返します。

返される値は idn_successidn_nomemoryidn_failure のいずれかです。

idn_ucsmap_fix

void
idn_ucsmap_fix(idn_ucsmap_t ctx)

コンテキスト内に格納されいてるデータの配置を、最適化します。 この関数を利用すると、それ以降は idn_ucsmap_add によるマッピング規則の登録はできなくなります。

逆に、この関数を呼ばないと idn_ucsmap_map による文字のマッピングは行えません。

idn_ucsmap_map

idn_result_t
idn_ucsmap_map(idn_ucsmap_t ctx, unsigned long v, unsigned long *to,
        size_t tolen, size_t *maplenp);

Unicode のコードポイント v のマップ結果の UCS4 文字列を to に格納します。領域toの大きさをtolenで渡し、 実際のマップ後のシーケンスの長さはmaplenp に格納されます。

この関数を利用するには、あらかじめ idn_ucsmap_fix を 呼んでおかなければなりません。 idn_ucsmap_fix が呼ばれていない状態でこの関数を呼ぶと、 idn_failure を返します。

返される値は idn_successidn_nomappingidn_failure のいずれかです。


ucssetモジュール

ucssetモジュールは、文字の登録を行うためのモジュールです。

このモジュールは、 filecheckerモジュールおよび delimitermapモジュール の下位モジュールとして実装されています。

以下にモジュールの提供するAPI関数を示します。

idn__ucsset_create

idn_result_t
idn_ucsset_create(idn_ucsset_t *ctxp)

UCSセットコンテキストを一つ作成します。 作成したばかりのコンテキストには、文字は一つも登録されていません。

返される値は idn_successidn_nomemory のいずれかです。

idn_ucsset_destroy

void
idn_ucsset_destroy(idn_ucsset_t ctx)

idn_ucsset_create で 作成したUCSマップコンテキストの参照カウントを一つ減らします。 その結果、カウントが 0 になれば、コンテキストを削除し、アロケートされた メモリを解放します。

idn_ucsset_incrref

void
idn_ucsset_incrref(idn_ucsset_t ctx)

idn_ucsset_create で 作成したUCSマップコンテキストの参照カウントを一つ増やします。

idn_ucsset_add

void
idn_ucsset_add(idn_ucsset_t ctx, unsigned long v)

idn_ucsset_create で 作成したコンテキストに Unicode コードポイントvを登録します。 ただし、idn_ucsset_fixを を呼ぶ前でないと、文字を登録することはできません。 idn_ucsset_fixを既に呼んだ状態でこの関数を呼ぶと、 idn_failureを返します。

返される値は idn_successidn_invalid_codeidn_nomemoryidn_failure のいずれかです。

idn_ucsset_addrange

void
idn_ucsset_addrange(idn_ucsset_t ctx, unsigned long from, unsigned long to)

idn_ucsset_create で 作成したコンテキストに、fromからtoまでの Unicodeコードポイント(両端を含む) をすべて登録します。 ただし、idn_ucsset_fixを 呼ぶ前でないと、文字を登録することはできません。 idn_ucsset_fixを既に呼んだ状態でこの関数を呼ぶと、 idn_failureを返します。

返される値は idn_successidn_invalid_code idn_nomemoryidn_failure のいずれかです。

idn_ucsset_fix

void
idn_ucsset_fix(idn_ucsset_t ctx)

コンテキスト内に格納されいてるデータの配置を、最適化します。 この関数を利用すると、それ以降は idn_ucsset_addおよび idn_ucsset_addrange による文字の登録はできなくなります。

逆に、この関数を呼ばないと idn_ucsset_lookup による文字の判定は行えません。

idn_ucsset_lookup

idn_result_t
idn_ucsset_lookup(idn_ucsset_t ctx, unsigned long v, int *found)

Unicode のコードポイント vctx に含まれて いるかどうかを検査します。 含まれていれば *foundに1を、含まれていなければ0を格納し ます。

この関数を利用するには、あらかじめ idn_ucsset_fix を 呼んでおかなければなりません。 idn_ucsset_fix が呼ばれていない状態でこの関数を呼ぶと、 idn_failure を返します。

返される値は idn_successidn_nomemoryidn_failure のいずれかです。


unicodeモジュール

unicodeモジュールは、 UnicodeData.txt に記述されている、Unicode の各種文字属性を取得するモジュールです。なお、 Unicode.txt に記述されているデータの意味、およびファイル形式については UnicodeData File Formatをご覧ください。

本ライブラリの多くのモジュールは Unicode のデータを UCS4エンコードされた 文字列形式で扱いますが、このモジュールは UCS4 エンコード文字を unsigned long 型のデータとして扱います。

Unicode で定義されている文字属性などのデータには、いくつかのバージョンが 存在し、それぞれ少しずつ異なります。したがって特定のバージョンを 用いてデータを取得することができるように、本モジュールの提供する API 関数 にはバージョンを指定するためのキーを引数として指定するようになっています。 このキーの型は idn__unicode_version_t 型であり、 次のような opaque 型として定義されています。

typedef struct idn__unicode_ops *idn__unicode_version_t;

このモジュールでは Unicode 文字の大文字小文字の相互変換機能も 提供しています。 これは Unicode Technical Report #21: Case Mappings で 定義されているものです。 Unicode 文字の中にはごく一部ですが大文字小文字の変換をする際に 文脈情報を必要とするものがあり、これは次のような列挙型のデータで指定します。

typedef enum {
        idn__unicode_context_unknown,
        idn__unicode_context_final,
        idn__unicode_context_nonfinal
} idn__unicode_context_t;

文脈が FINAL の場合には idn__unicode_context_final を、また NON_FINAL の場合には idn__unicode_context_nonfinal を指定します。 idn__unicode_context_unknown は文脈情報がわからない (調べていない) ことを示します。 文脈情報に関して詳しくは上記文献をご覧ください。

以下にモジュールの提供するAPI関数を示します。

idn__unicode_create

idn_result_t
idn__unicode_create(const char *version, idn__unicode_version_t *versionp)

version で指定されるバージョンに対応するキーを作成し、 versionp の指す領域に格納します。 version には例えば "3.0.1" のように、バージョンを 示す文字列を指定します。 もし NULL を指定した場合には、 本モジュールがサポートしている中で最新のバージョンに対応するキーを 作成します。

返される値は idn_successidn_notfound (指定されたバージョンをサポートしていない場合) のいずれかです。

idn__unicode_destroy

void
idn__unicode_destroy(idn__unicode_version_t version)

idn__unicode_create で 作成したキー version を削除します。

idn__unicode_canonicalclass

int
idn__unicode_canonicalclass(idn__unicode_version_t version,
        unsigned long c);

version で指定されるバージョンの文字属性データを使用して、 Unicode 文字 cCanonical Combining Class を 求めます。 Canonical Combining Class が定義されていない文字については 0 を返します。 ただし versionidn__unicode_create で 作成したキーです。

idn__unicode_decompose

idn_result_t
idn__unicode_decompose(idn__unicode_version_t version,
        int compat, unsigned long *v, size_t vlen,
        unsigned long c, int *decomp_lenp)

Unicode 文字 cversion で指定されるバージョンの Unicode 文字属性データの CharacterDecomposition Mapping にしたがって decompose し、その結果を v および vlen で指定される領域に書き込みます。 compat の値が真なら Compatibility Decomposition を、 偽ならCanonical Decomposition を行います。 ただし versionidn__unicode_create で 作成したキーです。

decompose は再帰的に行われます。つまりCharacter Decomposition Mapping にしたがって分解した各文字についてさらに decompose 処理が行われます。

返される値は idn_successidn_notfoundidn_nomemory のいずれかです。

idn__unicode_compose

idn_result_t
idn__unicode_compose(idn__unicode_version_t version,
        unsigned long c1, unsigned long c2, unsigned long *compp)

c1c2 の2文字の Unicode 文字のシーケンスを version で指定されるバージョンの Unicode 文字属性データの Character Decomposition Mapping にしたがって compose し、その結果を compp の指す領域に書き込みます。 必ず Canonical Composition が行われます。 ただし versionidn__unicode_create で 作成したキーです。

返される値は idn_successidn_notfound のいずれかです。

idn__unicode_iscompositecandidate

int
idn__unicode_iscompositecandidate(idn__unicode_version_t version,
        unsigned long c)

version で指定されるバージョンの Unicode 文字属性データを用いて、 Unicode文字 c から始まる Canonical Composition が存在するか どうかを調べ、存在する可能性があれば 1 を可能性がなければ 0 を返します。 これはヒント情報であり、1が返ってきたとしても実際には Composition が 存在しないこともあり得ます。逆に 0 が返ってくれば確実に存在しません。 ただし versionidn__unicode_create で 作成したキーです。

Unicode の全文字の中で Canonical Composition の先頭となる文字は数少ないので、 idn__unicode_compose の 検索のオーバヘッドを減らすためにあらかじめデータをスクリーニングする目的に 使用することができます。


unormalizeモジュール

unormalizeモジュールは、Unicode で定義されている標準の正規化を 行うモジュールです。Unicode の正規化は Unicode Technical Report #15: Unicode Normalization Forms で定義されています。本モジュールはこの文書にあげられた4つの正規化形式を 実装しています。

正規化に用いる具体的なデータは、Unicode のバージョンによってそれぞれ 少しずつ異なります。そこで 本モジュールの提供する API 関数は unicodeモジュールのものと同様に バージョンを指定するためのキーを引数として指定するようになっています。 キーの作成および削除には、それぞれunicodeモジュールの idn__unicode_create および idn__unicode_destroy を 使用します。

以下にモジュールの提供するAPI関数を示します。

idn__unormalize_formc

idn_result_t
idn__unormalize_formc(idn__unicode_version_t version,
        const char *from, char *to, size_t tolen)

UCS4でエンコードされた文字列 from に対して version で指定されるバージョンの 正規化 Unicode Normalization Form C を適用し、その結果を to および tolen で指定される領域に書き込みます。

返される値は idn_successidn_buffer_overflowidn_nomemory のいずれかです。

idn__unormalize_formkc

idn_result_t
idn__unormalize_formkc(idn__unicode_version_t version,
        const char *from, char *to, size_t tolen)

UCS4でエンコードされた文字列 from に対して version で指定されるバージョンの 正規化 Unicode Normalization Form KC を適用し、その結果を to および tolen で指定される領域に書き込みます。

返される値は idn_successidn_buffer_overflowidn_nomemory のいずれかです。


utf8モジュール

utf8モジュールはUTF-8でエンコードされた文字列の基本処理を行う モジュールです。

以下にモジュールの提供するAPI関数を示します。

idn_utf8_mblen

int
idn_utf8_mblen(const char *s)

UTF-8 文字列 s の先頭文字の長さ(バイト数)を返します。 もし s が指すバイトが UTF-8 の先頭バイトとして正しくないものである 場合には 0 を返します。

この関数は s の先頭バイトのみを調べて長さを返します。したがって 2バイト目以降に不正なバイトがある可能性が存在します。特に途中に NUL バイトが ある可能性もあるので、s が正当な UTF-8 文字列であることが確実では ない場合には気をつける必要があります。

idn_utf8_getmb

int
idn_utf8_getmb(const char *s, size_t len, char *buf)

長さ len バイトの UTF-8 文字列 s の先頭の1文字を buf にコピーし、コピーしたバイト数を返します。 もし len が短すぎたり、s が指す文字が UTF-8 として 正しくない場合にはコピーは行わず、0 を返します。

buf は任意の UTF-8 エンコーディングの文字が保持できる大きさ でなければなりません。すなわち、6バイト以上の長さを持っている必要があります。

書き込んだUTF-8文字列は NUL 文字で終端されていません

idn_utf8_getwc

int
idn_utf8_getwc(const char *s, size_t len,
        unsigned long *vp)

idn_utf8_getmb とほぼ同じですが、 s から取り出した文字を UCS-4に変換して vp の指す領域に格納するところが異なります。

idn_utf8_putwc

int
idn_utf8_putwc(char *s, size_t len, unsigned long v)

UCS-4 文字 v を UTF-8 エンコーディングに変換して、 s および len で指定される領域に書き込むとともに、 書き込んだバイト数を返します。v の値が不正であったり len が短すぎた場合には 0 を返します。

書き込んだUTF-8文字列は NUL 文字で終端されていません

idn_utf8_isvalidchar

int
idn_utf8_isvalidchar(const char *s)

UTF-8 文字列 s の先頭の1文字が正しい UTF-8 エンコーディング であるかどうか調べ、正しければその文字の大きさをバイト数で返し、 正しくなければ 0 を返します。

idn_utf8_isvalidstring

int
idn_utf8_isvalidstring(const char *s)

NUL 文字で終端された文字列 s が正しい UTF-8 エンコーディング であるかどうか調べ、正しければ 1 を、正しくなければ 0 を返します。

idn_utf8_findfirstbyte

char *
idn_utf8_findfirstbyte(const char *s,
        const char *known_top)

文字列 known_top 中の s が指すバイトを含む UTF-8 文字の先頭バイトを調べて返します。その文字が正しい UTF-8 エンコーディングではない場合、known_top から s までの 間に先頭バイトがなかった場合には NULL を返します。


utilモジュール

utilモジュールは他のモジュールで使われるユーティリティー的な 機能を提供するモジュールです。

以下にモジュールの提供するAPI関数を示します。

idn__util_asciihaveaceprefix

int
idn__util_asciihaveaceprefix(const char *str, const char *prefix)

ASCII 文字列 str が指定された ACE プレフィクス prefix で始まっているかどうかを 調べます。返り値が 1 ならば ACE プレフィクスで始まっていて、 0 ならそうではありません。

idn__util_ucs4haveaceprefix

int
idn__util_ucs4haveaceprefix(const unsigned long *str, const char *prefix)

UCS4 の文字列 str が指定された ACE プレフィクス prefix で始まっているかどうかを 調べます。返り値が 1 ならば ACE プレフィクスで始まっていて、 0 ならそうではありません。

idn__util_ucs4isasciirange

int
idn__util_ucs4isasciirange(const unsigned long *str)

UCS4 の文字列 str が ASCII 領域内の文字 (U+0000 ~ U+007F) だけで構成されているかどうかを調べます。 返り値が 1 ならば ASCII 文字列であり、0 ならばそうではありません。


versionモジュール

versionモジュールは、idnkit ライブラリのバージョンに関する 機能を提供します。

以下にモジュールの提供するAPI関数を示します。

idn_version_getstring

const char *
idn_version_getstring(void);

idnkit ライブラリのバージョン番号を表現した文字列を返します。

このページを評価してください

このWebページは役に立ちましたか?
ページの改良点等がございましたら自由にご記入ください。

このフォームをご利用した場合、ご連絡先の記入がないと、 回答を差し上げられません。 回答が必要な場合は、お問い合わせ先をご利用ください。

ロゴ:JPNIC

Copyright© 1996-2019 Japan Network Information Center. All Rights Reserved.