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_success、 idn_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_create の name 引数に指定することができます。

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

返される値は idn_success、 idn_nomemory のいずれかです。

`idn__aliaslist_find`

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

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

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

返される値は idn_success、 idn_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_encodename、 idn_decodename もしくは idn_decodename2 が呼び出されたときは、エンコード、デコードの処理に先だって自動的に idn_nameinit(0) による初期化が行われます。

返される値は idn_success、 idn_nofile、 idn_invalid_syntax、 idn_invalid_name、 idn_nomemory のいずれかです。

`idn_encodename`

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

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

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_NAMEPREP、 IDN_ENCODE_APP、IDN_ENCODE_QUERY、 IDN_ENCODE_STORED というフラグも用意されています。

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

IDN_MAP | IDN_NORMALIZE | IDN_PROHCHECK | IDN_BIDICHECK

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

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

IDN_ENCODE_QUERY と IDN_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_success、 idn_invalid_encoding、 idn_invalid_length、 idn_invalid_syntax、 idn_invalid_name、 idn_invalid_action、 idn_buffer_overflow、 idn_nomemory、 idn_nofile、 idn_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 を変換し、結果を to と tolen で指定される領域に書き込みます。

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_NAMEPREP、 IDN_ENCODE_APP、IDN_ENCODE_QUERY、 IDN_ENCODE_STORED というフラグも用意されています。

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

IDN_MAP | IDN_NORMALIZE | IDN_PROHCHECK | IDN_BIDICHECK

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

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

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() と同じ処理を行います。

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

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

`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_success、 idn_nomemory のいずれかです。

`idn_checker_create`

idn_result_t
idn_checker_create(idn_checker_t *ctxp)

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

返される値は idn_success、 idn_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_success、 idn_invalid_name、 idn_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 でエンコードされたラベル ucs4 を ctx に指定された検査方式で検査します。ラベルが禁止文字、未割り当てコードポイントを含んでいた場合、 foundにその先頭位置を格納します。含まれていない場合は、NULLを返します。

返される値は idn_success、 idn_nomemory、 idn_buffer_overflow、 idn_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_add、 idn_checker_addall でコンテキストに検査方式を追加する際には、この名称で検査方法を指定します。

create、destroy、lookupには、それぞれ idn_checker_create、 idn_checker_destroy、 idn_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_success、 idn_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_success、 idn_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_success、 idn_invalid_name、 idn_nomemory、 idn_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 の文字列 from を idn_converter_create で指定したエンコーディングにコード変換し、結果を to に格納します。 tolen は to の長さです。また、変換は毎回初期状態から始まります。

返される値は idn_success、 idn_buffer_overflow、 idn_invalid_encoding、 idn_invalid_name、 idn_nomemory、 idn_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 に格納します。 tolen は to の長さです。また、変換は毎回初期状態から始まります。

返される値は idn_success、 idn_buffer_overflow、 idn_invalid_encoding、 idn_invalid_name、 idn_nomemory、 idn_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)

返される値は idn_failure、 idn_success、 idn_nomemory のいずれかです。

`idn_converter_aliasfile`

idn_result_t
idn_converter_aliasfile(const char *path)

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

返される値は idn_success、 idn_nofile、 idn_invalid_syntax、 idn_nomemory のいずれかです。

`idn_converter_resetalias`

idn_result_t
idn_converter_resetalias(void)

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

返される値は idn_success、 idn_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との間のエンコーディング変換機能を追加します。 openfromucs4、 opentoucs4、convfromucs4、 convtoucs4、 close は変換等の処理関数へのポインタです。 encoding_type にはこのローカルエンコーディングのタイプを指定します。エンコーディングタイプについては、 idn_converter_encodingtype を御覧ください。

返される値は idn_success、 idn_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_add、 idn_delimitermap_addall を用います。コンテキストで作成された時点では、コンテキストの参照カウントは 1 になっています。

返される値は idn_success、 idn_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_success、 idn_nomemory、 idn_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 でエンコードされた文字列 from に ctxによるマッピングを適用します。 idnkit ライブラリにデフォルトで登録されているデリミタと ctxに登録されているデリミタ (区切り文字) をピリオド (`.')にマッピングし、結果を to とtolen で指定される領域に書き込みます。

この関数から返される値は idn_success、 idn_buffer_overflow、 idn_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_success、 idn_nomemory、 idn_nofile、 idn_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 でエンコードされたラベル str を ctx に指定された検査方式で検査します。文字列が禁止文字、未割り当てコードポイントを含んでいた場合、 foundにその先頭位置を格納します。含まれていない場合は、NULLを返します。

返される値は idn_success、 idn_nomemory、 idn_buffer_overflow、 idn_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_success、 idn_nomemory、 idn_nofile、 idn_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 でエンコードされたラベル from に ctx で指定されるマッピングを適用し、その結果を to と tolen で指定される領域に書き込みます。

返される値は idn_success、 idn_nomemory、 idn_buffer_overflow、 idn_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 はハンドラ関数へのポインタです。もしハンドラを指定しない場合、あるいは proc にNULL を指定した場合には、ログは標準エラー出力に出力されます。

ハンドラの型 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_success、 idn_nomemory のいずれかです。

`idn_mapper_create`

idn_result_t
idn_mapper_create(idn_mapper_t *ctxp)

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

返される値は idn_success、 idn_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_success、 idn_nomemory、 idn_buffer_overflow、 idn_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 でエンコードされたラベル from に ctx で指定されるマッピング方式を適用し、その結果を to と tolen で指定される領域に書き込みます。 ctx に複数のマッピング方式が含まれている場合、それらが idn_mapper_add で追加した順番に適用されます。

返される値は idn_success、 idn_nomemory、 idn_buffer_overflow、 idn_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_add、 idn_mapper_addall でコンテキストにマッピング方式を登録する際に、この名称でマッピング方法を指定します。

create、destroy、mapには、それぞれ idn_mapper_create、 idn_mapper_destroy、 idn_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_success、 idn_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_success、 idn_nomemory のいずれかです。

`idn_mapselector_create`

idn_result_t
idn_mapselector_create(idn_mapselector_t *ctxp)

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

返される値は idn_success、 idn_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_success、 idn_nomemory、 idn_buffer_overflow、 idn_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 で指定されたマッピング方式を適用し、結果は to と tolen で指定される領域に書き込みます。 ctx に、そのトップレベルドメイン向けのマッピング方式が複数個含まれている場合、それらが idn_mapselector_add で追加した順番に適用されます。

返される値は idn_success、 idn_nomemory、 idn_buffer_overflow、 idn_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_success、 idn_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 でエンコードされたラベル from に handle で指定されるマッピング方式を適用し、その結果を to と tolen で指定される領域に書き込みます。

返される値は idn_success、 idn_buffer_overflow、 idn_invalid_encoding のいずれかです。

`idn_nameprep_isprohibited`

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

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

返される値は idn_success、 idn_invalid_encoding のいずれかです。

`idn_nameprep_isunassigned`

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

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

返される値は idn_success、 idn_invalid_encoding のいずれかです。

`idn_nameprep_isvalidbidi`

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

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

返される値は idn_success、 idn_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_success、 idn_nomemory のいずれかです。

`idn_normalizer_create`

idn_result_t
idn_normalizer_create(idn_normalizer_t *ctxp)

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

返される値は idn_success、 idn_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_success、 idn_invalid_name、 idn_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 でエンコードされたラベル from に ctx で指定される正規化方式を適用し、その結果を to と tolen で指定される領域に書き込みます。 ctx に複数の正規化方式が含まれている場合、それらが idn_normalizer_add で追加した順番に適用されます。

返される値は idn_success、 idn_invalid_encoding、 idn_nomemory のいずれかです。

`idn_normalizer_register`

idn_result_t
idn_normalizer_register(const char *scheme_name,
        idn_normalizer_proc_t proc)

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

返される値は idn_success、 idn_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 を変換し、結果を to と tolen で指定される領域に書き込みます。

返される値は idn_success、 idn_buffer_overflow、 idn_invalid_encoding、 idn_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 を変換し、結果を to と tolen で指定される領域に書き込みます。

返される値は idn_success、 idn_buffer_overflow、 idn_invalid_encoding、 idn_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 を変換し、結果を to と tolen で指定される領域に書き込みます。

返される値は idn_success、 idn_buffer_overflow、 idn_invalid_encoding、 idn_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 を変換し、結果を to と tolen で指定される領域に書き込みます。

返される値は idn_success、 idn_buffer_overflow、 idn_invalid_encoding、 idn_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_NAMEPREP、 IDN_ENCODE_APP、IDN_ENCODE_QUERY、 IDN_ENCODE_STORED というフラグも用意されています。

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

IDN_MAP | IDN_NORMALIZE | IDN_PROHCHECK | IDN_BIDICHECK

IDN_ENCODE_QUERY と IDN_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 を指定した場合は)、文字列は単にコピーされます。

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 を変換し、結果を to と tolen で指定される領域に書き込みます。変換や検査は、設定コンテキスト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_NAMEPREP、 IDN_ENCODE_APP、IDN_ENCODE_QUERY、 IDN_ENCODE_STORED というフラグも用意されています。

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

IDN_MAP | IDN_NORMALIZE | IDN_PROHCHECK | IDN_BIDICHECK

IDN_ENCODE_QUERY と IDN_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 を行いません。)

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() と同じ処理を行います。

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

`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_success、 idn_nomemory のいずれかです。

`idn_resconf_create`

idn_result_t
idn_resconf_create(idn_resconf_t *ctxp)

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

返される値は idn_success、 idn_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 に格納します。

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

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

返される値は idn_success、 idn_nofile、 idn_invalid_syntax、 idn_invalid_name、 idn_nomemory のいずれかです。

`idn_resconf_setdefaults`

idn_result_t
idn_resconf_setdefaults(idn_resconf_t ctx)

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

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

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

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

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

返される値は idn_success、 idn_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_mapper に NULL を渡した場合、デリミタは未指定の状態となります。

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

`idn_resconf_setidnconverter`

idn_result_t
idn_resconf_setidnconverter(idn_resconf_t ctx,
        idn_converter_t idn_converter)

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

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

`idn_resconf_setlocalconverter`

idn_result_t
idn_resconf_setlocalconverter(idn_resconf_t ctx,
        idn_converter_t local_converter)

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

反対に 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_selector に NULL を渡した場合、マッピング方式は未指定の状態となります。

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

`idn_resconf_setmapper`

idn_result_t
idn_resconf_setmapper(idn_resconf_t ctx, idn_mapper_t mapper)

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

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

`idn_resconf_setnormalizer`

idn_result_t
idn_resconf_setnormalizer(idn_resconf_t ctx,
        idn_normalizer_t normalizer)

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

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

`idn_resconf_setprohibitchecker`

idn_result_t
idn_resconf_setprohibitchecker(idn_resconf_t ctx,
        idn_checker_t prohibit_checker)

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

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

`idn_resconf_setunassignedchecker`

idn_result_t
idn_resconf_setunassignedchecker(idn_resconf_t ctx,
        idn_checker_t unassigned_checker)

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

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

`idn_resconf_setbidichecker`

idn_result_t
idn_resconf_setbidichecker(idn_resconf_t ctx,
        idn_checker_t bidi_checker)

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

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

`idn_resconf_setidnconvertername`

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

IDN エンコーディングを設定コンテキストctxにセットします。 idn_converter に NULL を渡した場合、 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 に対するローカルなマッピング方式として、 namesとnnamesに記されたものをすべて設定コンテキストctxに追加します。

`idn_resconf_addallmappernames`

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

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

`idn_resconf_addallnormalizernames`

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

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

`idn_resconf_addallprohibitcheckernames`

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

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

`idn_resconf_addallunassignedcheckernames`

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

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

`idn_resconf_addallbidicheckernames`

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

namesとnnamesに記された双方向文字列の検査方式をすべて設定コンテキスト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_success、 idn_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_success、 idn_nomemory のいずれかです。

`idn__strhash_get`

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

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

返される値は idn_success、 idn_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 を変換し、結果を utf16 と tolen で指定される領域に書き込みます。

返される値は idn_success、 idn_buffer_overflow、 idn_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 を変換し、結果を ucs4 と tolen で指定される領域に書き込みます。

返される値は idn_success、 idn_buffer_overflow、 idn_invalid_encoding のいずれかです。

`idn_ucs4_utf8toucs4`

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

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

返される値は idn_success、 idn_buffer_overflow、 idn_invalid_encoding のいずれかです。

`idn_ucs4_ucs4toutf8`

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

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

返される値は idn_success、 idn_buffer_overflow、 idn_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 文字列 from を to にコピーします。

`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 の文字列である str1 と str2 を比較します。 str1 が str2 に較べて

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

返します。

`idn_ucs4_strcasecmp`

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

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

str1 が str2 に較べて

小さい場合は 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_success、 idn_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のマッピング規則を登録します。マップ後のシーケンスを map、 maplenで指定します。ただし、 idn_ucsmap_fix を呼ぶ前でないと、マッピング規則を登録することはできません。 idn_ucsmap_fixを既に呼んだ状態でこの関数を呼ぶと、 idn_failureを返します。

返される値は idn_success、 idn_nomemory、 idn_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_success、 idn_nomapping、 idn_failure のいずれかです。

`ucsset`モジュール

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

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

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

`idn__ucsset_create`

idn_result_t
idn_ucsset_create(idn_ucsset_t *ctxp)

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

返される値は idn_success、 idn_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_success、 idn_invalid_code、 idn_nomemory、 idn_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_success、 idn_invalid_code idn_nomemory、 idn_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 のコードポイント v が ctx に含まれているかどうかを検査します。含まれていれば *foundに1を、含まれていなければ0を格納します。

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

返される値は idn_success、 idn_nomemory、 idn_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_success、 idn_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 文字 c の Canonical Combining Class を求めます。 Canonical Combining Class が定義されていない文字については 0 を返します。ただし version は idn__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 文字 c を version で指定されるバージョンの Unicode 文字属性データの CharacterDecomposition Mapping にしたがって decompose し、その結果を v および vlen で指定される領域に書き込みます。 compat の値が真なら Compatibility Decomposition を、偽ならCanonical Decomposition を行います。ただし version は idn__unicode_create で作成したキーです。

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

返される値は idn_success、 idn_notfound、 idn_nomemory のいずれかです。

`idn__unicode_compose`

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

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

返される値は idn_success、 idn_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 が返ってくれば確実に存在しません。ただし version は idn__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_success、 idn_buffer_overflow、 idn_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_success、 idn_buffer_overflow、 idn_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 ライブラリのバージョン番号を表現した文字列を返します。

idnkit ライブラリ の仕様書

idnkit ライブラリの仕様書