.\" $Id: libmdn.3.in,v 1.5.2.3 2002/02/20 05:27:51 m-kasahr Exp $
.\"
.\" Copyright (c) 2001 Japan Network Information Center.  All rights reserved.
.\"  
.\" By using this file, you agree to the terms and conditions set forth bellow.
.\" 
.\" 			LICENSE TERMS AND CONDITIONS 
.\" 
.\" The following License Terms and Conditions apply, unless a different
.\" license is obtained from Japan Network Information Center ("JPNIC"),
.\" a Japanese association, Kokusai-Kougyou-Kanda Bldg 6F, 2-3-4 Uchi-Kanda,
.\" Chiyoda-ku, Tokyo 101-0047, Japan.
.\" 
.\" 1. Use, Modification and Redistribution (including distribution of any
.\"    modified or derived work) in source and/or binary forms is permitted
.\"    under this License Terms and Conditions.
.\" 
.\" 2. Redistribution of source code must retain the copyright notices as they
.\"    appear in each source code file, this License Terms and Conditions.
.\" 
.\" 3. Redistribution in binary form must reproduce the Copyright Notice,
.\"    this License Terms and Conditions, in the documentation and/or other
.\"    materials provided with the distribution.  For the purposes of binary
.\"    distribution the "Copyright Notice" refers to the following language:
.\"    "Copyright (c) Japan Network Information Center.  All rights reserved."
.\" 
.\" 4. Neither the name of JPNIC may be used to endorse or promote products
.\"    derived from this Software without specific prior written approval of
.\"    JPNIC.
.\" 
.\" 5. Disclaimer/Limitation of Liability: THIS SOFTWARE IS PROVIDED BY JPNIC
.\"    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\"    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
.\"    PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL JPNIC BE LIABLE
.\"    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\"    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\"    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\"    BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\"    WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\"    OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\"    ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
.\" 
.\" 6. Indemnification by Licensee
.\"    Any person or entities using and/or redistributing this Software under
.\"    this License Terms and Conditions shall defend indemnify and hold
.\"    harmless JPNIC from and against any and all judgements damages,
.\"    expenses, settlement liabilities, cost and other liabilities of any
.\"    kind as a result of use and redistribution of this Software or any
.\"    claim, suite, action, litigation or proceeding by any third party
.\"    arising out of or relates to this License Terms and Conditions.
.\" 
.\" 7. Governing Law, Jurisdiction and Venue
.\"    This License Terms and Conditions shall be governed by and and
.\"    construed in accordance with the law of Japan. Any person or entities
.\"    using and/or redistributing this Software under this License Terms and
.\"    Conditions hereby agrees and consent to the personal and exclusive
.\"    jurisdiction and venue of Tokyo District Court of Japan.
.\"
.TH libmdn 3 "Apr 23, 2001"
.\"
.SH NAME
libmdn, libmdnlite \- Mulitilingual Domain Name Handling Libraries
.\"
.SH SYNOPSIS
.nf
#include <mdn/api.h>

mdn_result_t
\fBmdn_nameinit\fP(void)

mdn_result_t
\fBmdn_encodename\fP(int\ actions,\ const\ char\ *from,\ char\ *to,\ size_t\ tolen)

mdn_result_t
\fBmdn_decodename\fP(int\ actions,\ const\ char\ *from,\ char\ *to,\ size_t\ tolen)

mdn_result_t
\fBmdn_enable\fP(int\ on_off)

char *
\fBmdn_result_tostring\fP(mdn_result_t\ result)

.\"
.SH OVERVIEW
The
.B libmdn
and
.B libmdnlite
libraries support various manipulations of multilingual domain names,
including:
.RS 2
.IP \- 2
encoding convesion
.IP \- 2
name preparation
.RE
.PP
They are designed according to IDNA framework where each application must
do necessary preparations for the multilingual domain names before passing
them to the resolver.
.PP
To help applications do the preparation, the libraries provide easy-to-use,
high-level interface for the work.
.PP
Both libraries provide almost the same API.
The difference between them is that
.B libmdn
internally uses
.I iconv
function to provide encoding conversion from UTF-8 to the local encoding
(such as iso-8859-1, usually determined by the current locale), and vise
versa.
.B libmdnlite
is lightweight version of libmdn.
It assumes local encoding is UTF-8 so that it never uses
.IR iconv .
.PP
This manual describes only a small subset of the API that the libraries
provide, most important functions for application programmers.
For other API, please refer to the mDNkit's specification document
(which is not yet available) or the header files typically found under
`/usr/local/include/mdn/' on your system.
.\"
.SH DESCRIPTION
.PP
The
.B mdn_nameinit
function initializes the whole library, and reads the default
configuration file
.BR mdn.conf ,
which includes configuration parameters for multilingual domain name
preparation.
If
.B mdn_nameinit
is called more than once, the library initialization will take place
only at the first call while the configuration file will be (re)read
at every call.
.PP
If there are no errors,
.B mdn_nameinit
returns
.BR mdn_success .
Otherwise, the returned value indicates the cause of the error.
See the section ``RETURN VALUES'' below for the error codes.
.PP
Usually you don't have to call this function explicitly because
it is implicitly called when
.B mdn_encodename
or
.B mdn_decodename
is first called without prior calling of
.BR mdn_nameinit .
.\"
.PP
.B mdn_encodename
function performs name preparation and encoding conversion on
the multilingual domain name specified by
.IR from ,
and stores the result to
.IR to ,
whose length is specified by 
.IR tolen .
.I actions
is a bitwise-OR of the following macros, specifying which subprocesses
in the encoding process are to be employed.
.RS 2
.nf
.ft CW
MDN_LOCALCONV     Local encoding <-> UTF-8 conversion
MDN_DELIMMAP      Delimiter mapping
MDN_LOCALMAP      Local mapping
MDN_NAMEPREP      NAMEPREP
                  (inculding unassigned codepoint check)
MDN_IDNCONV       UTF-8 <-> ACE conversion
.ft R
.fi
.RE
.PP
Details of this encoding process can be found in the section ``NAME ENCODING''.
.PP
For ordinary application, also the
.B MDN_ENCODE_APP
macro is provided for the convenience.
It is eqivalent to 
.RS 2
.nf
.ft CW
MDN_LOCALCONV|MDN_DELIMMAP|MDN_LOCALMAP|MDN_NAMEPREP|MDN_IDNCONV
.ft R
.fi
.RE
.PP
in libmdn, and eqivalent to
.RS 2
.nf
.ft CW
MDN_DELIMMAP|MDN_LOCALMAP|MDN_NAMEPREP|MDN_IDNCONV
.ft R
.fi
.RE
.PP
in libmdnlite.
.PP
.B mdn_decodename
function performs the reverse of
.BR mdn_encodename .
It converts the multilingual domain name given by
.IR from ,
which is represented in a special encoding called ACE,
to the application's local codeset and stores into
.IR to ,
whose length is specified by
.IR tolen .
.I actions
specifies which subprocesses in decoding process take place, as in
.BR mdn_encodename ,
except that only \f(CWMDN_IDNCONV\fP, \f(CWMDN_NAMEPREP\fP and
\f(CWMDN_LOCALCONV\fP are allowed.
Details of this decoding process can be found in the section ``NAME DECODING''.
.PP
For ordinary application, also the
.B MDN_DECODE_APP
macro is provided for the convenience.
It is eqivalent to 
.RS 2
.nf
.ft CW
MDN_IDNCONV|MDN_NAMEPREP|MDN_LOCALCONV
.ft R
.fi
.RE
.PP
in libmdn, and eqivalent to
.RS 2
.nf
.ft CW
MDN_IDNCONV|MDN_NAMEPREP
.ft R
.fi
.RE
.PP
in libmdnlite.
.PP
All of the functions above return error code of type
.BR mdn_result_t .
All codes other than
.B mdn_success
indicates some kind of failure.
.B mdn_result_tostring
function takes an error code
.I result
and returns a pointer to the corresponding message string.
.\"
.SH "NAME ENCODING"
Name encoding is a process that transforms the specified
multilingual domain name to a certain string suitable for name
resolution.
The name encoding process consists of the following steps.
.IP "(1) Encoding Conversion (local codeset to UCS)"
Convert the encoding of the given domain name to
Unicode/ISO10646 UTF-8 format string.
.br
This step is performed if
.I actions
given to
.B mdn_encodename
contains
.B MDN_LOCALCONV
or equals to
.BR MDN_ENCODE_APP .
Note that libmdnlite doesn't support this step.
.br
The source encoding must be one of the two encodings below:
.RS 2
.IP \- 2
The application's local encoding (codeset).
.IP \- 2
ACE specified by the configuration file.
.RE
The latter is suppored because name decoding process may produce
ACE strings when its attempt to convert to the local encoding fails.
See the section ``NAME DECODING'' for details.
.IP "(2) Local mapping"
Apply any locale/language-specific mapping.  This process is
further divided into two subprocesses:
.RS 2
.IP "(2-1) Delimiter mapping"
Map certain characters to the domain name delimiter (U+002E).
This step is performed if
.I actions
given to
.B mdn_encodename
contains
.B MDN_DELIMMAP
or equals to
.BR MDN_ENCODE_APP .
.IP "(2-2) Local mapping based on TLD"
Apply character mapping whose rule is determined by the TLD of the name.
.br
This step is performed if
.I actions
given to
.B mdn_encodename
contains
.B MDN_LOCALMAP
or equals to
.BR MDN_ENCODE_APP .
.RE
.IP "(3) NAMEPREP"
Perform name preparation (NAMEPREP), which is a standard process for
name canonicalizaion of multilingual domain names.
.B mdn_encodename
performs mapping, normalization, prohibited character check and
unassigned codepoint check in that order, as NAMEPREP mentions.
.br
This process includes checking of characters which are not allowed in
multilingual domain names.
This step is performed if
.I actions
given to
.B mdn_encodename
contains
.B MDN_NAMEPREP
or equals to
.BR MDN_ENCODE_APP .
.IP "(4) Encoding conversion (UCS to ACE)"
Convert the NAMEPREPed name to a special encoding designed for representing
multilingual domain names.
.br
The encoding is also known as ACE (ASCII Compatible Encoding) since
a string in the encoding is just like a traditional ASCII domain name
consisting of only letters, numbers and hyphens.
This step is performed if
.I actions
given to
.B mdn_encodename
contains
.B MDN_IDNCONV
or equals to
.BR MDN_ENCODE_APP .
.PP
There are many configuration parameters for this process, such as the
ACE or the local mapping rules.  These parameters are read from the
default mDNkit's configuration file,
.BR mdn.conf .
See mdn.conf(5) for details.
.\"
.SH "NAME DECODING"
Name decoding is a reverse process of the name encoding.
It transforms the specified
multilingual domain name in a special encoding suitable for name
resolution to the normal name string in the application's current codeset.
However, name encoding and name decoding are not symmetric.
Name decoding doesn't perform local mapping.
Both name encoding and decoding do NAMEPREP, but decoding does
it to verfiy a name, while encoding does it to normalize a name.
.PP
The name decoding process consists of the following steps.
.IP "(1) Encoding conversion (ACE to UCS)"
Convert the encoding of the given domain name
from a special one designed for representing
multilingual domain names (ACE) to Unicode/ISO10646 UTF-8.
This step is performed if
.I actions
given to
.B mdn_decodename
contains
.B MDN_IDNCONV
or equals to
.BR MDN_DECODE_APP .
.IP "(2) NAMEPREP check"
Perform name preparation (NAMEPREP) as also done in name encoding,
and compare the result of NAMEPREP and the given UCS name.
If the NAMEPREP is failed or the names are different, the given
name is considered as invalid domain name.
It contains a character which is never seen in a NAMEPREPed domain
name.
This step is performed if
.I actions
given to
.B mdn_decodename
contains
.B MDN_NAMEPREP
or equals to
.BR MDN_DECODE_APP .
.IP "(3) Encoding conversion (UCS to local codeset)"
Convert the encoding of the name from UTF-8 to
the application's local codeset.
.br
The local codeset is determined by the application's locale.
However, it is possible that the conversion to the application's
local codeset fails because the name includes some characters
which don't have mappings to the local codeset.
In this case, libmdn tries instead to convert to ACE specified by
the configuration file.  
.br
This step is performed if
.I actions
given to
.B mdn_decodename
contains
.B MDN_LOCALCONV
or equals to
.BR MDN_DECODE_APP .
Note that libmdnlite doesn't support this step.
.PP
The configuration parameters for this process,
are also read from the configuration file
.BR mdn.conf .
.\"
.SH "MDN_DISABLE"
If the
.BR MDN_DISABLE
environ variable is defined at run-time,
the libraries disable mulitilingual domain name support, by default.
In this case,
.B mdn_encodename
and 
.B mdn_decodename
don't encode/decode an input name, but instead they simply ouput a
copy of the input name as the result of encoding/decoding.
.PP
If your application should always enable mulitilingual domain name
support regardless of definition of
.BR MDN_DISABLE ,
call
.RS 4
.nf
.ft CW
mdn_enable(1)
.ft R
.fi
.RE
before performing encoding/decoding. 
.\"
.SH "RETURN VALUES"
Most of the API functions return values of type
.B mdn_result_t
in order to indicate the status of the call.

The following is a complete list of the status codes.  Note that some
of them are never returned by the functions described in this manual.
.TP 15
.SB mdn_success
Not an error.  The call succeeded.
.TP
.SB mdn_notfound
Specified information does not exist.
.TP
.SB mdn_invalid_encoding
The encoding of the specified string is invalid.
.TP
.SB mdn_invalid_syntax
There is a syntax error in the configuration file.
.TP
.SB mdn_invalid_name
The specified name is not valid.
.TP
.SB mdn_invalid_message
The specified DNS message is not valid.
.TP
.SB mdn_invalid_action
The specified action contains invalid flags.
.TP
.SB mdn_invalid_codepoint
The specified Unicode code point value is not valid.
.TP
.SB mdn_buffer_overflow
The specified buffer is too small to hold the result.
.TP
.SB mdn_noentry
The specified key does not exist in the hash table.
.TP
.SB mdn_nomemory
Memory allocation using malloc failed.
.TP
.SB mdn_nofile
The specified file could not be opened.
.TP
.SB mdn_nomapping
Some characters do not have the mapping to the target character set.
.TP
.SB mdn_context_required
Context information is required.
.TP
.SB mdn_prohibited
The specified string contains some prohibited characters.
.TP
.SB mdn_failure
Generic error which is not covered by the above codes.
.\"
.SH EXAMPLES
To get the address of a multilingual domain name in the application's
local codeset, use
.B mdn_encodename
to convert the name to the format suitable for passing to resolver functions.
.RS 4
.nf
.ft CW
mdn_result_t r;
char ace_name[256];
struct hostent *hp;

\&...
r = mdn_encodename(MDN_ENCODE_APP, name, ace_name,
                   sizeof(ace_name));
if (r != mdn_success) {
    fprintf(stderr, "mdn_encodename failed: %s\en",
            mdn_result_tostring(r));
    exit(1);
}

hp = gethostbyname(ace_name);
\&...
.ft R
.fi
.RE
.PP
To decode the multilingual domain name returned from a resolver function,
use
.BR mdn_decodename .
.RS 4
.nf
.ft CW
mdn_result_t r;
char local_name[256];
struct hostent *hp;

\&...
hp = gethostbyname(name);
r = mdn_decodename(MDN_DECODE_APP, hp->h_name, local_name,
                   sizeof(local_name));
if (r != mdn_success) {
    fprintf(stderr, "mdn_decodename failed: %s\en",
            mdn_result_tostring(r));
    exit(1);
}
printf("name: %s\en", local_name);
\&...
.ft R
.fi
.RE
.\"
.SH COMPATIBILITY
.B mdn_encodename
and
.B mdn_decodename
in mDNkit version 2.x prior to 2.4 provide the 
.B MDN_UNASCHECK
process macro for unassigned codepoint check.
However, beginning with mDNkit version 2.4, the 
.B MDN_NAMEPREP
process macro also performs the unassigned check.
.PP
To perform NAMEPREP without the unassigned check on mDNkit 2.4
or later, specify the actions:
.RS 2
.nf
.ft CW
MDN_NAMEPREP^MDN_UNASCHECK
.ft R
.fi
.RE
.PP
instead of
.BR MDN_NAMEPREP .
.SH FILES
.I @sysconfdir@/mdn.conf
.\"
.SH "SEE ALSO"
mdn.conf(5)