MDN libarary specification

# MDN Library

- 機能概要
- Function Overview
- モジュール一覧
- Module List
- モジュール詳細
- Details of Modules

## 機能概要

## Function Overview

MDN ライブラリ (libmdn) は多言語ドメイン名の変換に関わる各種の処理を 実装するモジュールの集合です。このライブラリは以下のような機能を 提供します。
The MDN library (libmdn) is a group of modules that provide various processing with respect to multilingual domain name conversion. This library provides the following features.

- エンコーディング (コードセット) 変換
  Encoding (code set) conversion
- 文字列の正規化
  Normalization of character strings
- DNS メッセージの解析、再組み立て
  Analysis and reassembly of DNS messages
- ZLD (Zero Level Domain) のマッチング、削除、追加
  Matching, removal and addition of ZLD (Zero Level Domain)
- ローカルエンコーディングの判別
  Local encoding identification
- クライアント用設定ファイルの読み込み
  Loading of client configuration files

  ### エンコーディング (コードセット) 変換

  ### Encoding (code set) conversion

  文字列のエンコーディングを変換し、その結果を返します。 MDN ライブラリの内部では、文字列はすべて UTF-8 エンコーディングであるとして 取り扱われます。そこで、このモジュールは
  Converts character string encoding and returns the result. Inside the MDN library, character strings are all handled as UTF-8 encoding. This module supports the following conversions.

  - あるエンコーディングから UTF-8 への変換
    Conversion from certain encoding methods to UTF-8
  - UTF-8 からあるエンコーディングへの変換
    Conversion from UTF-8 to certain encoding methods
  をサポートします。

エンコーディングは大きく分けて、次の2種類があります。
Encoding is roughly divided into the following two types.

- アプリケーションが使用するエンコーディング (シフトJIS、EUC 等)
  Encoding used by applications (shift JIS, EUC, etc.)
- 多言語ドメイン名で使用するためにデザインされた特別なエンコーディング (UTF-5、RACE 等)
  Special encoding designed to be used for multilingual domain names (UTF-5、RACE etc.)

このモジュールでは前者のエンコーディング変換のために iconv() ユーティリティを使用し、後者のエンコーディング変換のためには 独自の変換関数を実装して使用しています。
This module uses the iconv() utility for the first encoding conversion process and implements a unique conversion function for the latter encoding conversion.

### 文字列の正規化

### Normalization of character strings

与えられた文字列を正規化します。標準では次にあげる正規化をサポートします。
Normalizes given character strings. The following standard normalization functions are supported.

- ASCII の小文字→大文字変換
  Converts lowercase ASCII to uppercase ASCII
- ASCII の大文字→小文字変換
  Converts uppercase ASCII to lowercase ASCII
- UnicodeData.txt に従った小文字→大文字変換
  Converts lowercase to uppercase as specified in UnicodeData.txt
- UnicodeData.txt に従った大文字→小文字変換
  Converts uppercase to lowercase as specified in UnicodeData.txt
- Unicode Normalization Form C
  Unicode Normalization Form C
- Unicode Normalization Form KC
  Unicode Normalization Form KC
- 日本語の半角かな→全角カタカナ変換
  Converts single-byte Japanese katakana to double-byte katakana
- 全角マイナス記号→半角ハイフン変換
  Converts double-byte minus symbols to single-byte hyphens
- 句点(。)、全角ピリオド(．)→ピリオド(.)変換
  Converts Japanese periods (。) and double-byte periods (．) to periods (.)

### DNS メッセージの解析、再組み立て
Analysis and assembly of DNS messages

DNS プロキシサーバ (dnsproxy) では、クライアントから送られてきた DNS メッセージに含まれるドメイン名に対してエンコーディング変換や正規化を行い、 その結果を DNS サーバに送ります。このために以下の機能を提供します。
In the DNS proxy server (dnsproxy), encoded domain names included in DNS messages sent from the client are converted and normalized and the result is sent to the DNS server. This process is comprised of the following functions:

- DNSメッセージを解析し、ドメイン名を取り出す
  Analyzes DNS messages and extracts domain names
- 変換したドメイン名を用いてDNSメッセージを再構成する
  Re-constructs DNS messages using converted domain names

### ZLD (Zero Level Domain) のマッチング、削除、追加
Matching, removal and addition of ZLD (Zero Level Domain)

多言語ドメイン名を識別するために ZLD を必要とする方式のために、ZLD に 関する以下の機能を提供します。
To identify multilingual domain names, the following ZLD-related functions are provided:

- 複数の ZLD の中から、ドメイン名にマッチするものを探す
  Of the multiple number of ZLDs, finds the one that matches the domain name
- ドメイン名から ZLD 部分を削除する
  Removes the ZLD portion from the domain name
- ドメイン名に ZLD を追加する
  Adds ZLD to the domain name

### ローカルエンコーディングの判別
Local encoding identification

アプリケーションプログラムが使用しているローカルエンコーディング (コードセット) を自動判別します。判別は基本的にはアプリケーションのロケール 情報を利用しますが、環境変数で指定することも可能になっています。
Automatically identifies the local encoding (code set) used by the application program. Basically, the application locale information is used, though the local encoding (code set) can also be specified using an environmental variable.

### クライアント用設定ファイルの読み込み
Loading of client configuration file

アプリケーションにリンクされるリゾルバライブラリでエンコーディング 変換や正規化を行う場合、使用するエンコーディングや正規化方式は 設定ファイルに記述されます。このファイルを読み込む機能を提供します。
When the resolver library linked by the application is used to perform conversion or normalization, the encoding and normalization method to be used is described in the configuration file. A function is provided to load this file.

## モジュール一覧
Module list

MDN ライブラリは以下のモジュールから構成されます。
The MDN library consists of the following modules.

brace モジュール
brace module
  ドメイン名のエンコーディング方式の一つとして提案されている BRACE エンコーディングの変換モジュール
  Conversion module for the proposed BRACE encoding domain name encoding method
converter module
  文字列のエンコーディング(コードセット)の変換モジュール
  Conversion module for character string encoding (code set)
debug module
  デバッグ用出力のためのユーティリティモジュール
  Utility module for debug output
dn module
  DNS メッセージ内のドメイン名の展開・圧縮を行うモジュール
  Extraction/compression module for domain names inside DNS messages
lace module
  ドメイン名のエンコーディング方式の一つとして提案されている LACE エンコーディングの変換モジュール
  Conversion module for the proposed LACE encoding domain name encoding method
localencoding module
  アプリケーションの使用しているエンコーディングを推測するモジュール
  Guesses which encoding is used by the application
log module
  MDN ライブラリのログの出力処理を制御するモジュール
  Controls MDN library log output processing
msgheader module
  DNS メッセージのヘッダの解析モジュール
  Analyzes the header of the DNS message
msgtrans module
  DNS プロキシサーバでの DNS メッセージの変換を行うためのモジュール
  Converts the DNS message at the DNS proxy server
normalizer module
  文字列の正規化を行うモジュール
  Normalizes character strings
race module
  ドメイン名のエンコーディング方式の一つとして提案されている RACE エンコーディングの変換モジュール
  Conversion module for proposed RACE domain name encoding method
res module
  リゾルバライブラリ、あるいはアプリケーションでドメイン名の エンコーディング変換や正規化を行うためのインタフェースを提供するモジュール
  Provides an interface to perform encoding conversion or normalization of domain names by the resolver library or application
resconf module
  リゾルバライブラリ、あるいはアプリケーションでドメイン名の エンコーディング変換や正規化を行う際の設定ファイルを読み込むためのモジュール
  Loads the configuration file used by the resolver library or application during encoding conversion and normalization of domain names
result module
  ライブラリの各関数が返すリザルトコードを扱うモジュール
  Handles the result code returned by each library function
selectiveencode module
  テキストの中から非ASCII文字を含むドメイン名を探し出すモジュール
  Finds domain names that include non-ASCII characters
strhash module
  文字列をキーとするハッシュ表を実現するモジュール
  Implements a hash table that uses character strings as keys
translator module
  与えられたパラメータに従ってドメイン名を変換するモジュール
  Converts domain name according to the specified parameters
unicode module
  Unicode の各種文字属性を取得するモジュール
  Obtains various Unicode character properties
unormalize module
  Unicode で定義されている標準の正規化を行うモジュール
  Performs standard normalization defined by Unicode
utf5 module
  ドメイン名のエンコーディング方式の一つとして提案されている UTF-5 の基本処理を行うモジュール
  Performs basic processing for the proposed UTF-5 domain name encoding method
utf8 module
  UTF-8 エンコーディング文字列の基本処理を行うモジュール
  Performs basic processing of UTF-8 encoding character strings
util module
  他のモジュールで使われる共用関数を提供するモジュール
  Provides common functions used by other modules
ZLDrule module
  ドメイン名と ZLD とのマッチングを行うモジュール
  Matches domain names and ZLD

以下にモジュールの呼び出し関係図を示します。ただしほとんどすべての モジュールから呼び出されている debug モジュールと log モジュール、また 共用関数を納めた util モジュールは割愛してあります。
The following diagram shows the invoking relationship of modules. debug and log modules called by most modules and util modules that store common functions are omitted in the diagram.

## モジュール詳細
Details of Modules

MDN ライブラリに含まれるすべてのモジュールについて、その仕様を記述 します。まず各モジュールで共通に使用される、関数のリターン値について 説明したあと、モジュール毎に詳細を解説します。
The specifications of all modules included in MDN library are explained below. First, return values of functions commonly used by the modules are explained and then each module is discussed in detail.

### API関数のリターン値
Values returned by API functions

MDNライブラリのほとんど全てのAPI関数は、リターン値として 列挙型であるmdn_result_t 型の値を返します。値の一覧とその意味を 示します。
Almost all API functions of the MDN library return values of mdn_result_t, which is an enumeration type value. The values and their meanings are explained below.

`mdn_success`
  処理が成功したことを示します。
  Processing was successful.
`mdn_notfound`
  検索処理などにおいて、見つからなかったことを示します。
  The target of search processing could not be found.
`mdn_invalid_encoding`
  エンコーディング変換において、入力された文字列のエンコーディングが間違っていることを示します。
  Incorrect conversion of encoded input character string.
`mdn_invalid_syntax`
  ファイルなどの書式に間違いがあることを示します。
  Incorrect file format.
`mdn_invalid_name`
  指定された名前が間違っていることを示します。
  Specified name is incorrect.
`mdn_invalid_message`
  入力されたDNSメッセージが正しくないことを示します。
  Entered DNS message is incorrect.
`mdn_buffer_overflow`
  結果を格納するバッファの大きさが足りないことを示します。
  Insufficient buffer to store result.
`mdn_noentry`
  指定された項目が存在しないことを示します。
  Specified item does not exist.
`mdn_nomemory`
  メモリのアロケーションに失敗したことを示します。
  Memory allocation failed.
`mdn_nofile`
  指定されたファイルが存在しないことを示します。
  Specified file does not exist.
`mdn_nomapping`
  文字列のエンコーディング(コードセット)を変換する際、変換ターゲットの文字集合に含まれない文字があった (つまり正しく変換できなかった) ことを示します。
  Conversion could not be performed correctly because a character in the encoded character string (code set) does not exist in the target conversion character set.
`mdn_context_required`
  文字の大文字小文字変換の際に、正しい変換を行うには文脈情報が必要であることを示します。
  Indicates that context information is required to correctly convert uppercase characters to lowercase characters.
`mdn_failure`
  上記のいずれにも当てはまらないエラーが発生したことを示します。
  Indicates that an error occurred that does not fall into any of the above categories.

### brace モジュール
brace module

brace モジュールは、多言語ドメイン名のエンコーディング方式の一つとして提案されているBRACE エンコーディングとUTF-8との間の変換を行うモジュールです。このモジュールはconverter モジュールの下位モジュールとして実装されており、アプリケーションがこのモジュールを直接呼び出すことはありません。converter モジュールに対して`BRACE` エンコーディングとの変換を要求すると、このモジュールが間接的に呼び出されることになります。
The brace module performs conversion between UTF-8 and the proposed BRACE encoding of multilingual domain names. This module is implemented as a low-order converter module, and is not directly called by the application. When converter module is requested in association with BRACE encoding conversion, this module is indirectly called.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn__brace_open

      mdn_result_t
      mdn__brace_open(mdn_converter_t ctx, mdn_converter_dir_t dir)

  BRACEエンコーディングとの変換をオープンします。実際には何もしません。
  Opens conversion context used for BRACE encoding. Actually, this does not do anything.

  常に `mdn_success`を返します。
  Always returns `mdn_success`.

mdn__brace_close

      mdn_result_t
      mdn__brace_close(mdn_converter_t ctx, mdn_converter_dir_t dir)

  BRACEエンコーディングとの変換をクローズします。実際には何もしません。
  Closes conversion context used for BRACE encoding. Actually, this does not do anything.

  常に `mdn_success`を返します。
  Always returns `mdn_success`.

mdn__brace_convert

      mdn_result_t
      mdn__brace_convert(mdn_converter_t ctx, mdn_converter_dir_t dir,
      	const char *from, char *to, size_t tolen)

  BRACEエンコードされた文字列とUTF-8エンコードされた文字列の相互変換を 行います。入力文字列 from を変換し、結果を to と tolen で指定される領域に書き込みます。dir が`mdn_converter_l2u`ならBRACEエンコーディングからUTF-8エンコーディングへ、`mdn_converter_u2l`ならUTF-8エンコーディングからBRACEエンコーディングへの変換となります。
  Performs bidirectional conversion of BRACE and UTF-8 encoded character strings. The from input character string is converted and the result is written in the area specified by to and tolen. When dir is `mdn_converter_l2u`, BRACE strings are converted to UTF-8 encoding and when dir is `mdn_converter_u2l`, UTF-8 strings are converted to BRACE encoding.

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_encoding`
  `mdn_nomemory`

### converter モジュール
converter module

converter モジュールは、文字列のエンコーディング(コードセット)を 変換します。MDN ライブラリは内部処理に UTF-8 エンコーディングの文字列を 使用するため、このモジュールはローカルエンコーディングと UTF-8 との 間の相互変換を行います。
converter module converts character string encoding (code set). Because the MDN library uses UTF-8 character strings for internal processing, this module performs bidirectional conversion between the local encoding method and UTF-8.

現在サポートされているエンコーディングは次の通りです
Support is currently provided for the following encoding methods.

- iconv() がサポートしているエンコーディング
  iconv() encoding support
  iconv() とは汎用的なコードセット変換機能を提供する関数で、 この関数がサポートするエンコーディングをサポートします。 iconv() がサポートするエンコーディングは実装依存なので、 具体的にどのエンコーディングが使用可能なのかは iconv() の ドキュメントをご覧ください。
  The iconv() function provides general code set conversion functions and encoding support. The encoding methods supported by iconv() are implementation-dependent; in that regard, refer to the documentation included with iconv() for information on which encoding is actually available.
- `UTF-5`
  多言語ドメイン名のエンコーディング方法として提案されているものです。 詳しくは draft-jseng-utf5-01.txt をご覧ください。
  Proposed multilingual domain name encoding method. For details, refer to draft-jseng-utf5-01.txt
- `RACE`
  これも多言語ドメイン名のエンコーディング方法として提案されているものです。 詳しくは draft-ietf-idn-race-02.txt をご覧ください。
  Proposed multilingual domain name encoding method. For details, refer to draft-ietf-idn-race-02.txt
- `BRACE`
  これも多言語ドメイン名のエンコーディング方法として提案されているものです。 詳しくは draft-ietf-idn-brace-00.txt をご覧ください。
  Proposed multilingual domain name encoding method. For details, refer to draft-ietf-idn-brace-00.txt
- `LACE`
  これも多言語ドメイン名のエンコーディング方法として提案されているものです。 詳しくは draft-ietf-idn-lace-00.txt をご覧ください。
  Proposed multilingual domain name encoding method. For details, refer to draft-ietf-idn-lace-00.txt

また、converter モジュールはドメイン名のエンコーディング変換のために 特別に設計されたもので、一般的なエンコーディング変換には必ずしも適しません。 例えば UTF-5、RACE、BRACE、LACE エンコーディングはドメイン名の 区切り文字であるピリオドを特別に扱います。
The converter module is specially designed for encoding conversion of domain names and is not suitable for general encoding conversion. For example, UTF-5, RACE, BRACE, and LACE encoding provide special handling of the delimiting periods used in domain names.

converter モジュールは「コード変換コンテキスト」という概念を用います。 あるエンコーディングと UTF-8 との相互変換を行うには、まず そのエンコーディングのコード変換コンテキストを作成します。実際の コード変換にはエンコーディングを直接指定するのではなく、この コード変換コンテキストを指定します。コード変換コンテキストの型は mdn_converter_t 型であり、次のような opaque 型として定義されています。
The converter module employs the "code conversion context" concept. When perform bidirectional conversion between a specific encoding method and UTF-8, first the code conversion context of that encoding is created. For actual code conversion, the encoding is not directly specified; instead this code conversion context is specified. The code conversion context is mdn_converter_t and is defined as the following opaque type.

>     typedef struct mdn_converter *mdn_converter_t;

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_converter_initialize

      mdn_result_t
      mdn_converter_initialize(void)

  モジュールの初期化処理を行います。本モジュールの他のAPI関数を呼ぶ前に 必ず呼び出してください。
  Initializes the module. This function is always called before calling other API functions of this module.

  返される値は`mdn_success`、`mdn_nomemory`のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

mdn_converter_create

      mdn_result_t
      mdn_converter_create(const char *name, mdn_converter_t *ctxp,
              int delayedopen)

  name で指定されるローカルエンコーディングと UTF-8 との間の コード変換コンテキストを作成、初期化し、ctxp の指す領域に 格納します。
  Creates the code conversion context used for conversion between the local encoding specified by name and UTF-8, then initializes and stores it in the area specified by ctxp.

  ローカルエンコーディングとして、現在のところ `UTF-5`、`RACE`、`BRACE`、`LACE` の変換機能が用意されています。これ以外のエンコーディングが指定された場合には、システムの提供するiconv() ユーティリティを用いて変換が行われます。 この場合、この関数の呼び出し時にiconv_open() の呼び出しが行われますが、 delayedopen が真ならば実際に文字列の変換が行われるまで iconv_open() の呼び出しが遅延されます。
  Currently provides `UTF-5`, `RACE`, `BRACE`, and `LACE` conversion functions. For encoding methods other than those listed above, conversion is performed using the iconv() utility provided with the system. In such a case, when this function is invoked iconv_open() is called. When delayedopen is true, calling of iconv_open() is delayed until the character string is actually converted.

  またmdn_converter_register を用いて新たなローカルエンコーディングを追加することも可能です。
  In addition, mdn_converter_register can be also used to add new local encoding methods.

  One of the following values is returned:
  `mdn_success`
  `mdn_invalid_name`
  `mdn_nomemory`
  `mdn_failure`

mdn_converter_destroy

      void
      mdn_converter_destroy(mdn_converter_t ctx)

  mdn_converter_create で 作成したコード変換コンテキストを削除し、確保したメモリを解放します。
  Deletes the code conversion context created by mdn_converter_create and releases the allocated memory.

mdn_converter_convert

      mdn_result_t
      mdn_converter_convert(mdn_converter_t ctx,
      	mdn_converter_dir_t dir, const char *from,
      	char *to, size_t tolen)

  mdn_converter_create で作成したコード変換コンテキストを用いて文字列 from をコード変換し、結果を to に格納します。tolen は to の長さです。 dir は変換の方向の指定で、
  Uses the code conversion context created by mdn_converter_create to perform code conversion of character strings and stores the result in to. tolen is the length of to. dir is used to specify the direction of conversion.

  - `mdn_converter_l2u`ならローカルエンコーディングから UTF-8 への変換
    `mdn_converter_l2u` specifies the conversion method used to convert from local encoding to UTF-8.
  - `mdn_converter_u2l`なら UTF-8 からローカルエンコーディングへの変換
    `mdn_converter_u2l` the conversion method used to convert from UTF-8 to the local encoding method.
  となります。

  `ISO-2022-JP`のように状態をもつエンコーディングを使用した場合、 iconv() と異なり、この関数の呼び出し間で状態は保存されません。 変換は毎回初期状態から始まります。
  Unlike iconv(), when status-dependent encoding such as `ISO-2022-JP` is used, the status that is in effect when the function is called the first time is not maintained when this function is called the next time. Conversion starts from the initial status each time.

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_encoding`
  `mdn_invalid_name`
  `mdn_nomemory`
  `mdn_failure`

mdn_converter_localencoding

      char *
      mdn_converter_localencoding(mdn_converter_t ctx)

  コード変換コンテキスト ctx のローカルエンコーディング名を 返します。
  Returns the local encoding name of the code conversion context ctx.

mdn_converter_isasciicompatible

      int
      mdn_converter_isasciicompatible(mdn_converter_t ctx)

  コード変換コンテキスト ctx のローカルエンコーディングが ASCII互換エンコーディングかどうかを返します。ASCII互換エンコーディングなら 0でない値が、そうでないなら1が返ります。
  Returns whether or not the local encoding of the code conversion context ctxis ASCII-compatible. When the local encoding method is ASCII-compatible encoding, a value other than 0 is returned and if not, 1 is returned.

  ASCII互換エンコーディング (ASCII-compatible Encoding) とは、そのエンコーディングでエンコードされたドメイン名が通常のASCIIのドメイン名と区別できない、つまり英数字およびハイフンのみで構成されるようなエンコーディングのことで、具体的には RACE などが相当します。これらのエンコーディングは一般にアプリケーションのローカルエンコーディングとして用いられることはありませんが、DNS プロトコル上でドメイン名を表すためのエンコーディングとしては(従来の DNS サーバ等がなんの変更もなしに使えることもあって) 有力視されているものです。
  ASCII-compatible encoding consists of only alphenumeric characters and hyphens, meaning it is not possible to differentiate between domain names encoded using this encoding and standard ASCII domain names. Specifically, RACE encoding is of this type. These types of encoding are not generally used for local encoding by applications but are strong candidates for the encoding used to express domain names in the DNS protocol (because conventional DNS servers can be used without modification).

mdn_converter_addalias

      mdn_result_t
      mdn_converter_addalias(const char *alias_name, const char *real_name)

  エンコーディング名 real_name に対して、alias_name という別名を登録します。登録した別名はmdn_converter_create のname 引数に指定することができます。
  Used to register the alias alias_name for the encoding name real_name . Registered aliases can be specified in the var>name argument of mdn_converter_create.

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

mdn_converter_aliasfile

      mdn_result_t
      mdn_converter_aliasfile(const char *path)

  ファイル path で指定されるファイルを読み込み、その内容に 従って別名を登録します。
  Loads the file specified by the path variable and registers the alias in accordance with the contents of the file.

  ファイル path は次のような単純な形式の行からなるテキストファイルです。
  The file path is a text file consisting of the following simple format.

          別名    正式名
          Alias   Formal name

  また `#`で始まる行はコメントとみなされます。
  In addition, comment lines begin with `#`.

  返される値は `mdn_success`、 `mdn_nofile`、 `mdn_invalid_syntax`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nofile`
  `mdn_invalid_syntax`
  `mdn_nomemory`

mdn_converter_resetalias

      mdn_result_t
      mdn_converter_resetalias(void)

  mdn_converter_addalias や mdn_converter_aliasfile で登録した別名をリセットし、別名が全く登録されていない初期状態に戻します。
  Resets aliases registered using mdn_converter_addalias or mdn_converter_aliasfile to the initial default status (where no aliases are registered).

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

mdn_converter_register

      mdn_result_t
      mdn_converter_register(const char *name,
      	mdn_converter_openproc_t open,
      	mdn_converter_closeproc_t close,
      	mdn_converter_convertproc_t convert,
      	int ascii_compatible)

  name という名前のローカルエンコーディングと UTF-8との 間のエンコーディング変換機能を追加します。open、close、 convert は変換等の処理関数へのポインタです。 ascii_compatible にはこのローカルエンコーディングが ASCII互換エンコーディングなら1を、そうでなければ0を指定します。
  Adds the encoding conversion function between the name local encoding method and UTF-8. open, close, and convert are used as pointers to processing functions such as conversion. 1 specifies ascii_compatible local encoding, 0 that local encoding is not ASCII compatible.

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success` and
  `mdn_nomemory`

### debug モジュール
debug module

debug モジュールはデバッグ用出力のためのユーティリティモジュールです。
The debug module is a utility module for debug output.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_debug_hexstring

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

  文字列 s を16進数表示した文字列を返します。 maxbytes は表示する最大の長さで、sが これを超えた場合には 最後に `...`が追加されます。
  Returns a hexidecimal character string of s length. maxbytes indicates the maximum length expressed and when s exceeds that length, `...` is appended to the string at that point.

  返される文字列のメモリ領域は本関数の保持するスタティック変数のもので、その内容は本関数の次の呼び出し時まで有効です。
  The memory area allocated for the returned character string is used for the static variable held by this function and is in effect until the function is called the next time.

mdn_debug_xstring

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

  文字列 s の中で、コードが128以上のものを`\x{HH}`形式で 表示した文字列を返します。 maxbytes は表示する最大の長さで、s がこれを超えた場合には 最後に `...`が追加されます。
  Of the s character strings, returns in `\x{HH}` format those character strings 128 bytes or larger. maxbytes indicates the maximum length expressed and when s exceeds this, `...` is appended to the string at that point.

  返される文字列のメモリ領域は本関数の保持するスタティック変数の もので、その内容は本関数の次の呼び出し時まで有効です。
  The memory area allocated for the returned character string is used for the static variable held by this function and is in effect until the function is called the next time.

mdn_debug_hexdata

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

  長さ length のバイト列 s を16進表示した文字列を返します。maxbytes は表示する最大のバイト長で、length がこれを超えた場合には最後に `...`が追加されます。
  Returns the length of byte row s in hexadecimal character strings. maxbytes indicates the maximum length expressed and when length exceeds this, `...` is appended to the string at that point.

  返される文字列のメモリ領域は本関数の保持するスタティック変数のもので、その内容は本関数の次の呼び出し時まで有効です。
  The memory area allocated for the returned character string is used for the static variable held by this function and is in effect until the function is called the next time.

mdn_debug_hexdump

      void
      mdn_debug_hexdump(const char *s, int length)

  長さ length のバイト列 s の16進ダンプを標準エラー出力に表示します。
  The standard error output is comprised of a hexidecimal dump of length of byte row s.

### dn モジュール dn module

dn モジュールは、DNS メッセージ内のドメイン名の展開・圧縮を行うモジュール です。これはリゾルバライブラリのres_comp およびres_expand に 相当する機能を提供します。
The dn module expands or compresses domain names in DNS messages. This provides the functional equivalent of res_comp and res_expand in the resolver library.

このモジュールは本ライブラリの他のモジュールからのみ利用されることを想定して 設計されています。
This module was designed under the assumption that it would only used by only other modules in the libary.

ドメイン名の圧縮の際は、次に示すmdn__dn_t 型のコンテキスト情報を 使用します。
When a domain name is compressed, context information of type mdn__dn_t is used, as shown below:

>     #define MDN_DN_NPTRS	64
>     typedef struct {
>     	const unsigned char *msg;
>     	int cur;
>     	int offset[MDN_DN_NPTRS];
>     } mdn__dn_t;

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn__dn_expand

      mdn_result_t
      mdn__dn_expand(const char *msg, size_t msglen,
      	const char *compressed, char *expanded,
      	size_t buflen, size_t *complenp)

  長さ msglen のDNSメッセージ msg 中の 圧縮されたドメイン名 compressed を展開し、 expanded に結果を格納します。 buflen は expanded の大きさです。 また、compressed の長さが *complenp に格納されます。
  Expands the compressed domain name in DNS message msg of length msglen and stores the result in expanded. buflen is the size of expanded. Also, the length of compressed is stored in *complenp.

  返される値は `mdn_success`、 `mdn_buffer_overflow`、 `mdn_invalid_message` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_message`

mdn__dn_initcompress

      void
      mdn__dn_initcompress(mdn__dn_t *ctx, const char *msg)

  ドメイン名圧縮用のコンテキスト情報 ctx を初期化します。 この関数はmdn__dn_compress を呼び出す前に必ず呼び出す必要があります。 msg は圧縮したドメイン名を格納するDNSメッセージの 先頭アドレスです。
  Initializes context information ctx for domain name compression. This function must be called before calling mdn__dn_compress. msg is the leading address in a DNS message where the compressed domain name is stored.

mdn__dn_compress

      mdn_result_t
      mdn__dn_compress(const char *name, char *sptr, size_t length,
      	mdn__dn_t *ctx, size_t *complenp)

  name の指すドメイン名を圧縮して sptr の指す 場所に格納します。length は sptr の空き領域の長さです。 圧縮の際は、ctx に入っている以前に圧縮したドメイン名の情報が 参照されます。圧縮したドメイン名の長さが complenp に入れられるとともに、圧縮に必要な情報が ctx に追加されます。
  Compresses the domain name indicated by name and stores it in the location indicated by sptr. length is the length of available space sptr. When compression is performed, the previously compressed domain name information in ctx is referenced. The length of the compressed domain name is placed in complenp and also the information necessary for compression is added to ctx.

  返される値は `mdn_success`、 `mdn_buffer_overflow`、 `mdn_invalid_name` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_name`

### lace モジュール
lace module

lace モジュールは、多言語ドメイン名のエンコーディング方式の一つとして 提案されている LACE エンコーディング とUTF-8との間の変換を行うモジュールです。このモジュールは converter モジュールの 下位モジュールとして実装されており、 アプリケーションがこのモジュールを直接呼び出すことはありません。 converter モジュールに対して `LACE` エンコーディング との変換を要求すると、このモジュールが間接的に呼び出されることになります。
The lace module performs conversion between UTF-8 and the proposed LACE multilingual domain name encoding method. This module is implemented as a low-order converter module, and is not directly called by the application. When the converter module is requested for conversion with `LACE` encoding, this module is indirectly called.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn__lace_open

      mdn_result_t
      mdn__lace_open(mdn_converter_t ctx, mdn_converter_dir_t dir)

  LACEエンコーディングとの変換をオープンします。実際には何もしません。
  Opens conversion context with LACE encoding. Actually, this does not do anything.

  常に `mdn_success`を返します。
  Always returns `mdn_success`.

mdn__lace_close

      mdn_result_t
      mdn__lace_close(mdn_converter_t ctx, mdn_converter_dir_t dir)

  LACEエンコーディングとの変換をクローズします。実際には何もしません。
  Closes conversion context with LACE encoding. Actually, this does not do anything.

  常に `mdn_success`を返します。
  Always returns `mdn_success`.

mdn__lace_convert

      mdn_result_t
      mdn__lace_convert(mdn_converter_t ctx, mdn_converter_dir_t dir,
      	const char *from, char *to, size_t tolen)

  LACEエンコードされた文字列とUTF-8エンコードされた文字列の相互変換を 行います。 入力文字列 from を変換し、結果を to と tolen で指定される領域に書き込みます。 dir が`mdn_converter_l2u`なら LACEエンコーディングからUTF-8エンコーディングへ、`mdn_converter_u2l` ならUTF-8エンコーディングからLACEエンコーディングへの変換となります。
  Provides bidirectional conversion between LACE character strings and UTF-8 character strings. The from input character string is converted and the result is written in the area specified by to and tolen. When dir is `mdn_converter_l2u`, LACE encoding is converted to UTF-8 encoding. When it is `mdn_converter_u2l`, UTF-8 encoding is converted to LACE encoding.

  返される値は `mdn_success`、 `mdn_buffer_overflow`、 `mdn_invalid_encoding`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_encoding`
  `mdn_nomemory`

### localencoding モジュール localencoding module

localencoding モジュールはロケール情報を利用して、 アプリケーションの使用しているエンコーディングを推測するモジュールです。
The localencoding module uses locale information to guess the encoding used by the application.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_localencoding_name

      const char *
      mdn_localencoding_name(void)

  現在のロケール情報を元に、アプリケーションの使用しているエンコーディング名 (mdn_converter_create() に渡す 名前) を推測して返します。
  Guesses the type of encoding used by the application (the name passed to mdn_converter_create())and returns it based on the current locale information.

  推測は、システムがnl_langinfo() を備えていればそれを利用し、 そうでなければsetlocale() や環境変数の情報から行われます。 後者の場合には必ずしも正しいエンコーディング名が得られるとは限りません。
  To guess the type of encoding, nl_langinfo() is used if it is available in the the system and if not, setlocale() or environmental variable information is used. In the latter case, the corrent encoding name may not be obtained.

  ロケール情報から正しい推測ができない場合、もしくはアプリケーションが ロケールと異なるエンコーディングを用いて動作している場合のために、 もし環境変数 MDN_LOCAL_CODESET が定義されていれば、 をアプリケーションのロケールに関わらず、その変数の値をエンコーディング名として 返すようになっています。
  When MDN_LOCAL_CODESET environmental variable is defined in order to deal with situations in which the correct encoding cannot be guessed from the locale information or the application is operating using different encoding than that the locale, this module returns the value of that variable as the encoding name regardless of the application locale.

### log モジュール log module

log モジュールはMDN ライブラリのログの出力処理を制御するモジュールです。 ログはデフォルトでは標準エラー出力に書き出されますが、ハンドラを登録する ことで、別の出力方法に変更することも可能です。
log module controls MDN library log output. A standard error output log is written by default. It can, however, be changed to another output method by registering the handler.

またログレベルを設定することも可能です。ログレベルは次の5段階が 定義されています。
The log level can be set as well. The following five log levels are defined.

>     enum {
>     	mdn_log_level_fatal   = 0,
>     	mdn_log_level_error   = 1,
>     	mdn_log_level_warning = 2,
>     	mdn_log_level_info    = 3,
>     	mdn_log_level_trace   = 4,
>     	mdn_log_level_dump    = 5
>     };

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_log_fatal

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

  fatal レベルのログを出力します。このレベルは、プログラムの実行が 不可能であるような致命的なエラーの際に用いられます。 引数はprintf と同じ形式で指定します。
  Outputs a fatal level log. This level is used when a fatal error occurs that causes problems such as when program execution cannot be performed. Arguments are specified using the same format as printf.

mdn_log_error

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

  error レベルのログを出力します。このレベルは、 致命的ではないエラーの際に用いられます。 引数はprintf と同じ形式で指定します。
  Outputs the error level log. This level is used when an error occurs that is not fatal. Arguments are specified using the same format as printf.

mdn_log_warning

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

  warning レベルのログを出力します。このレベルは警告メッセージを 表示するために用いられます。 引数はprintf と同じ形式で指定します。
  Outputs a warning level log. This level is used to display a warning message. Arguments are specified using the same format as printf.

mdn_log_info

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

  info レベルのログを出力します。このレベルはエラーではなく、 有用と思われる情報を出力するのに用いられます。 引数はprintf と同じ形式で指定します。
  Outputs info level log. This level is not used for errors but instead to output other potentially useful information. Arguments are specified using the same format as printf.

mdn_log_trace

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

  trace レベルのログを出力します。このレベルはAPI関数のトレース 情報を出力するのに用いられます。一般にライブラリのデバッグ目的以外で このレベルのログを記録する必要はないでしょう。 引数はprintf と同じ形式で指定します。
  Outputs the trace level log. This level is used to output API function trace information. Generally, this log does not need to be recorded for purposes other than debugging the library. The arguments are specified using the same format as printf.

mdn_log_dump

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

  dump レベルのログを出力します。このレベルはさらにデバッグ用の パケットデータダンプなどを出力するのに用いられます。 一般にライブラリのデバッグ目的以外でこのレベルのログを記録する 必要はないでしょう。 引数は printf と同じ形式で指定します。
  Outputs the dump level log. This level is used to output additional packet data dump for debugging. Generally, this level of log does not need to be recorded for purposes other than debugging the library. The arguments are specified using the same format as for printf.

mdn_log_setlevel

      void
      mdn_log_setlevel(int level)

  ログ出力のレベルを設定します。設定したレベルを超えるレベルの ログは出力されません。この関数でログレベルを設定しない場合、 環境変数 `MDN_LOG_LEVEL` に設定された整数値が使用されます。
  Sets the level of log output. Logs higher than the set level are not output. When the log level is not specified with this function, the integer value set to the `MDN_LOG_LEVEL` environmental variable is used.

mdn_log_getlevel

      int
      mdn_log_getlevel(void)

  現在のログ出力のレベルを表す整数値を取得して返します。
  Obtains and returns the integer value for the current level of log output.

mdn_log_setproc

      void
      mdn_log_setproc(mdn_log_proc_t proc)

  ログの出力ハンドラを設定します。proc はハンドラ関数への ポインタです。もしハンドラを指定しない場合、あるいは proc に NULL を指定した場合には、ログは標準エラー出力に出力されます。
  Used to set the log output handler. proc is a pointer to the handler function. When the handler is not specified or NULL is specified for proc, a standard error log is output.

  ハンドラの型 `mdn_log_proc_t` は次のように定義されています。
  The `mdn_log_proc_t` handler type is defined as follows.

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

  level にはログのレベルが、また msg には表示すべき メッセージ文字列が渡されます。
  The log level is passed to level and the message character string that should be displayed is passed to msg.

### msgheader モジュール msgheader module

msgheader モジュールはDNS メッセージのヘッダの解析、および組み立てを 行うモジュールです。
msgheader module analyses and assembles the DNS message header.

解析されたヘッダ情報は、次に示す構造体に入ります。各フィールドは DNS メッセージヘッダのフィールドにそのまま対応しているので、説明は省略します。
Analyzed header information is placed in the following structure. Since each field corresponds to a field of DNS message header, the explanation is omitted here.

>     typedef struct mdn_msgheader {
>     	unsigned int id;
>     	int qr;
>     	int opcode;
>     	int flags;
>     	int rcode;
>     	unsigned int qdcount;
>     	unsigned int ancount;
>     	unsigned int nscount;
>     	unsigned int arcount;
>     } mdn_msgheader_t;

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_msgheader_parse

      mdn_result_t
      mdn_msgheader_parse(const char *msg, size_t msglen,
      	mdn_msgheader_t *parsed)

  msg と msglen で示されるDNSメッセージのヘッダを 解析し、parsed が示す構造体に格納します。
  Analyses the DNS message headers indicated by msg and msglen and stores the information in the structure indicated by parsed.

  返される値は `mdn_success`、 `mdn_invalid_message` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_invalid_message`

mdn_msgheader_unparse

      mdn_result_t
      mdn_msgheader_unparse(mdn_msgheader_t *parsed,
      	char *msg, size_t msglen)

  この関数はmdn_msgheader_parse の 逆の処理を行います。つまり、parsed で指定された構造体のデータから DNSメッセージのヘッダを構成し、msg と msglen で 示される領域に格納します。
  This function performs reverse processing of mdn_msgheader_parse, in which the DNS message header is structured from the structure data specified by parsed, after which it is stored in the area specified by msg and msglen.

  返される値は `mdn_success`、 `mdn_buffer_overflow` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`

mdn_msgheader_getid

      unsigned int
      mdn_msgheader_getid(const char *msg)

  msg で指定されるDNSメッセージから ID を取り出して返します。 この関数はヘッダ全体を解析せずにIDだけ取り出したいときに便利です。 この関数は、msg の指すデータがDNSメッセージのヘッダ長以上ある ことを仮定していますので、必ず呼び出し側で確認してから呼び出すように してください。
  Extracts the ID from the DNS message specified by msg and returns it. This function is only useful for extracting the ID without analyzing the entire header. Since this function assumes the data indicated by msg is longer than the DNS message header length, always call the function after confirmation at the calling side.

mdn_msgheader_setid

      void
      mdn_msgheader_setid(char *msg, unsigned int id)

  msg で指定されるDNSメッセージに id で指定される ID を設定します。 この関数も msg の指すデータがDNSメッセージのヘッダ長以上ある ことを仮定していますので、必ず呼び出し側で確認してから呼び出すように してください。
  Sets the ID specified by id in the DNS message specified by msg. Since this function also assumes that the data indicated by msg is longer than the DNS message header length, always call the function after confirmation at the calling side.

### msgtrans モジュール
msgtrans module

msgtrans モジュールはDNS プロキシサーバでの DNS メッセージの変換処理の 大部分を提供するモジュールです。このモジュールは converter モジュールや normalizer モジュールなど他の多くのモジュールを の上位モジュールとして実現されています。
The msgtrans module provides a large portion of DNS message conversion processing performed by the DNS proxy server. This module is implemented as a high-order module for many other modules including the converter module and normalizer module.

DNSプロキシサーバにおけるメッセージ変換処理はおよそ次のようなものです。
Message conversion processing by the DNS proxy server is briefly explained below.

まずクライアントからDNSサーバへのメッセージの変換の場合は次の ようになります。
Conversion of a message from a client to the DNS server is as follows.

1. クライアントから受信したリクエストメッセージを解析し、 クライアント側の ZLD およびエンコーディングを判定します。
   Request message received from client is analyzed and ZLD and encoding at the client side are determined.
2. 判定結果を用いて、ドメイン名からZLDを除去し、エンコーディングをUTF-8に 変換します。
   Based on the determination result, ZLD are removed from domain names and encoding is converted to UTF-8.
3. 正規化処理を行います。
   Normalization processing is performed.
4. エンコーディングを UTF-8からDNSサーバ側で用いられるエンコーディングに 変換し、ZLDを付加します。
   The encoding is converted from UTF-8 to the encoding method used by the DNS server side and ZLD are added.
5. 以上の処理をメッセージに含まれるすべてのドメイン名に対して行い、 変換結果を再び DNS メッセージ形式にまとめて DNS サーバに送信します。
   The above processing is performed on all domain names included in the message and the conversion results are collectively placed in the DNS message format and then sent to the DNS server.

次にDNSサーバからクライアントへのメッセージの変換の場合は次の ようになります。
Conversion of messages from the DNS server to the client is as follows.

1. DNSサーバから受信したリプライメッセージを解析し、 含まれているすべてのドメイン名に対して、ZLDの除去、UTF-8エンコーディング への変換を行います。
   The reply message received from the DNS server is analyzed and removal of ZLD and conversion to UTF-8 encoding are performed on all domain names included in the message.
2. さらにクライアント側エンコーディングに変換し、ZLDを付加します。
   Encoding is converted to the client side encoding and ZLD are added.
3. 変換結果を再び DNS メッセージ形式にまとめてクライアントに送信します。
   The conversion results are collectively placed in the DNS message format and then sent to the client.

このように、DNSメッセージの変換に際しては、 クライアント・サーバ側のZLD、エンコーディング等 いろいろなパラメータが必要となります。API関数にこれらを指定する際、 それぞれを別々の引数で指定するのは煩雑なので、次のような構造体を 用いてまとめて渡すようにしてあります。
As explained above, various parameters with respect to ZLD at the client/server side and encoding are necessary for DNS message conversion. When specifying those parameters for API functions, it is troublesome to specify them using different arguments for various functions. To avoid this, the following structure can be used to pass the parameters collectively.

>     typedef struct mdn_msgtrans_param {
>     	int use_local_rule;
>     	mdn_ZLDrule_t local_rule;
>     	mdn_converter_t local_converter;
>     	mdn_converter_t local_alt_converter;
>     	char *local_ZLD;
>     	mdn_converter_t target_converter;
>     	mdn_converter_t target_alt_converter;
>     	char *target_ZLD;
>     	mdn_normalizer_t normalizer;
>     } mdn_msgtrans_param_t;

`use_local_rule`は、入力側のメッセージのZLDおよびエンコーディングの 判定方法を指定します。
`use_local_rule` specifies the ZLD and encoding determination method fr the message at the input side.

もし値が真ならば、これらは`local_rule`で 指定されるZLDとエンコーディングの集合とメッセージに含まれるドメイン名の マッチング処理を行い、マッチしたものが使われます。 これはクライアントからDNSサーバへのリクエストメッセージの変換の際に 用いられます。 この場合、判定結果が`local_converter`と`local_ZLD`に 代入されます。
When the value is true, matching processing is performed on the ZLD and encoding as specified by `local_rule` and the domain names included in the message, and the matches are used when converting the request message from the client to the DNS server; in this case, the judgement results are assigned to `local_converter` and `local_ZLD`.

一方、`local_rule`が偽ならばZLDおよびエンコーディングは `local_converter`と`local_ZLD`で指定されるものがそのまま 使用されます。 これはDNSサーバからクライアントへのリクエストメッセージの変換の際に 用いられます。 この場合`local_rule`の値は使用されません。`use_local_rule` の値に関わらず、`local_alt_converter` は入力側メッセージの代替エンコーディングとして使用されます。代替エンコーディングがない場合には NULL を指定します。
On the other hand, if `local_rule` is false, the ZLD and encoding specified by `local_converter` and `local_ZLD` are used as is when converting the request message sent from DNS server to the client; in this case, the value of `local_rule` is not used. Regardless of the value of `use_local_rule`, `local_alt_converter` defines the alternate encoding method used to encode the message at the input side. When there is no alternate encoding, NULL is specified.

`target_converter` and `target_ZLD` are used to specify the output side encoding and ZLD. ``target_converter`と`target_ZLD`で出力側の エンコーディングとZLDを指定します。 `target_alt_converter`は、`target_converter`による 出力側のエンコーディングへの変換が、変換しようとするドメイン名に 出力側の文字集合にない文字が含まれていたために失敗した場合に、 `target_converter`の代わりに使用されます。 なお `local_alt_converter` と `target_alt_converter` に対応するエンコーディングはいずれも ASCII 互換エンコーディングでなければなりません。
target_alt_converter` is alternately used with `target_converter` when the conversion by `target_converter` to the output side encoding fails because the domain name to be converted includes characters that do not exist in the output side character set. Note that the encoding corresponding to `local_alt_converter` and `target_alt_converter` must be ASCII-compatible encoding, respectively.

`normalizer`は正規化方式を指定します。
`normalizer` specifies normalization method.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_msgtrans_translate

      mdn_result_t
      mdn_msgtrans_translate(mdn_msgtrans_param_t *param,
      	const char *msg, size_t msglen,
      	char *outbuf, size_t outbufsize,
      	size_t *outmsglenp)

  msg および msglen で指定されるDNSメッセージを 変換パラメータ param にしたがって変換し、結果を outbuf および outbufsize で示される領域に格納します。 outmsglenp には変換結果のメッセージ長が格納されます。
  Converts the DNS messages specified by msg and msglen according to the conversion parameter param and stores the result in the area indicated by outbuf and outbufsize. The message length of the conversion result is stored in outmsglenp.

  返される値は `mdn_success`、 `mdn_invalid_message`、 `mdn_invalid_encoding`、 `mdn_buffer_overflow` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_invalid_message`
  `mdn_invalid_encoding`
  `mdn_buffer_overflow`

### normalizer モジュール
normalizer module

normalizer モジュールは文字列の正規化を行うモジュールです。 正規化の方式としては現在次のものが用意されています。 また別の新たな正規化方式を追加登録するためのAPIも用意されています。
normalizer module normalizes character string. The following normalization methods are currently provided. In addition, API used to additionally register new normalization method is provided.

- `ascii-uppercase`
  ASCII の小文字から大文字への変換
  Converts ASCII lowercase to uppercase
- `ascii-lowercase`
  ASCII の大文字から小文字への変換
  Converts ASCII uppercase to lowercase
- `unicode-uppercase`
  Unicode の文字属性を規定した Case Mappings に記述されている小文字大文字マッピングに従った小文字から大文字への変換
  Converts lowercase to uppercase in accordance with the lowercase/uppercase mapping described in Case Mappings that prescribes character properties of Unicode.
- `unicode-lowercase`
  上記と同じ文書にしたがった大文字から小文字への変換
  Converts uppercase to lowercase in accordance with the same above document.
- `unicode-form-c`
  Unicode の正規化方式を規定した Unicode Normalization Forms に記述されているNormaliztion form C に従う正規化
  Normalizes characters in accordance with Normaliztion form C described in Unicode Normalization Forms that prescribes normalization method of Unicode.
- `unicode-form-kc`
  同文書に記述されている Unicode Normalization Form KC に 従う正規化
  Normalizes characters in accordance with Unicode Normalization Form KC described in the above same document.
- `ja-kana-fullwidth`
  日本語の半角かなから全角カタカナへの変換
  Converts Japanese single-byte katakana to double-byte katakana.
- `ja-fullwidth`
  `ja-kana-fullwidth` と同じ。 これは以前のバージョンとの互換性のために残されているもので、 将来のバージョンではなくなる可能性があります。`ja-kana-fullwidth` を使ってください。
  Same as `ja-kana-fullwidth`. This is kept for compatibility with the previous version and may be eliminated in the future version. Use `ja-kana-fullwidth`.
- `ja-alnum-halfwidth`
  日本語の全角英数字および全角マイナス記号を半角文字に変換
  Converts Japanese double-byte alphanumeric characters and double-byte minus symbol to single-byte characters
- `ja-compose-voiced-sound`
  日本語の全角かなとそれに続く濁点(゛)半濁点(゜)を 濁点・半濁点つきのかな1文字に変換
  Converts Japanese double-byte katakana and following voiced consonant mark (゛) and circle attached to certain katakana (゜) to one katakana character attached with voiced consonant mark or circle.
- `ja-minus-hack`
  日本語の全角マイナス記号(−)からハイフン(`-`)への変換
  Converts Japanese double-byte minus symbol (−) to hyphen(-).
- `ja-delimiter-hack`
  句点(。)および全角ピリオド(．)からピリオド(`.`)への変換
  Converts Japanese period (。) and double-byte period (．) to period (`.`).

最後の`ja-delimiter-hack`は句点および全角ピリオドを ドメイン名のセパレータであるピリオドと見なすようにするもので、 これは本来多言語ドメイン名のユーザ入力の際の手間および間違いを軽減するために 用意されたものですが、ブラウザによってはピリオドのないドメイン名が ドメイン名ではなくキーワードと認識されてしまうなどの問題があり、 またこれはドメイン名の正規化の範囲を逸脱しているとも考えられるので、 できるだけこの正規化方式の使用は避けるべきです。
The last `ja-delimiter-hack` is to assume Japanese period and double-byte period as the period that is the separator of domain name. This is originally provided to reduce steps or mistakes when user enters multilingual domain names. However, depending on browser, there are problems that domain names without period are recognized as keyword not domain name and also this method is supposed to exceed the scope of normalization of domain names, therefore, use of this normalization method should be avoided as much as possible.

正規化方式は複数併用することも可能で、この場合指定した順に適用されます。
More than one normalization methods can be used and they are applied in the order they were specified.

normalizer モジュールは「正規化コンテキスト」という概念を用います。 正規化を行うに先立ってまず正規化コンテキストを作成し、使用する正規化方式をコンテキストに登録しておきます。実際の正規化処理の際には正規化方式ではなく、この正規化コンテキストを指定します。正規化コンテキストの型はmdn_normalizer_t 型であり、次のような opaque 型として定義されています。
normalizer module uses the concept "normalization context". Prior to normalization, a normalization context is created and the normalization method to be used is registered in the context. For actual normalization procesesing, not the normalization method but this normalization context is specified. The type of normalization context is mdn_normalizer_t type and defined as the following opaque type.

>     typedef struct mdn_normalizer *mdn_normalizer_t;

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_normalizer_initialize

      mdn_result_t
      mdn_normalizer_initialize(void)

  モジュールの初期化処理を行います。本モジュールの他のAPI関数を呼ぶ前に 必ず呼び出してください。
  Initializes module. Make sure to call this function before calling other API function of this module.

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

mdn_normalizer_create

      mdn_result_t
      mdn_normalizer_create(mdn_normalizer_t *ctxp)

  正規化用の空のコンテキストを作成し、ctxp の指す領域に格納します。 返されるコンテキストは空で、正規化方式は一つも含まれていません。 正規化方式を追加するには mdn_normalizer_add を用います。
  Creates an empty content for normalization and stores it in the area specified by ctxp. The returned content is empty and does not contain any normalization methods. To add normalization method, mdn_normalizer_add is used.

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

mdn_normalizer_destroy

      void
      mdn_normalizer_destroy(mdn_normalizer_t ctx)

  mdn_normalizer_create で 作成した正規化コンテキストを削除し、アロケートされたメモリを解放します。
  Deletes the normalization context created by mdn_normalizer_create and releases the allocated memory.

mdn_normalizer_add

      mdn_result_t
      mdn_normalizer_add(mdn_normalizer_t ctx, const char *scheme_name)

  mdn_normalizer_create で 作成した正規化コンテキストに、scheme_name で指定される 正規化方式を追加します。一つのコンテキストに複数の正規化方式を 追加することができます。
  Adds the normalization method specified by scheme_name in the normalization context created by mdn_normalizer_create. More than one normalization methods can be specified in one context.

  返される値は `mdn_success`、 `mdn_invalid_name`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_invalid_name`
  `mdn_nomemory`

mdn_normalizer_normalize

      mdn_result_t
      mdn_normalizer_normalize(mdn_normalizer_t ctx,
      	const char *from, char *to, size_t tolen)

  UTF-8 でエンコードされた文字列 from に ctx で 指定される正規化方式を適用し、その結果を to と tolen で 指定される領域に書き込みます。 ctx に複数の正規化方式が含まれている場合、それらが mdn_normalizer_add で追加した順番に 適用されます。
  Applies the normalization method specified by ctx to the character strings encoded by UTF-8 from and writes the result in the area specified by to and tolen. When more than one normalization method is included in ctx, they are applied in the order they were added by mdn_normalizer_add.

  返される値は `mdn_success`、 `mdn_invalid_encoding`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_invalid_encoding`
  `mdn_nomemory`

mdn_normalizer_register

      mdn_result_t
      mdn_normalizer_register(const char *scheme_name,
      	mdn_normalizer_proc_t proc)

  新しい正規化方式を scheme_name という名前で登録します。 proc はその正規化方式の処理関数へのポインタです。
  New normalization methods are registered in scheme_name.proc is a pointer to the processing function of that normalization method.

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

### race モジュール
race module

race モジュールは、多言語ドメイン名のエンコーディング方式の一つとして 提案されている RACE エンコーディング とUTF-8との間の変換を行うモジュールです。このモジュールは converter モジュールの下位モジュールとして実装されており、 アプリケーションがこのモジュールを直接呼び出すことはありません。 converter モジュールに対して `RACE` エンコーディング との変換を要求すると、このモジュールが間接的に呼び出されることになります。
The race module performs conversion between UTF-8 and the proposed RACE multilingual domain name method. This module is implemented as a low-order module of converter module and is not directly called by the application. When converter module is requested for conversion with `RACE` encoding, this module is indirectly called.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn__race_open

      mdn_result_t
      mdn__race_open(mdn_converter_t ctx, mdn_converter_dir_t dir)

  RACEエンコーディングとの変換をオープンします。実際には何もしません。
  Opens conversion context with RACE encoding. Actually, this does not do anything.

  常に `mdn_success`を返します。
  Always returns `mdn_success`.

mdn__race_close

      mdn_result_t
      mdn__race_close(mdn_converter_t ctx, mdn_converter_dir_t dir)

  RACEエンコーディングとの変換をクローズします。実際には何もしません。
  Closes conversion context with RACE encoding. Actually, this does not do anything.

  常に `mdn_success`を返します。
  Always returns `mdn_success`.

mdn__race_convert

      mdn_result_t
      mdn__race_convert(mdn_converter_t ctx, mdn_converter_dir_t dir,
      	const char *from, char *to, size_t tolen)

  RACEエンコードされた文字列とUTF-8エンコードされた文字列の相互変換を 行います。 入力文字列 from を変換し、結果を to と tolen で指定される領域に書き込みます。 dir が`mdn_converter_l2u`なら RACEエンコーディングからUTF-8エンコーディングへ、`mdn_converter_u2l` ならUTF-8エンコーディングからRACEエンコーディングへの変換となります。
  Performs bidirectional conversion between RACE-encoded and UTF-8 encoded character strings. Converts the from input character string and writes the result in the area specified by to and tolen. When dir is `mdn_converter_l2u`, RACE encoding is converted to UTF-8 encoding. When it is `mdn_converter_u2l`, UTF-8 encoding is converted to RACE encoding.

  返される値は `mdn_success`、 `mdn_buffer_overflow`、 `mdn_invalid_encoding`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_encoding`
  `mdn_nomemory`

### res モジュール
res module

res モジュールはクライアント側 (リゾルバライブラリやアプリケーション) で多言語ドメイン名の処理、つまりドメイン名のエンコーディング変換や 正規化を行う際の高レベル API を提供します。 このモジュールはあとで説明する resconf モジュール とともに用いることを前提に設計されています。
The res module provides high level APIs used when multilingual domain names are processed at the client side (by the resolver library or an application) i.e. when domain name encoding conversion or normalization is performed. This module is designed on the assumption that it will be used together with resconf module, which is explained below.

これらのモジュールの提供する API を使用すれば、 converter モジュールや normalizer モジュールなどの関数を直接 呼び出す必要はありません。
Using APIs provided by the module, it is not necessary to directly call converter module or normalizer module function.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_res_localtoucs

      mdn_result_t
      mdn_res_localtoucs(mdn_resconf_t conf, const char *local_name,
      	char *ucs_name, size_t ucs_name_len)

  アプリケーションの使用するローカルエンコーディングで表された ドメイン名文字列 local_name を UTF-8 に変換し、その結果を ucs_name に格納します。ucs_name_len で あらかじめ ucs_name に確保した領域の大きさを指定します。
  Converts local_name domain name character strings expressed in the local encoding used by the application to UTF-8 and stores the result in ucs_name. ucs_name_len is used to specify the size of the area secured for ucs_name beforehand.

  conf は resconf モジュール の返す クライアント設定コンテキストです。もし conf が NULL であれば 変換は行われず、local_name の内容がそのまま ucs_name にコピーされます。
  conf is the client configuration context returned by resconf module. When conf is NULL, conversion is not performed and the contents of local_name is copied to ucs_name as is.

  ドメイン名 local_name が従来の ASCII ドメイン名として 正しく (つまり英数字およびハイフンとピリオドから構成される)、かつ クライアント設定コンテキスト conf に代替エンコーディング が設定されている場合、ローカルエンコーディングとしての変換を行う前に 代替エンコーディングから UTF-8 の変換を試み、失敗した場合に ローカルエンコーディングから UTF-8 への変換を行います。これによって、 mdn_res_ucstolocal が 与えられたドメイン名をローカルエンコーディングに変換できず 代替エンコーディングに変換した場合でも、それを本関数に与えれば 正しい UTF-8 エンコーディングのドメイン名が得られます。
  Conversion from local encoding to UTF-8 is performed when the local_name domain name is a valid conventional ASCII domain name (that is, it consists of alphanumeric characters, hyphens and periods), alternate encoding is set in the client configuraiton context conf, and conversion to UTF-8 from the alternate encoding is attempted and failed before conversion of the local encoding is performed. Because of this, even if mdn_res_ucstolocal could not convert the given domain name to the local encoding and converted to the alternate encoding, if it is given to this function, the correct UTF-8 encoded domain name can be obtained.

  返される値は `mdn_success`、 `mdn_buffer_overflow`、 `mdn_invalid_name`、 `mdn_failure` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_name`
  `mdn_failure`

mdn_res_ucstolocal

      mdn_result_t
      mdn_res_ucstolocal(mdn_resconf_t conf, const char *ucs_name,
      	char *local_name, size_t local_name_len)

  mdn_res_localtoucs の 逆の変換、つまり UTF-8 で表されたドメイン名文字列 ucs_name をアプリケーションの使用するローカルエンコーディングに変換し、その結果を local_name に格納します。local_name_len で あらかじめ local_name に確保した領域の大きさを指定します。
  Performs reverse conversion of mdn_res_localtoucs, i.e., converts the ucs_name domain name character string expressed in UTF-8 to the local encoding used by the application and stores the result in local_name. local_name_len is used to specify the size of the area secured for local_name beforehand.

  conf は resconf モジュール の返す クライアント設定コンテキストです。もし conf が NULL であれば 変換は行われず、local_name の内容がそのまま ucs_name にコピーされます。
  conf is the client configuration context returned by resconf module. When conf is NULL, conversion is not performed and the contents of local_name is copied in ucs_name as is.

  もしドメイン名 ucs_name の中にローカルエンコーディングの 文字集合にない文字があって変換に失敗した場合、クライアント設定コンテキスト conf に代替エンコーディングが設定されていれば、 ローカルエンコーディングの代わりに代替エンコーディングへの変換が行われます。 これにより、たとえ DNS サーバからローカルエンコーディングに含まれない文字を 含むドメイン名が返された場合にもエラーとならずに変換が行われます。 なお、代替エンコーディングに変換された文字列は mdn_res_localtoucs によって UTF-8 文字列に戻すことが可能です。
  When conversion fails because a character that is not in the character set of the local encoding is contained in the ucs_name domain name, if the alternate encoding is set in the client configuration context conf, conversion to the alternate encoding is performed instead of to the local encoding. Because of this, even if the DNS server returns a domain name that includes a character that is not included in the local encoding, conversion is performed without error. Note that character strings converted to the alternate encoding can be returned to UTF-8 character strings by mdn_res_localtoucs.

  返される値は `mdn_success`、 `mdn_buffer_overflow`、 `mdn_invalid_name`、 `mdn_failure` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_name`
  `mdn_failure`

mdn_res_normalize

      mdn_result_t
      mdn_res_normalize(mdn_resconf_t conf, const char *name,
                        char *normalized_name, size_t normalized_name_len)

  クライアント設定コンテキスト conf にしたがって UTF-8 で表されたドメイン名 name に対して正規化を実行し、 その結果を normalized_name に格納します。 normalized_name_len であらかじめ normalized_name に 確保した領域の大きさを指定します。
  Executes normalization on the name domain name expressed in UTF-8 according to the client configuration context conf and stores the result in normalized_name. normalized_name_len is used to specify the size of the area secured for normalized_name beforehand.

  もし conf が NULL であれば正規化は行われず、 name の内容がそのまま normalized_name にコピーされます。
  When conf is NULL, normalization is not performed and the contents of name is copied in normalized_name as is.

  返される値は `mdn_success`、 `mdn_buffer_overflow`、 `mdn_invalid_encoding`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_encoding`
  `mdn_nomemory`

mdn_res_ucstodns

      mdn_result_t
      mdn_res_ucstodns(mdn_resconf_t conf, const char *ucs_name, char *dns_name,
      	size_t dns_name_len)

  クライアント設定コンテキスト conf にしたがって UTF-8 で表されたドメイン名 ucs_name を DNS プロトコル上で 用いられるエンコーディングに変換し、その結果を dns_name に 格納します。 dns_name_len であらかじめ dns_name_len に 確保した領域の大きさを指定します。
  Converts the ucs_name domain name expressed in UTF-8 to the encoding used in the DNS protocol per the conf client configuration context and stores the result in dns_name. dns_name_len is used to specify the size of the area secured for dns_name_len beforehand.

  もし conf が NULL であれば変換は行われず、 ucs_name の内容がそのまま dns_name にコピーされます。
  When conf is NULL, conversion is not performed and the contents of ucs_name are copied to dns_name as is.

  返される値は `mdn_success`、 `mdn_buffer_overflow`、 `mdn_invalid_encoding`、 `mdn_invalid_name`、 `mdn_failure` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_encoding`
  `mdn_invalid_name`
  `mdn_failure`

mdn_res_dnstoucs

      mdn_result_t
      mdn_res_dnstoucs(mdn_resconf_t conf, const char *dns_name, char *ucs_name,
      	size_t ucs_name_len)

  mdn_res_ucstodns の逆変換、 つまりクライアント設定コンテキスト conf にしたがって DNS プロトコル上のエンコーディングで表されたドメイン名 dns_name を UTF-8 に変換し、その結果を ucs_name に格納します。 ucs_name_len であらかじめ ucs_name_len に 確保した領域の大きさを指定します。
  Performs reverse conversion of mdn_res_ucstodns, i.e., converts the dns_name domain name expressed in the encoding used in the DNS protocol to UTF-8 per the conf client configuration context and stores the result in ucs_name. ucs_name_len is used to specify the size of the area secured for ucs_name_len beforehand.

  もし conf が NULL であれば変換は行われず、 dns_name の内容がそのまま ucs_name にコピーされます。
  When conf is NULL, conversion is not peformed and the contents of dns_name are copied to ucs_name as is.

  返される値は `mdn_success`、 `mdn_buffer_overflow`、 `mdn_invalid_encoding`、 `mdn_invalid_name`、 `mdn_failure` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_encoding`
  `mdn_invalid_name`
  `mdn_failure`

### resconf モジュール
resconf module

resconf モジュールはクライアント側 (リゾルバライブラリやアプリケーション) で多言語ドメイン名の処理を行う際に参照される クライアント設定ファイルを読み込み、 ファイルに記述された設定にしたがった初期化を実行します。また 設定情報を取り出す機能を提供します。
The resconf module loads the client configuration file referenced when a multilingual domain name is processed at the client side (by a resolver library or application) and executes initialization in accordance with the settings described in the file. It also provides a function to extract the setting information.

resconf モジュールは「クライアント設定コンテキスト」という概念を用います。 クライアント設定ファイルに記述された設定はこのクライアント設定コンテキストに 格納され、このコンテキストを引数にして API 関数を呼び出すことによって 設定された値を取り出すことができます。 クライアント設定コンテキストの型は mdn_resconf_t 型であり、 次のような opaque 型として定義されています。
The resconf module uses the "client configuration context" concept. Settings described in the client configuration file are stored in this client configuration context, which is used as an argument to call API functions to extract the set values. The client configuration context is defined by mdn_resconf_t and is of the following opaque type.

>     typedef struct mdn_resconf *mdn_resconf_t;

このモジュールは単体でも使用できますが、 res モジュールと組み合わせることによって、 クライアント側での多言語ドメイン名の処理を簡単に行うことができるように 設計されています。
This module can be used as a single module but it is designed so that by combining it with res module multilingual domain names can easily be processed at the client side.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_resconf_initialize

      mdn_result_t
      mdn_resconf_initialize(void)

  多言語ドメイン名の処理を行う際に必要な初期化を実行します。 本モジュールの他のAPI関数を呼ぶ前に必ず呼び出してください。 本モジュールが使用する他のモジュールの初期化もすべて行うので、これ以外の初期化 関数を呼び出す必要はありません。
  Executes initialization required when processing multilingual domain names. Always call this function before calling other API functions of this module. Since this function initializes all other modules used by this module, it is not necessary to call another initialization function.

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

mdn_resconf_create

      mdn_result_t
      mdn_resconf_create(mdn_resconf_t *ctxp)

  クライアント設定コンテキストを作成、初期化し、ctxp の指す 領域に格納します。 初期状態では、まだクライアント設定ファイルの内容は読み込まれていません。 読み込むためには mdn_resconf_loadfile を実行する必要があります。
  Creates and initializes client configuration context and stores it in the area indicated by ctxp. In the initial status, the contents of the client configuration file are not loaded. To do so, mdn_resconf_loadfile must be executed.

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

mdn_resconf_destroy

      void
      mdn_resconf_destroy(mdn_resconf_t ctx)

  mdn_resconf_create で 作成されたクライアント設定コンテキストを削除し、確保したメモリを解放します。
  Deletes the client configuration context created by mdn_resconf_create and releases the allocated memory.

mdn_resconf_loadfile

      mdn_result_t
      mdn_resconf_loadfile(mdn_resconf_t ctx, const char *file)

  file で指定される クライアント設定ファイルの内容を読み込み、 設定内容をクライアント設定コンテキスト ctx に格納します。 file が NULL の場合にはデフォルトのクライアント設定ファイルの 内容を読み込みます。
  Loads the contents of the client configuration file specified by file and stores the setting contents in the ctx client configuration context. When file is NULL, the contents of the default client configuration file are loaded.

  すでに設定ファイルが読み込まれているコンテキストに対して、 別の設定ファイルの内容を読み込むこともできます。その場合には、 クライアント設定コンテキストに格納されていた前の設定ファイルの内容は すべて消え、新たに読み込んだ設定ファイルの内容で置き換わります。
  If the configuration file has already been loaded and another configuration file is loaded, the previous configuration file contents stored in the client configuration context are erased and replaced with the newly loaded configuration file contents.

  返される値は `mdn_success`、 `mdn_nofile`、 `mdn_invalid_syntax`、 `mdn_invalid_name`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nofile`
  `mdn_invalid_syntax`
  `mdn_invalid_name`
  `mdn_nomemory`

mdn_resconf_defaultfile

      char *
      mdn_resconf_defaultfile(void)

  デフォルトのクライアント設定ファイルのパス名を返します。 これは mDNkit のコンパイル時の設定によって決まりますが、特に指定しなければ
  Returns the path to the default client configuration file. This is determined by the settings set when mDNkit is compiled. The default path is as follows:

  >     /usr/local/etc/mdnres.conf

  です。

mdn_resconf_localconverter

      mdn_converter_t
      mdn_resconf_localconverter(mdn_resconf_t ctx)

  クライアント設定コンテキスト ctx の情報を元に、 ローカルエンコーディングと UTF-8 との間の文字コード変換を行うための コード変換コンテキストを返します。ローカルエンコーディングが判別できなかった 場合には NULL を返します。
  Based on the ctx client configuration context information, returns the code conversion context to perform character code conversion between the local encoding and UTF-8. NULL is returned if the local encoding cannot be determined.

  コード変換コンテキストについては converter モジュール の項をご覧ください。
  For details of code conversion context, refer to the converter module section.

mdn_resconf_alternateconverter

      mdn_converter_t
      mdn_resconf_alternateconverter(mdn_resconf_t ctx)

  クライアント設定コンテキスト ctx の情報を元に、 代替エンコーディングと UTF-8 との間の 文字コード変換を行うためのコード変換コンテキストを返します。 代替エンコーディングとはドメイン名をローカルエンコーディングに変換することが できなかった場合に、ローカルエンコーディングの代わりに用いられる エンコーディングのことです。 クライアント設定ファイルがまだ読み込まれていなかったり、設定ファイルに エンコーディングの指定がなかった場合には NULL を返します。
  Based on the ctx client configuration context information, returns the code conversion context to perform character code conversion between the alternate encoding and UTF-8. The alternate encoding is used instead of the local encoding when a domain name could not be converted to the local encoding. NULL is returned if the client configuration file has not been loaded or the encoding method is not specified in the configuration file.

  コード変換コンテキストについては converter モジュール の項をご覧ください。
  For code conversion context, refer to converter module section.

mdn_resconf_serverconverter

      mdn_converter_t
      mdn_resconf_serverconverter(mdn_resconf_t ctx)

  クライアント設定コンテキスト ctx の情報を元に、 DNS プロトコル上で用いられるエンコーディングと UTF-8 との間の 文字コード変換を行うためのコード変換コンテキストを返します。 クライアント設定ファイルがまだ読み込まれていなかったり、設定ファイルに エンコーディングの指定がなかった場合には NULL を返します。
  Based on the information of client configuration context ctx, returns the code conversion context to perform character code conversion between the encoding used on DNS protocol and UTF-8. NULL is returned if the client configuration file has not been loaded or the encoding method is not specified in the configuration file.

  コード変換コンテキストについては converter モジュール の項をご覧ください。
  For code conversion context, refer to converter module section.

mdn_resconf_ZLD

      const char *
      mdn_resconf_ZLD(mdn_resconf_t ctx)

  クライアント設定コンテキスト ctx の情報を元に、 多言語ドメイン名と従来のドメイン名とを区別するために一部の エンコーディングとともに用いられる ZLD の文字列を返します。 ZLD を使用しない設定の場合には NULL を返します。
  Based on the information in the ctx client configuration context, returns the ZLD character string used together with some encoding methods to differentiate between multilingual domain names and conventional domain names. NULL is returned when ZLD is not used.

  mDNkit はデフォルトの設定では ZLD をサポートせず、この関数は常に NULL を返します。mDNkit を ZLD をサポートするように設定する方法に ついては mDNkit のインストールガイドの `configure` 実行 の項をご覧ください。
  By default, mDNkit does not support ZLD and this function always returns NULL. For details of how to set mKNkit to support ZLD, refer to `configure` execute in the mDNkit Installation Guide.

mdn_resconf_normalizer

      mdn_normalizer_t
      mdn_resconf_normalizer(mdn_resconf_t ctx)

  クライアント設定コンテキスト ctx の情報を元に、 ドメイン名を正規化するための正規化コンテキストを返します。 クライアント設定ファイルがまだ読み込まれていなかったり、設定ファイルに 正規化方式の指定がなかった場合には NULL を返します。
  Based on the information of client configuration context ctx, returns the normalization context used to normalize domain names. NULL is returned if the client configuration file has not been loaded or the normalization method is not specified in the configuration file.

  正規化コンテキストについては normalizer モジュール の項をご覧ください。
  For details of normalization context, refer to the normalizer module section.

### result モジュール result module

result モジュールはライブラリの各関数が返す `mdn_result_t`型の値を扱うモジュールで、 値からそのコードに対応するメッセージへの変換を提供します。
The result module handles the `mdn_result_t` type value returned by each function in the library and converts the value to the corresponding message code.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

      char *
      mdn_result_tostring(mdn_result_t result)

  `mdn_result_t`型の値 result に対応する メッセージ文字列を返します。
  Returns the message character string corresponding to the value result of `mdn_result_t` type.

  未定義のコードに対しては `unknown result code` という文字列が 返されます。
  An `unknown result code` character string is returned for undefined code.

### selectiveencode モジュール selectiveencode module

selectiveencode モジュールはゾーンマスタファイル等のテキストの中から 非ASCII文字を含むドメイン名を探し出すモジュールです。 もちろんテキストのどの部分がドメイン名なのかを判定することは一般的には 不可能なので、実際には次のような大きな仮定を置くことによって 近似的に実現しています。
The selectiveencode module finds domain names that include non-ASCII characters in text such as zone master files. Generally speaking it is of course impossible to determine which part of the text is the domain name; in actuality, however, the following rough assumptions are used to approximately implement it.

- 非ASCII文字はドメイン名の中にのみ現れる
  Non-ASCII characters appear only in domain names.

具体的には次のようなアルゴリズムを用いてドメイン名の領域検出を行います。
Specifically, the following algorithm is used to detect the domain name area.

1. テキストを走査して、非ASCII文字を探す。
   Scans the text and finds non-ASCII characters.
2. 見つかった非ASCII文字の前後の文字を調べ、 その文字を含み、かつ他の非ASCII文字あるいは従来の(多言語化されていない) ドメイン名として使用可能な文字だけからなる範囲を求める。
   Check characters before and after found non-ASCII characters to determine a range consisting of only the found character and also other non-ASCII characters or characters that can be used for conventional (not internationalized) domain names.
3. 求めた範囲をドメイン名として返す。
   Returns the found range as the domain name.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_selectiveencode_findregion

      mdn_result_t
      mdn_selectiveencode_findregion(const char *s,
      	char **startp, char **endp)

  UTF-8でエンコードされた文字列 s を走査して、最初に出現する 非ASCII文字を含むドメイン名の領域を求め、その先頭を指すポインタを startp に、領域の直後の文字を指すポインタを endp に それぞれ格納します。
  Scans s UTF-8 encoded character strings and finds the area in the domain that includes the first appearance of a non-ASCII character, then stores a pointer indicating the beginning of the area at startp and a pointer indicating the end of the area in endp.

  返される値は `mdn_success`、 `mdn_notfound` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_notfound`

### strhash モジュール
strhash module

strhash モジュールは文字列をキーとするハッシュ表を実現するモジュールです。 ハッシュ表は converter モジュールや normalizer モジュールなどライブラリの他のモジュールで 使用されます。 非常に一般的なハッシュ表の実装であり、特筆すべき点はありません… 一つだけあります。登録はできますが削除の機能がありません。本ライブラリでは 必要ないからです。
The strhash module implements a hash table that uses a character string as a key. The hash table is used by other modules in the library such as the converter module and normalizer module. This is a very general hash table implementation in which registration can be performed but there is no deletion function because it is not needed with this library.

ハッシュ表のサイズは要素の総数が増えるに従って大きくなります。
The size of the hash table increases as the total numer of elements increases.

ハッシュ表は次に示す mdn_strhash_t 型の opaque データとして 表されます。
As shown below, the hash table is expressed in opaque data of mdn_strhash_t type.

>     typedef struct mdn_strhash *mdn_strhash_t;

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_strhash_create

      mdn_result_t
      mdn_strhash_create(mdn_strhash_t *hashp)

  空のハッシュ表を作成し、そのハンドルを hashp の指す領域に 格納します。
  Creates an empty hash table and stores the handle to the area indicated by hashp.

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

mdn_strhash_destroy

      void
      mdn_strhash_destroy(mdn_strhash_t hash)

  mdn_strhash_create で作成した ハッシュ表を削除し、確保したメモリを解放します。
  Deletes the hash table created by mdn_strhash_create and releases the allocated memory.

mdn_strhash_put

      mdn_result_t
      mdn_strhash_put(mdn_strhash_t hash, const char *key,
      	void *value)

  mdn_strhash_create で作成した ハッシュ表 hash にキー key、値 value の組を 登録します。 文字列 key はコピーされますので、この関数の呼び出し後 key の指すメモリを解放しても、文字列の内容を書き換えても 影響はありません。これに対して value の内容はコピーされないので 注意してください (もちろんよく考えてみればコピーされないことは自明ですが)。
  Used to register a key and value set in the hash table created by mdn_strhash_create. Since character strings are copied, there is no influence even if the memory indicated by key is released or the contents of the character strings are changed after this function is called. Contrarily, the contents of value are not copied, so use care when working with this item. (If you think carefully about it, it will become obvious that this value is not copied.)

  同じキーを使用して複数回登録した場合、最後に登録されたものだけが 有効です。
  When the same key is used for registration more than once, only the most recently registered key is effective.

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

mdn_strhash_get

      mdn_result_t
      mdn_strhash_get(mdn_strhash_t hash,
      	const char *key, void **valuep)

  ハッシュ表 hash からキー key を持つ要素を検索し、 対応する要素があればその値を valuep に格納します。
  Searches for elements that have key in the hash table; if a corresponding element is found, the value is stored in valuep.

  返される値は `mdn_success`、 `mdn_noentry` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_noentry`

mdn_strhash_exists

      int
      mdn_strhash_exists(mdn_strhash_t hash, const char *key)

  ハッシュ表 hash にキー key を持つ要素があれば 1を、なければ 0 を返します。
  Returns 1 if there is an element that has the key in the hash table, and returns 0 if no element is found.

### translator モジュール
translator module

translator モジュールは、与えられたパラメータに従ってドメイン名を 変換するモジュールです。パラメータとしては次にあげるデータを与えます。
The translator module converts domain names in accordance with the given parameters. Values can provided for the following parameters.

- 入力として渡すドメイン名のエンコーディング (ローカルエンコーディング)
  Encoding (local encoding) of domain name passed as input
- 入力として渡すドメイン名の代替エンコーディング (ローカル代替エンコーディング)
  Alternate encoding of domain name passed as input (local alternate encoding)
- 入力として渡すドメイン名のZLD (ローカル ZLD)
  ZLD (local ZLD) of domain name passed as input
- 正規化方式 Normalization method
- ドメイン名の変換後のエンコーディング (ターゲットエンコーディング)
  Encoding after conversion of domain name (target encoding)
- ターゲットエンコーディングへの変換が失敗した時に用いるエンコーディング (ターゲット代替エンコーディング)
  Encoding used when conversion to target encoding failed (target alternate encoding)
- ドメイン名の変換後のZLD (ターゲットZLD)
  ZLD after conversion of domain name (target ZLD)

ドメイン名の変換の手続きはやや複雑です。これは次の理由によります。
The domain name conversion procedure is complicated, for the following reasons:

- ドメイン名として常に多言語ドメイン名が渡されるわけではなく、 従来のASCIIドメイン名も渡される可能性があり、 そのどちらであるかによって処理を変える必要があること
  Multilingual domain names are not always passed as the domain name, and it is possible that conventional ASCII domain names may be passed and processing thus must be changed accordingly.
- またこの2つを判別する処理がASCII互換エンコーディングの場合 簡単ではなく、ZLD等を参照する必要があること
  With regard to ASCII-compatible encoding, differentiating between multilingual domain names and conventional ASCII domain names is not simple and ZLD, etc. need to be referenced.
- さらにローカル代替エンコーディングでエンコードされたドメイン名も 渡される可能性があること
  Domain names may be passed that are encoded using local alternate encoding.
- さらにターゲットエンコーディングへの変換が失敗した時には 代替エンコーディングを代わりに使用する必要があること
  If conversion to the target encoding fails, alternate encoding must be used instead.

具体的には、次のようなアルゴリズムを使用して変換を行います。
Specifically, the following algorithm is used for conversion.

1. ローカルZLDが定義されている (空でない) かどうかを調べる。
   Checks if the local ZLD is defined (empty or not).
2. 定義されていれば、渡されたドメイン名がそれにマッチするかどうか調べる。
   If it is defined, checks whether or not the passed domain name matches.
3. マッチすれば多言語ドメイン名だと判断し、ドメイン名からZLDを除去し、 6のコード変換処理へと移る。
   マッチしなければ、従来のASCIIドメイン名だとしてそのまま コピーし、処理を終了する。
   If it matches, the domain name is determined to be a multilingual doman name and ZLD is removed from the domain, then processing proceeds to code conversion processing (Step 6).
4. ローカルZLDが定義されていなければ、ローカルエンコーディングが ASCII互換エンコーディングであるかどうか、また渡されたドメイン名が 従来のASCIIドメイン名として正しいものであるかどうかを調べる。
   When the local ZLD is not defined, checks whether or not the local encoding is ASCII-conpatible and also that the passed domain name is a valid conventional ASCII domain name.
5. もしASCII互換エンコーディングであるか、あるいは渡されたドメイン名に 従来のASCIIドメイン名として正しくない文字が混じっていれば 多言語ドメイン名であるとして6のコード変換処理へと移る。
   それ以外の場合には従来のASCIIドメイン名だとしてそのまま コピーし、処理を終了する。
   When ASCII compatible encoding is used or the passed domain name includes an invalid character in a conventional ASCII domain name, the passed domain name is assumed to be a multilingual domain name and the procedure proceeds to code conversion processing (Step 6).
   For situations other than the above, the passed domain name is assumed to be a conventional ASCII-domain name and is copied as is, then processing ends.
6. ローカル代替エンコーディングが定義されていれば、まず ローカル代替エンコーディングから UTF-8 へとコード変換を実行する。 成功すれば8の正規化処理へと移る。
   When the local alternate encoding is defined, the code is first converted from the local alternate encoding to UTF-8. If this is successful, processing proceeds to normalization processing (Step 8).
7. ローカルエンコーディングからUTF-8へとコード変換を実行する。
   Executes code conversion from local encoding to UTF-8.
8. 正規化処理を実行する。
   Executes normalization processing.
9. UTF-8からターゲットエンコーディングへとコード変換を実行する。
   Executes code conversion from UTF-8 to the target encoding.
10. もしドメイン名にターゲットエンコーディングの文字集合にない文字があって 変換に失敗した場合には、代わりに UTF-8 から代替エンコーディングへの コード変換を実行する。
    If the conversion fails because there is a character in the domain name that is not included in the target character set, code conversion from UTF-8 to the alternate encoding is executed instead.
11. ターゲットZLDが定義されていればドメイン名に追加する。
    When the target ZLD is defined, it is added to the domain name.

以上の処理をフローチャートで表したのが次の図です。
The following flow chart explains the above procedure.

本モジュールはエンコーディング変換に converter モジュールを、また正規化に normalizer モジュールをそれぞれ使用します。
This module uses the converter module for encoding and the normalizer module for normalization.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_translator_translate

      mdn_result_t
      mdn_translator_translate(mdn_converter_t local_converter,
      	mdn_converter_t local_alternate_converter,
      	const char *local_ZLD,
      	mdn_normalizer_t normalizer,
      	mdn_converter_t target_converter,
      	mdn_converter_t target_alternate_converter,
      	const char *target_ZLD,
      	const char *from, char *to, size_t tolen)

  与えられたパラメータにしたがってドメイン名 from を変換し、 結果を to と tolen で指定される領域に格納します。
  Converts the domain name produced by from per the specified parameters and stores the result in the area specified by to and tolen.

  ローカルエンコーディング、ローカル代替エンコーディング、 ターゲットエンコーディングおよびターゲット代替エンコーディングは エンコーディングの名称ではなく、 対応するconverter モジュールの コード変換コンテキスト local_converter、 alternate_converter および target_converter で 指定します。
  Local encoding, local alternate encoding, target encoding and target alternate encoding are not the actual names of types of encoding and are specified by the corresponding code conversion context, which is defined by the following converter module variables: local_converter,alternate_converter and target_converter.

  ターゲット代替エンコーディング target_alternate_converter は、 target_converter によるターゲットエンコーディングへの変換が、 ドメイン名がターゲットエンコーディングの文字集合にない文字を含んでいるために 失敗した時に、ターゲットエンコーディングの代わりに使用されます。
  The target_alternate_converter variable is used instead of the target encoding if conversion to the target encoding by target_converter fails because the domain name contains a character that is not included in the target character set.

  正規化はnormalizer モジュールの正規化コンテキスト normalizer で指定します。
  Normalization is specified by normalization context defined by the normalizer variable of the normalizer module.

  ローカルZLDおよびターゲットZLDは mdn_translator_canonicalZLD で標準形式に変換したものでなければなりません。
  The local ZLD and target ZLD must have been converted to the standard format by mdn_translator_canonicalZLD.

  返される値は `mdn_success`、 `mdn_buffer_overflow`、 `mdn_invalid_encoding`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_buffer_overflow`
  `mdn_invalid_encoding`
  `mdn_nomemory`

mdn_translator_canonicalZLD

      mdn_result_t
      mdn_translator_canonicalZLD(const char *ZLD,
      	char **canonicalizedp)

  ZLD ZLD を標準形式に変換し、そのポインタを canonicalizedp の指す領域に格納します。 変換された文字列 (*canonicalizedp) の領域は malloc() されていますので、不要になったら free() で 解放してください。
  Converts ZLD ZLD to the standard format and stores a pointer in the area specified by canonicalizedp. Since the area for the converted character string (*canonicalizedp) is secured by malloc(), release it when it is no longer needed.

  ここでいう ZLD の標準形式とは次のような形式のものを指します。
  The standard format for ZLD mentioned is as follows:

  - 空のZLD ("" あるいは ".") の標準形式は NULL
    The standard format for empty ZLD ("" or ".") is NULL
  - 先頭がピリオド (.) から始まっていればピリオドを除去
    The period is removed when the beginning is a period (.)
  - 最後がピリオド (.) で終わっていなければピリオドを追加
    A period is added when the ending is not a period (.)
  - 小文字はすべて大文字に変換
    Lowercase characters are all converted to uppercase characters

    返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

    One of the following values is returned:
    `mdn_success`
    `mdn_nomemory`

mdn_translator_matchZLD

      int
      mdn_translator_matchZLD(const char *domain,
      	const char *ZLD)

  ドメイン名 domain と ZLD ZLD がマッチするかどうか を調べ、マッチすれば1を、しなければ0を返します。
  Checks whether or not the domain variable and ZLD ZLD match, and returns a 1 if they match and a 0 if not.

  ZLD は mdn_translator_canonicalZLD で標準形式に変換したものでなければなりません。
  The ZLD must have been converted to the standard format by mdn_translator_canonicalZLD.

### unicode モジュール
unicode module

unicode モジュールは、 UnicodeData.txt に記述されている、Unicode の各種文字属性を取得するモジュールです。なお、 Unicode.txt に記述されているデータの意味、およびファイル形式については UnicodeData File Formatをご覧ください。
The unicode module obtains various character properties of Unicode described in UnicodeData.txt. For details of the data described in Unicode.txt and the file format, refer to UnicodeData File Format.

本ライブラリの多くのモジュールは Unicode のデータを UTF-8エンコードされた 文字列形式で扱いますが、このモジュールは unsigned long 型の データとして扱います。含まれる値は UCS-4 です。
Many modules in this library handle Unicode data as UTF-8 encoded character strings but this module handles Unicode data as unsigned long type data. Includes UCS-4 values.

このモジュールでは Unicode 文字の大文字小文字の相互変換機能も 提供しています。 これは Unicode Technical Report #21: Case Mappings で 定義されているものです。 Unicode 文字の中にはごく一部ですが大文字小文字の変換をする際に 文脈情報を必要とするものがあり、これは次のような列挙型のデータで指定します。
This module provides a mutual conversion function between uppercase and lowercase Unicode characters. This is defined by Unicode Technical Report #21: Case Mappings. Among Unicode characters, a few characters require context information when uppercase is converted to lowercase. This is specified by the following enumeration type data.

>     typedef enum {
>     	mdn__unicode_context_unknown,
>     	mdn__unicode_context_final,
>     	mdn__unicode_context_nonfinal
>     } mdn__unicode_context_t;

文脈が FINAL の場合には `mdn__unicode_context_final` を、また NON_FINAL の場合には `mdn__unicode_context_nonfinal` を指定します。 `mdn__unicode_context_unknown` は文脈情報がわからない (調べていない) ことを示します。 文脈情報に関して詳しくは上記文献をご覧ください。
When the context is FINAL, `mdn__unicode_context_final` is specified and when it is NON_FINAL, `mdn__unicode_context_nonfinal` is specified. `mdn__unicode_context_unknown` indicates that the context is unknown (has not yet been checked). For a detailed discussion of context information, refer to the above references.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn__unicode_canonicalclass

      int
      mdn__unicode_canonicalclass(unsigned long c);

  Unicode 文字 c の Canonical Combining Class を求めます。 Canonical Combining Class が定義されていない文字については 0 を返します。
  Obtains Canonical Combining Class for Unicode character c. 0 is returned for characters for which Canonical Combining Class is not defined.

mdn__unicode_decompose

      mdn_result_t
      mdn__unicode_decompose(int compat,
      	unsigned long *v, size_t vlen,
      	unsigned long c, int *decomp_lenp)

  Unicode 文字 c を UnicodeData.txt のCharacter Decomposition Mapping にしたがって decompose し、その結果を v および vlen で指定される領域に書き込みます。 compat の値が真なら Compatibility Decomposition を、 偽ならCanonical Decomposition を行います。
  decompose は再帰的に行われます。つまりCharacter Decomposition Mappingにしたがって分解した各文字についてさらに decompose 処理が行われます。

  Decomposes Unicode characters c in accordance with Character Decomposition Mapping of UnicodeData.txt and writes the result in the area specified by v and vlen. When the value of compat is true, Compatibility Decomposition is performed and when false, Canonical Decomposition is performed. Decompose is performed recursively, i.e. each character resolved in accordance with Character Decomposition Mapping is further decomposed.

  返される値は `mdn_success`、 `mdn_notfound`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_notfound`
  `mdn_nomemory`

mdn__unicode_compose

      mdn_result_t
      mdn__unicode_compose(unsigned long c1,
      	unsigned long c2, unsigned long *compp)

  c1 と c2 の2文字の Unicode 文字のシーケンスを UnicodeData.txt のCharacter Decomposition Mapping にしたがって compose し、その結果を compp の指す領域に書き込みます。 必ず Canonical Composition が行われます。
  Composes a sequence of the two Unicode characters c1 and c2 per the Character Decomposition Mapping in UnicodeData.txt and writes the result in the area specified by compp. Canonical Composition is always peformed.

  返される値は `mdn_success`、 `mdn_notfound` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_notfound`

mdn__unicode_iscompositecandidate

      int
      mdn__unicode_iscompositecandidate(unsigned long c)

  Unicode文字 c から始まる Canonical Composition が存在するか どうかを調べ、存在する可能性があれば 1 を可能性がなければ 0 を返します。 これはヒント情報であり、1が返ってきたとしても実際には Composition が 存在しないこともあり得ます。逆に 0 が返ってくれば確実に存在しません。
  Checks whether or not Canonical Composition that begins with Unicode character c exists. 1 is returned if existence is possible, and 0 if not. If 1 is returned, it is possible that Composition does not actually exist; however, when 0 is returned, it definitely does not exist.

  Unicode の全文字の中で Canonical Composition の先頭となる文字は数 少ないので、mdn__unicode_compose の検索のオーバヘッドを減らすためにあらかじめデータをスクリーニングする目的に 使用することができます。
  As there are only a small number of Unicode characters that can begin Canonical Composition, this can be used for pre-screening of data in order to decrease the search overhead of mdn__unicode_compose.

mdn__unicode_toupper

      mdn_result_t
      mdn__unicode_toupper(unsigned long c, mdn__unicode_context_t ctx,
      	unsigned long *v, size_t vlen, int *convlenp)

  Unicode文字 c を UnicodeData.txt の Uppercase Mapping 情報および SpecialCasing.txtの情報にしたがって大文字に変換し、結果を v の指す領域に格納します。vlen はあらかじめ v に確保した領域の大きさです。変換結果の文字数は *convlenp に返されます。 変換結果が複数の文字になることがあることに注意してください。 またロケール依存の変換は行いません。
  Converts Unicode characters c to uppercase in accordance with the Uppercase Mapping information in UnicodeData.txt and SpecialCasing.txt, and stores the result in the area specified by v. vlen is the size of the area that is secured for v beforehand. The number of characters in the conversion result is returned to *convlenp. Note that the conversion result may be greater than one character and that locale-dependent conversion is not performed.

  ctx は文字 c の出現する 文脈情報です。 ほとんどの文字では変換の際に文脈情報は不要なため、 通常は `mdn__unicode_context_unknown` を指定しておくことができます。 もし文脈情報が必要な場合、本関数は戻り値として `mdn_context_required` を返すので、文脈情報を取得してから改めて呼び出すことが可能です。 文脈情報の取得には mdn__unicode_getcontext を使用します。
  ctx is context information where character c appears. Since most characters do not require context information when they are converted, usually `mdn__unicode_context_unknown` can be specified. When context information is necessary, this function returns `mdn_context_required` as the return value, and it is possible to call it again after obtaining the context information. To obtain context information, mdn__unicode_getcontext is used.

  もし対応する大文字が存在しない場合には c がそのまま v に格納されます。
  If no corresponding uppercase character exists, c is stored in v as is.

  返される値は `mdn_success`、 `mdn_context_required`、 `mdn_buffer_overflow` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_context_required`
  `mdn_buffer_overflow`

mdn__unicode_tolower

      mdn_result_t
      mdn__unicode_tolower(unsigned long c, mdn__unicode_context_t ctx,
      	unsigned long *v, size_t vlen, int *convlenp)

  Unicode文字 c を UnicodeData.txt の Uppercase Mapping 情報および SpecialCasing.txtの情報にしたがって小文字に変換し、結果を v の指す領域に格納します。vlen はあらかじめ v に確保した領域の大きさです。変換結果の文字数は *convlenp に返されます。 変換結果が複数の文字になることがあることに注意してください。 またロケール依存の変換は行いません。
  Converts Unicode character c to lowercase in accordance with Uppercase Mapping information of UnicodeData.txt and SpecialCasing.txt information, and stores the result in the area specified by v. vlen is the size of area that is secured for v beforehand. The number of characters of the conversion result is returned to *convlenp.

  ctx は文字 c の出現する 文脈情報です。 ほとんどの文字では変換の際に文脈情報は不要なため、 通常は `mdn__unicode_context_unknown` を指定しておくことができます。 もし文脈情報が必要な場合、本関数は戻り値として `mdn_context_required` を返すので、文脈情報を取得してから改めて呼び出すことが可能です。 文脈情報の取得には mdn__unicode_getcontext を使用します。
  ctx is context information where character c appears. Since most characters do not require context information when they are converted, usually `mdn__unicode_context_unknown` can be specified. When context information is necessary, this function returns `mdn_context_required` as the return value, and it is possible to call it again after obtaining the context information. To obtain context information, mdn__unicode_getcontext is used.

  もし対応する小文字が存在しない場合には c がそのまま v に格納されます。
  If no corresponding uppercase character exists, c is stored in v as is.

  返される値は `mdn_success`、 `mdn_context_required`、 `mdn_buffer_overflow` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_context_required`
  `mdn_buffer_overflow`

mdn__unicode_getcontext

      mdn__unicode_context_t
      mdn__unicode_getcontext(unsigned long c)

  大文字小文字変換で用いられる文脈情報を返します。 文脈情報を取得するには次のようにします。 まず大文字小文字変換の対象文字に続く次の文字を取得し、この関数を 呼び出します。もし返される値が `mdn__unicode_context_final` あるいは `mdn__unicode_context_nonfinal` のいずれかであれば それが求める文脈情報です。 `mdn__unicode_context_unknown` の場合にはさらに続く文字を取得し、 この関数を呼び出します。このようにして `mdn__unicode_context_final` か `mdn__unicode_context_nonfinal` かいずれかの値が得られるまで 処理を繰り返します。もし文字列の最後まで来た場合には、文脈は`mdn__unicode_context_final` となります。
  Returns context information used for conversion of uppercase/lowercase characters. To obtain context information, first the character following the uppercase/lowercase character conversion target character is obtained and this function is called. If the return value is `mdn__unicode_context_final` or `mdn__unicode_context_nonfinal`, that context information is the context information to obtain. If `mdn__unicode_context_unknown` is returned, the next character is obtained and the function is called. In this way, processing continues until either the value of `mdn__unicode_context_final` or `mdn__unicode_context_nonfinal` is obtained. When processing reaches the end of the character string, `mdn__unicode_context_final` becomes the context.

  具体的にはこの関数は次のような処理を行います。 Unicode 文字 c の "General Category" 属性を参照し、 それが "Lu" "Ll" "Lt" のいずれかであれば `mdn__unicode_context_nonfinal` を、"Mn" であれば `mdn__unicode_context_unknown` を、それ以外であれば `mdn__unicode_context_final` を返します。
  Specifically, this function does the following. Refers "General Category" properties of Unicode character c and if it is "Lu", "Ll" or "Lt" `mdn__unicode_context_nonfinal` is returned, if it is "Mn" `mdn__unicode_context_unknown` is returned, and if it is other than the above, `mdn__unicode_context_final` is returned.

### unormalize モジュール
unormalize module

unormalize モジュールは、Unicode で定義されている標準の正規化を 行うモジュールです。Unicode の正規化は Unicode Technical Report #15: Unicode Normalization Forms で定義されています。本モジュールはこの文書にあげられた4つの正規化形式を 実装しています。
The unormalize module performs the standard normalization defined by Unicode. Normalization of Unicode is defined in Unicode Technical Report #15: Unicode Normalization Forms. This module implements the four normalization forms mentioned in this document.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn__unormalize_formc

      mdn_result_t
      mdn__unormalize_formc(const char *from, char *to, size_t tolen)

  UTF-8でエンコードされた文字列 from に対して 正規化 Unicode Normalization Form C を適用し、その結果を to および tolen で指定される領域に書き込みます。
  Applies Unicode Normalization Form C normalization to a UTF-8 encoded from character string and writes the result in the area specified by to and tolen.

  返される値は `mdn_success`、 `mdn_invalid_encoding`、 `mdn_buffer_overflow`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_invalid_encoding`
  `mdn_buffer_overflow`
  `mdn_nomemory`

mdn__unormalize_formd

      mdn_result_t
      mdn__unormalize_formd(const char *from, char *to, size_t tolen)

  UTF-8でエンコードされた文字列 from に対して 正規化 Unicode Normalization Form D を適用し、その結果を to および tolen で指定される領域に書き込みます。
  Applies Unicode Normalization Form D normalization to a UTF-8 encoded from character string and writes the result in the area specified by to and tolen.

  返される値は `mdn_success`、 `mdn_invalid_encoding`、 `mdn_buffer_overflow`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_invalid_encoding`
  `mdn_buffer_overflow`
  `mdn_nomemory`

mdn__unormalize_formkc

      mdn_result_t
      mdn__unormalize_formkc(const char *from, char *to, size_t tolen)

  UTF-8でエンコードされた文字列 from に対して 正規化 Unicode Normalization Form KC を適用し、その結果を to および tolen で指定される領域に書き込みます。
  Applies Unicode Normalization Form KC normalization to a UTF-8 encoded from character string and writes the result in the area specified by to and tolen.

  返される値は `mdn_success`、 `mdn_invalid_encoding`、 `mdn_buffer_overflow`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_invalid_encoding`
  `mdn_buffer_overflow`
  `mdn_nomemory`

mdn__unormalize_formkd

      mdn_result_t
      mdn__unormalize_formkd(const char *from, char *to, size_t tolen)

  UTF-8でエンコードされた文字列 from に対して 正規化 Unicode Normalization Form KD を適用し、その結果を to および tolen で指定される領域に書き込みます。
  Applies Unicode Normalization Form KC normalization to a UTF-8 encoded from character string and writes the result in the area specified by to and tolen.

  返される値は `mdn_success`、 `mdn_invalid_encoding`、 `mdn_buffer_overflow`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_invalid_encoding`
  `mdn_buffer_overflow`
  `mdn_nomemory`

### utf5 モジュール
utf5 module

utf5 モジュールはドメイン名のエンコーディング方式の一つとして 提案されている UTF-5 エンコーディング の基本処理を行うモジュールです。
The utf5 module performs basic processing for the proposed UTF-5 domain name encoding system.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_utf5_getwc

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

  UTF-5でエンコードされた長さ len バイトの文字列 s の 先頭の文字を取り出し、UCS-4 に変換して vp の指す領域に格納すると ともに、文字の (UTF-5エンコードでの) バイト数を返します。 もし len が短すぎて文字の途中で終わっていたり、エンコーディングが 間違っている場合には 0 が返されます。
  Extracts the leading character of length len byte UTF-5 encoded character string s, converts it to UCS-4 and stores it in the area specified by vp and also returns the number of bytes in the (UTF-5 encoded) character strintg. 0 is returned if len is too short and ends in the middle of a character or the encoding is invalid.

mdn_utf5_putwc

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

  UCS-4 文字 v をUTF-5エンコーディングに変換し、s および len で指定される領域に書き込むとともに、書き込んだバイト数を 返します。ただし len が短すぎて書き込めない場合には0を返します。
  Converts UCS-4 characters v to UTF-5 encoding, writes them in the area specified by s and len and returns the number of bytes written. 0 is returned if len is too short to write.

  書き込んだUTF-5文字列はNULL 文字で終端されていません。
  The written UTF-5 character string is not terminated with a NULL character.

### utf8 モジュール
utf8 module

utf8 モジュールはUTF-8 でエンコードされた文字列の基本処理を行う モジュールです。
The utf8 module performs the basic processing of UTF-8 encoded character strings.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_utf8_mblen

      int
      mdn_utf8_mblen(const char *s)

  UTF-8 文字列 s の先頭文字の長さ(バイト数)を返します。 もし s が指すバイトが UTF-8 の先頭バイトとして正しくないものである 場合には 0 を返します。
  Returns the length (number of bytes) of the leading character in the UTF-8 character string s. 0 is returned if the leading byte indicated by s is not valid for UTF-8.

  この関数は s の先頭バイトのみを調べて長さを返します。したがって 2バイト目以降に不正なバイトがある可能性が存在します。特に途中に NULL バイトが ある可能性もあるので、s が正当な UTF-8 文字列であることが確実では ない場合には気をつける必要があります。
  This function returns the length by checking the leading byte of s; there is therefore a possibility of invalid byte in the 2nd and later byte. In particular, NULL bytes may exist in the middle, so you have to be careful when it is not certain that s is a valid UTF-8 character string.

mdn_utf8_getmb

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

  長さ len バイトの UTF-8 文字列 s の先頭の1文字をbuf にコピーし、コピーしたバイト数を返します。もし len が短すぎたり、s が指す文字が UTF-8 として正しくない場合にはコピーは行わず、0 を返します。
  Copies the leading character of s UTF-8 character strings of length len and returns the number of copied bytes.

  buf は任意の UTF-8 エンコーディングの文字が保持できる大きさ でなければなりません。すなわち、6バイト以上の長さを持っている必要があります。
  buf must be large enough to hold any UTF-8 encoding, i.e. it must be 6 bytes or larger.

  書き込んだUTF-8文字列は NULL 文字で終端されていません。
  The written UTF-8 character string is not terminated with a NULL character.

mdn_utf8_getwc

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

  mdn_utf8_getmb とほぼ同じですが、 s から取り出した文字を UCS-4に変換して vp の指す領域に格納するところが異なります。
  This is almost same as mdn_utf8_getmb with the difference being that characters extracted from s are converted to UCS-4 and stored in the area indicated by vp.

mdn_utf8_putwc

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

  UCS-4 文字 v を UTF-8 エンコーディングに変換して、 s および len で指定される領域に書き込むとともに、 書き込んだバイト数を返します。v の値が不正であったり len が短すぎた場合には 0 を返します。
  Converts UCS-4 character v to UTF-8 encoding, writes it in the area specified by s and len and returns the number of written bytes. 0 is returned when the value of v is invalid or len is too short.

  書き込んだUTF-8文字列は NULL 文字で終端されていません。
  The written UTF-8 character string is not terminated with a NULL character.

mdn_utf8_isvalidstring

      int
      mdn_utf8_isvalidstring(const char *s)

  NULL 文字で終端された文字列 s が正しい UTF-8 エンコーディング であるかどうか調べ、正しければ 1 を、正しくなければ 0 を返します。
  Checks whether or not character string s terminated with a NULL character is valid UTF-8 encoding and returns 1 if so and 0 if not.

mdn_utf8_findfirstbyte

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

  文字列 known_top 中の s が指すバイトを含む UTF-8 文字の先頭バイトを調べて返します。その文字が正しい UTF-8 エンコーディングではない場合、known_top から s までの 間に先頭バイトがなかった場合には NULL を返します。
  In the character string known_top, checks the leading byte of UTF-8 characters including the byte indicated by s and returns it. NULL is returned if there are any incorrectly encoded UTF-8 characters or there is no leading byte between known_top and s.

### util モジュール util module

util モジュールは他のモジュールで使われるユーティリティー的な 機能を提供するモジュールです。 現在のところは大文字小文字の区別をしない文字列照合の機能のみを 提供しています。
The util module provides utility type functions used by other modules. The only function currently provided is a character string collation function that does not differentiate between uppercase and lowercase characters.

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_util_casematch

      int
      mdn_util_casematch(const char *s1, const char *s2, size_t n)

  文字列 s1 と s2 の先頭から最大 n バイトを 比較し、同一かどうかを判定します。 ASCII 文字の大文字と小文字 (つまり A から Z と a から z) は同一とみなします。 同一であれば 1 を、違っていれば 0 を返します。 これは多くのシステムで用意されている strcasencmp と返り値の仕様を 除けばほぼ同様の機能を提供する関数です。
  Compares the maximum n bytes from the beginning of character strings s1 and s2 and determines whether or not they are identical. Uppercase and lowercase ASCII characters (i.e. A to Z and a to z) are assumed to be the same. 1 is returned if they are found to be identical and 0 is returned if not. With the exception of the return value specifications, this function provides almost the same features as strcasencmp, which is provided in many systems.

### ZLDrule モジュール ZLDrule module

ZLDrule モジュールはドメイン名と ZLD とのマッチングを行うモジュールです。 ドメイン名に使用される可能性のある ZLD のリストとそれぞれの ZLD に対応した エンコーディングのリストを持ち、与えられたドメイン名とのマッチングを行って マッチした ZLD とエンコーディングを返します。
The ZLDrule module matches the domain name and ZLD. It has a list of ZLDs that are probably used for domain names and the list of encodings corresponding to each ZLD, and performs matching with the given doman name, then returns the matched ZLD and encoding.

ZLDrule モジュールはマッチングのために「コンテキスト」という概念を用います。 マッチングに先立ってまずコンテキストを作成し、それに対して ZLD とエンコーディングを登録していきます。 そして実際にドメイン名とマッチングを行う際にはこのコンテキストを用いて マッチングに使用するZLD とエンコーディングのリストを指定します。 コンテキストの型は mdn_ZLDrule_t 型であり、次のような opaque 型として定義されています。
The ZLDrule module uses "context" concept for matching. Prior to matching, a context is created and ZLD and encoding are registered for the context. When domain name matching is performed, this context is used to specify the ZLD and encoding lists used for matching. The type of context is mdn_ZLDrule_t and is defined as the following opaque type.

>     typedef struct mdn_ZLDrule *mdn_ZLDrule_t;

以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.

mdn_ZLDrule_create

      mdn_result_t
      mdn_ZLDrule_create(mdn_ZLDrule_t *ctxp)

  ZLDのマッチングを行うためのコンテキストを作成し、 ctxp の指す領域に格納します。
  Creates a context for ZLD matching and stores it in the area indicated by ctxp.

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

mdn_ZLDrule_destroy

      void
      mdn_ZLDrule_destroy(mdn_ZLDrule_t ctx)

  mdn_ZLDrule_create で作成した コンテキスト ctx を削除し、確保したメモリを解放します。
  Deletes the context created by mdn_ZLDrule_create and releases the allocated memory.

mdn_ZLDrule_add

      mdn_result_t
      mdn_ZLDrule_add(mdn_ZLDrule_t ctx, const char *ZLD,
      	const char **encodings, int nencodings)

  mdn_ZLDrule_create で作成した コンテキスト ctx に、ZLD ZLD と encodings および nencodings で指定される エンコーディングリストの組を登録します。
  Registers the ZLD and encoding list set specified by encodings and nencodings in context ctx created by mdn_ZLDrule_create.

  空の ZLD、つまり "" や "." は任意のドメイン名にマッチします。 したがってZLDとして空の値を指定することによって、いずれの ZLD にもマッチしなかった場合のデフォルトのエンコーディングを指定することが 可能です。
  Empty ZLDs such as "" or "." match all domain names, therefore, by specifying an empty value for ZLD the default encoding can be specified in those cases in which no ZLD match is found.

  返される値は `mdn_success`、 `mdn_nomemory` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_nomemory`

mdn_ZLDrule_select

      mdn_result_t
      mdn_ZLDrule_select(mdn_ZLDrule_t ctx, const char *domain,
      	char **ZLDp, mdn_converter_t *convctxp)

  コンテキスト ctx に含まれている ZLD のリストと ドメイン名 domain とのマッチングを試みます。マッチングは ZLDが長い (ZLD を構成するラベルの数が多い) ものから順に行われます。
  Attempts to match the ZLD list contained in context ctx and domain name domain. Matching is executed starting from the longest ZLD (a ZLD consisting of many labels).

  マッチするZLDがあった場合、ZLDp の指す領域に、マッチした ZLD へのポインタが格納されます。返されるポインタはすでに mdn_translator_canonicalZLD によって標準形式になっているので、そのまま mdn_translator_translate への 引数として渡すことができます。
  When a ZLD match is found, the pointer to the ZLD match is stored in the area specified by ZLDp. Since the return pointer has already been converted to the standard form by mdn_translator_canonicalZLD, it can be passed as the argument as is.

  マッチしたZLD に対応するエンコーディングが一つだけなら、そのエンコーディング に対応するコード変換コンテキストが convctxp の指す領域に 格納されます。 対応するエンコーディングが複数あれば、リストの先頭から順に domain がそのエンコーディングとして正しいかどうかを調べます。 もし正しいものがあれば、最初に見つかったもののコード変換コンテキストが convctxp の指す領域に格納されます。正しいものがなければ convctxp には何も書き込まれず、`mdn_invalid_encoding`が 返されます。
  When only one encoding method corresponds to the matched ZLD, the code conversion context corresponding to that encoding method is stored in the area specified by convctxp. If there is more than one valid encoding method, a check is performed from the top of the list to determine whether or not domain is valid for the encoding. Of the valid encoding methods found, the code conversion context of the first one found is stored in the area specified by convctxp. If no valid encoding method is found, nothing is written in convctxp and `mdn_invalid_encoding` is returned.

  マッチする ZLD がなければ `mdn_notfound`を返して処理を終了します。
  When there is no ZLD match, `mdn_notfound` is returned and processing ends.

  返される値は `mdn_success`、 `mdn_notfound`、 `mdn_invalid_encoding` のいずれかです。

  One of the following values is returned:
  `mdn_success`
  `mdn_notfound`
  `mdn_invalid_encoding`