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.
文字列のエンコーディングを変換し、その結果を返します。
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.
エンコーディングは大きく分けて、次の2種類があります。
Encoding is roughly divided into the following two types.
このモジュールでは前者のエンコーディング変換のために
iconv() ユーティリティを使用し、後者のエンコーディング変換のためには
独自の変換関数を実装して使用しています。
This module uses the iconv() utility for the first encoding conversion process and implements a unique conversion function for the latter encoding conversion.
与えられた文字列を正規化します。標準では次にあげる正規化をサポートします。
Normalizes given character strings. The following standard normalization functions are supported.
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:
多言語ドメイン名を識別するために ZLD を必要とする方式のために、ZLD に
関する以下の機能を提供します。
To identify multilingual domain names, the following ZLD-related functions are provided:
アプリケーションプログラムが使用しているローカルエンコーディング
(コードセット) を自動判別します。判別は基本的にはアプリケーションのロケール
情報を利用しますが、環境変数で指定することも可能になっています。
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.
アプリケーションにリンクされるリゾルバライブラリでエンコーディング
変換や正規化を行う場合、使用するエンコーディングや正規化方式は
設定ファイルに記述されます。このファイルを読み込む機能を提供します。
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.
MDN ライブラリは以下のモジュールから構成されます。
The MDN library consists of the following modules.
以下にモジュールの呼び出し関係図を示します。ただしほとんどすべての
モジュールから呼び出されている 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.
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.
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.
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_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_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_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 モジュールは、文字列のエンコーディング(コードセット)を
変換します。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.
また、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_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_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
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_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.
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
char * mdn_converter_localencoding(mdn_converter_t ctx)
コード変換コンテキスト ctx のローカルエンコーディング名を
返します。
Returns the local encoding name of the code conversion context ctx.
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_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_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_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_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 モジュールはデバッグ用出力のためのユーティリティモジュールです。
The debug module is a utility module for debug output.
以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.
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.
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.
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.
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 モジュールは、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_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
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_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 エンコーディング
と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_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_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_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 モジュールはロケール情報を利用して、
アプリケーションの使用しているエンコーディングを推測するモジュールです。
The localencoding module uses locale information to guess the encoding used by the application.
以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.
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 モジュールは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.
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.
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.
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.
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.
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.
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.
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.
int mdn_log_getlevel(void)
現在のログ出力のレベルを表す整数値を取得して返します。
Obtains and returns the integer value for the current level of log output.
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.
level にはログのレベルが、また msg には表示すべき メッセージ文字列が渡されます。typedef void (*mdn_log_proc_t)(int level, const char *msg);
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_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_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
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.
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 モジュールは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.
次にDNSサーバからクライアントへのメッセージの変換の場合は次の
ようになります。
Conversion of messages from the DNS server to the client is as follows.
このように、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_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 モジュールは文字列の正規化を行うモジュールです。
正規化の方式としては現在次のものが用意されています。
また別の新たな正規化方式を追加登録するための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.
最後の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_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_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
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_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_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_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 エンコーディング
と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_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_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_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 モジュールはクライアント側 (リゾルバライブラリやアプリケーション)
で多言語ドメイン名の処理、つまりドメイン名のエンコーディング変換や
正規化を行う際の高レベル 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_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_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_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_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_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 モジュールはクライアント側 (リゾルバライブラリやアプリケーション)
で多言語ドメイン名の処理を行う際に参照される
クライアント設定ファイルを読み込み、
ファイルに記述された設定にしたがった初期化を実行します。また
設定情報を取り出す機能を提供します。
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_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_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
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_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
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_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_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_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.
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_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 モジュールはライブラリの各関数が返す
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 モジュールはゾーンマスタファイル等のテキストの中から
非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.
具体的には次のようなアルゴリズムを用いてドメイン名の領域検出を行います。
Specifically, the following algorithm is used to detect the domain name area.
以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.
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 モジュールは文字列をキーとするハッシュ表を実現するモジュールです。
ハッシュ表は
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_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
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_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_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
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 モジュールは、与えられたパラメータに従ってドメイン名を
変換するモジュールです。パラメータとしては次にあげるデータを与えます。
The translator module converts domain names in accordance with the given parameters. Values can provided for the following parameters.
ドメイン名の変換の手続きはやや複雑です。これは次の理由によります。
The domain name conversion procedure is complicated, for the following reasons:
具体的には、次のようなアルゴリズムを使用して変換を行います。
Specifically, the following algorithm is used for conversion.
以上の処理をフローチャートで表したのが次の図です。
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_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_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:
返される値は mdn_success、 mdn_nomemory のいずれかです。
One of the following values is returned:
mdn_success
mdn_nomemory
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 モジュールは、
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 は文脈情報がわからない (調べていない)
ことを示します。
文脈情報に関して詳しくは上記文献をご覧ください。以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.
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_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_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
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_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_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_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 モジュールは、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_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_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_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_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 モジュールはドメイン名のエンコーディング方式の一つとして
提案されている
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.
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.
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 モジュールはUTF-8 でエンコードされた文字列の基本処理を行う
モジュールです。
The utf8 module performs the basic processing of UTF-8 encoded character strings.
以下にモジュールの提供するAPI関数を示します。
This module provides the following API functions.
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.
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.
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.
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.
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.
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 モジュールは他のモジュールで使われるユーティリティー的な
機能を提供するモジュールです。
現在のところは大文字小文字の区別をしない文字列照合の機能のみを
提供しています。
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.
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 モジュールはドメイン名と 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_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
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_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_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