mdn_nameinit
)
mdn_encodename
)
mdn_decodename
)
mdn_enable
)
Multilingual domain name processing consists of the following two types of processing.
In addition to the above, mDNkit provides two additional types of processing.
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.
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:
mdn_nameinit
mdn_encodename
mdn_decodename
Each function is explained below.
Refer to MDN Library Specifications api
module as well.
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
mdn_nofile
mdn_invalid_syntax
mdn_invalid_name
mdn_nomemory
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.
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.
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
MDN_DELIMMAP
MDN_LOCALMAP
MDN_NAMEPREP
MDN_UNASCHECK
MDN_IDNCONV
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.
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
mdn_invalid_action
mdn_invalid_encoding
mdn_prohibited
MDN_UNASCHECK
is specified, this code is returned when unassigned code points exist.
mdn_buffer_overflow
mdn_nomemory
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
mdn_invalid_syntax
mdn_invalid_name
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.
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.
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
MDN_NAMEPREP
MDN_UNASCHECK
MDN_LOCALCONV
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.
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
mdn_invalid_action
mdn_invalid_encoding
mdn_buffer_overflow
mdn_nomemory
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 also return the following results.
mdn_nofile
mdn_invalid_syntax
mdn_invalid_name
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.
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.
This section summarizes how to create programs using APIs and items to note.
stddef.h
and mdn/api.h
.
#include <stddef.h> #include <mdn/api.h>
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.
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
/usr/local/include
) of the header file of mDNkit using the -I
option.cc -I/usr/local/include example.c -L/usr/local/lib -lmdn -liconv
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; }