Multilingual Domain Name Conversion API

Overview
Initialize(mdn_nameinit)
Encode (mdn_encodename)
Decode(mdn_decodename)
Override the environment variable MDN_DISABLE (mdn_enable)
Programming Creation Method
Program Example

Overview

Multilingual domain name processing consists of the following two types of processing.

Encoding conversion
NAMEPREP

In addition to the above, mDNkit provides two additional types of processing.

Delimiter mapping
Local mapping based on the top level domain.

With the multilingual domain processing architecture IDNA, this processing is all performed by the application. For example, when the function for name resolution gethostbyname is called to resolve the multilingual domain name, the text string of the result already obtained using that processing is supposed to be passed.

mDNkit provides two types of APIs to perform processing.

High level API: This API is for general applications and is simple and easy to use. When you use this API, the multilingual domain processing function can easily be added to applications. Note, however, that detailed settings cannot be performed.
Low level API: This API is for specific applications requiring detailed settings that cannot be set with the high level API. The high level API is created above the low level API.

Since the low level API is provided for specific applications, it is not explained here. To use the low level API, refer to resconf module and res module of MDN Library Specification.

The high level API consists of three functions, as follows:

Performs initialization mdn_nameinit
Encodes multilingual domain names for name resolution mdn_encodename
Decodes multilingual domain names returned from the DNS server mdn_decodename

Each function is explained below. Refer to MDN Library Specifications api module as well.

Initialize

mdn_nameinit is used to perform initialization for multilingual domain name processing.

mdn_result_t mdn_nameinit(void)

This function initializes the entire MDN library, then loads Configuration file (mdn.conf), which describes various settings for multilingual domain name processing.

As the return value, this function returns the mdn_result_t type value that indicates the execution result. The codes returned by this function and their meanings are as follows.

mdn_success: Initialization is completed correctly.
mdn_nofile: The configuration file could not be opened.
mdn_invalid_syntax: The configuration file contains a syntax error.
mdn_invalid_name: The name (encoding name) specified in the configuration file contains an error.
mdn_nomemory: malloc failed.

This function can be called more than once; however, initialization of the entire MDN library is performed only once when the function is called the first time; during the second and following times only reloading of the configuration file is performed. When the contents of the configuration file are changed while running the application, the latest settings can be obtained by calling this function.

The encode or decode function may be called without calling this function beforehand. In such a case, initialization processing takes place implicitly before encode or decode processing, just like when using this function.

Encode

To perform multilingual domain name encode processing, that is, to perform conversion to text string to be passed to the name resolution function, etc., use mdn_encodename.

mdn_result_t mdn_encodename(int actions, const char *from,
                            char *to, size_t tolen)

Performs processing specified by actions on the domain name specified by from and writes the result in the field indicated by to. tolen is the size (the number of bytes) of the field indicated by to and the result is not written when tolen is exceeded.

Generally, when using this function the multilingual domain name encoding process is as follows.

Encoding conversion
Converts local encoding (SJIS, etc.) used by the application to UTF-8.
Delimiter mapping
Converts special characters to dot that is the delimiter in domain names.
Local mapping based on the top level domain
Performs mapping corresponding to the top level domain of the entered domain name.
NAMEPREP
Normalizes multilingual domain names and detects prohibited characters.
Encoding conversion
Converts from UTF-8 to multilingual domain name standard encoding (IDN encoding).

Use the following flags to specify which processing is actually to be executed with the argument actions. The actual value specified for actions is the logical OR for each bit.

MDN_LOCALCONV: Converts from local encoding to UTF-8.
MDN_DELIMMAP: Performs delimiter mapping.
MDN_LOCALMAP: Performs local mapping based on the top level domain.
MDN_NAMEPREP: Normalizes multilingual domain names and detects prohibited characters.
MDN_UNASCHECK: Detects unassigned code points, which is an optional (not mandatory) function in NAMEPREP.
MDN_IDNCONV: Converts from UTF-8 to IDN encoding.

With standard applications, it is OK if all of processing except MDN_UNASCHECK is performed. To do so, a macro called MDN_ENCODE_APP needs to be defined and this value needs to be specified for actions. By doing so, all processing is performed except the detection of unassigned code points.

All parameters used in the above processing are set in Configuration file (mdn.conf) of mDNkit. The parameters used are listed below.

Characters mapped by dot in delimiter mapping
Local mapping rules
NAMEPREP version
Encoding name used for IDN encoding

As the return value, this function returns the mdn_result_t type value that indicates the execution result. The codes returned by this function and their meanings are as follows.

mdn_success: Processing was completed correctly.
mdn_invalid_action: Incorrect flag is specified by actions.
mdn_invalid_encoding: Encoding of the character string specified by from contains an error.
mdn_prohibited: Entered character strings contain prohibited characters. When flag MDN_UNASCHECK is specified, this code is returned when unassigned code points exist.
mdn_buffer_overflow: The result cannot be stored because the value of tolen is too small.
mdn_nomemory: malloc failed.

Note that when this function is called without calling the mdn_nameinit initialization function beforehand, initialization takes place before conversion processing. In that case, in addition to the above the function may return the following results.

mdn_nofile: The configuration file could not be opened.
mdn_invalid_syntax: The configuration file contains a syntax error.
mdn_invalid_name: The name (encoding name, etc.) specified in the configuration file contains an error.

In addition, in the case of setting the environment variable MDN_DISABLE, even if using this function, the conversion for the string is not performed, but the result as the original string is returned. How to convert the string forcibly in an environment set MDN_DISABLE is written in Override the environment variable MDN_DISABLE.

Decode

To decode multilingual domain names, that is, to convert the already encoded domain name character strings returned from the name resolution function to the character strings of the encoding used by the application, use mdn_decodename.

mdn_result_t mdn_decodename(int actions, const char *from,
                            char *to, size_t tolen)

Performs processing specified by actions on the domain name specified by from and writes the result in the field indicated by to. tolen is the size (number of bytes) of the field indicated by to and the result is not written when tolen is exceeded.

Generally, when using this function multilingual domain name decode processing is as follows.

Encoding conversion
Converts from the multilingual domain name standard encoding (IDN encoding) to UTF-8.
NAMEPREP check
Checks whether the string was performed NAMEPREP correctly.
Encoding conversion
Converts from UTF-8 to the local encoding (SJIS, etc.) used by the application.

Use the following flags to specify which processing is to actually be executed with the actions argument. The actual value specifed for actions is the logical OR for each bit.

MDN_IDNCONV: Converts from IDN encoding to UTF-8.
MDN_NAMEPREP: Checks whether the string was performed NAMEPREP correctly. If not performed, undo IDN encoding again.
MDN_UNASCHECK: Checks whether the string included unassigned code points of NAMEPREP. If not include, undo IDN encoding again.
MDN_LOCALCONV: Converts from UTF-8 to local encoding. However, if conversion cannot be performed because there are no characters corresponding to the local encoding, the domain name is converted to IDN encoding.

With standard applications, it is OK if any types of processing except MDN_UNASCHECK are performed. To do any processes except detection unassigned code points, a macro called MDN_DECODE_APP must be defined and this value needs to be specifid for actions.

All parameters used in the above processing are set in Configuration file (mdn.conf) of mDNkit. The parameters used are listed below.

Encoding name used as IDN encoding
Version of NAMEPREP

As the return value, this function returns mdn_result_t type value that indicates the execution result. The codes returned by this function and their meanings are as follows.

mdn_success: Processing was completed correctly.
mdn_invalid_action: An incorrect flag is specified by actions.
mdn_invalid_encoding: The encoding of the character string specified by from contains an error.
mdn_buffer_overflow: The result cannot be stored because the value of tolen is too small.
mdn_nomemory: malloc failed.

mdn_nofile: The configuration file could not be opened.
mdn_invalid_syntax: The configuration file contains a syntax error.
mdn_invalid_name: The name (encoding name, etc.) specified in the configuration file contains an error.

Override the environment variable MDN_DISABLE

In regular case, even if using API to convert the domain name in an environment set the environment variable MDN_DISABLE, the process of conversion is not performed, but return the results as the original string. However, mdn_enable is available as the API to override this setting explicitly.

void
mdn_enable(int on_off)

In spite of whether the environment variable MDN_DISABLE is set or not, if on_off is 0, the conversion of the domain names is not performed subsequently. Besides, if the value of on_off is other than 0, in spite of whether the environment variable MDN_DISABLE is set or not, the conversion of the domain names is performed after calling this function.

Programming Creation Method

This section summarizes how to create programs using APIs and items to note.

Include files
For programs that use the high level API, include two header files, stddef.h and mdn/api.h.
```
#include <stddef.h>
#include <mdn/api.h>
```
Locale setting
mDNkit obtains the local encoding used by the application from the locale information or environment variable MDN_LOCAL_CODESET. To obtain from the locale information, perform setlocale at the beginning of the application and set the locale of the application correctly.
Error display
All APIs return a mdn_result_t type value. From this value, the mdn_result_tostring function used to obtain the corresponding message character string is provided. It is used to display error messages. For details of this function, refer to Explanation of Specifications
Compile and link
To compile, specify the install directory (in the default, /usr/local/include) of the header file of mDNkit using the -I option.
To link, link the iconv library as well if iconv is not contained in the standard library.
```
cc -I/usr/local/include example.c -L/usr/local/lib -lmdn -liconv
```

Program Example

This section lists a simple program used to perform name resolution of multilingual domain name using the above API.

#include <stdio.h>
#include <stddef.h>
#include <netdb.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <mdn/api.h>

int main(int ac, char **av)
{
    struct hostent *hp;
    char buf1[256];
    char buf2[256];
    char addrbuf[100];
    mdn_result_t r;

    /* Set the locale */
    setlocale(LC_ALL, "");
    if (ac != 2) {
        fprintf(stderr, "Usage: %s hostname\n", av[0]);
        return 1;
    }
    /* Convert the name before calling gethostbyname */
    if ((r = mdn_encodename(MDN_ENCODE_APP, av[1],
                            buf1, sizeof(buf1))) != mdn_success) {
        fprintf(stderr, "mdn_encodename: %s\n", mdn_result_tostring(r));
        return 1;
    }
    /* Resolve the name */
    if ((hp = gethostbyname(buf1)) == NULL) {
        fprintf(stderr, "gethostbyname failed\n");
        return 1;
    }
    /* Convert the returned name to the local encoding */
    if ((r = mdn_decodename(MDN_DECODE_APP, hp->h_name,
                            buf2, sizeof(buf2))) != mdn_success) {
        fprintf(stderr, "mdn_decodename: %s\n", mdn_result_tostring(r));
        return 1;
    }
    printf("%s  %s\n",
           inet_ntop(hp->h_addrtype, hp->h_addr, addrbuf, sizeof(addrbuf)),
           buf2);
    return 0;
}