The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

idn_decodename (3)
  • >> idn_decodename (3) ( Solaris man: Библиотечные вызовы )
  •  

    NAME

    idn_decodename, idn_decodename2, idn_enable, idn_encodename, idn_nameinit - IDN (Internationalized Domain Name) conversion functions
     
    

    SYNOPSIS

    cc [ flag... ] file... -lidnkit [ library... ] 
    #include <idn/api.h>
    
    idn_result_t idn_decodename(int actions, const char *from, char *to,
        size_t tolen);
    

    idn_result_t idn_decodename2(int actions, const char *from, char *to,
        size_t tolen, const char *auxencoding);
    

    idn_result_t idn_encodename(int actions, const char *from, char *to,
        size_t tolen);
    

    void idn_enable(int on_off);
    

    idn_result_t idn_nameinit(int load_file);
    

     

    DESCRIPTION

    The idn_nameinit() function initializes the library. It also sets default configuration if load_file is 0, otherwise it tries to read a configuration file. If idn_nameinit() is called more than once, the library initialization will take place only at the first call while the actual configuration procedure will occur at every call.

    If there are no errors, idn_nameinit() returns idn_success. Otherwise, the returned value indicates the cause of the error. See the section RETURN VALUES below for the error codes.

    It is usually not necessary to call this function explicitly because it is implicitly called when idn_encodename(), idn_decodename(), or idn_decodename2() is first called without prior calling of idn_nameinit().

    The idn_encodename() function performs name preparation and encoding conversion on the internationalized domain name specified by from, and stores the result to to, whose length is specified by tolen. The actions argument is a bitwise-OR of the following macros, specifying which subprocesses in the encoding process are to be employed.

    IDN_LOCALCONV

    Local encoding to UTF-8 conversion

    IDN_DELIMMAP

    Delimiter mapping

    IDN_LOCALMAP

    Local mapping

    IDN_NAMEPREP

    NAMEPREP mapping, normalization, prohibited character check, and bidirectional string check

    IDN_UNASCHECK

    NAMEPREP unassigned codepoint check

    IDN_ASCCHECK

    ASCII range character check

    IDN_IDNCONV

    UTF-8 to IDN encoding conversion

    IDN_LENCHECK

    Label length check

    Details of this encoding process can be found in the section Name Encoding

    For convenience, also IDN_ENCODE_QUERY, IDN_ENCODE_APP, and IDN_ENCODE_STORED macros are provided. IDN_ENCODE_QUERY is used to encode a ``query string'' (see the IDNA specification). It is equal to:

    (IDN_LOCALCONV | IDN_DELIMMAP | IDN_LOCALMAP | IDN_NAMEPREP |
            IDN_IDNCONV | IDN_LENCHECK)
    

    IDN_ENCODE_APP is used for ordinary application to encode a domain name. It performs IDN_ASCCHECK in addition with IDN_ENCODE_QUERY. IDN_ENCODE_STORED is used to encode a ``stored string'' (see the IDNA specification). It performs IDN_ENCODE_APP plus IDN_UNASCHECK.

    The idn_decodename() function performs the reverse of idn_encodename(). It converts the internationalized domain name given by from, which is represented in a special encoding called ACE (ASCII Compatible Encoding), to the application's local codeset and stores in to, whose length is specified by tolen. As in idn_encodename(), actions is a bitwise-OR of the following macros.

    IDN_DELIMMAP

    Delimiter mapping

    IDN_NAMEPREP

    NAMEPREP mapping, normalization, prohibited character check and bidirectional string check

    IDN_UNASCHECK

    NAMEPREP unassigned codepoint check

    IDN_IDNCONV

    UTF-8 to IDN encoding conversion

    IDN_RTCHECK

    Round trip check

    IDN_ASCCHECK

    ASCII range character check

    IDN_LOCALCONV

    Local encoding to UTF-8 conversion

    Details of this decoding process can be found in the section Name Decoding.

    For convenience, IDN_DECODE_QUERY, IDN_DECODE_APP, and IDN_DECODE_STORED macros are also provided. IDN_DECODE_QUERY is used to decode a ``query string'' (see the IDNA specification). It is equal to

    (IDN_DELIMMAP | IDN_NAMEPREP | IDN_IDNCONV | IDN_RTCHECK | IDN_LOCALCONV)
    

    IDN_DECODE_APP is used for ordinary application to decode a domain name. It performs IDN_ASCCHECK in addition to IDN_DECODE_QUERY. IDN_DECODE_STORED is used to decode a ``stored string'' (see the IDNA specification). It performs IDN_DECODE_APP plus IDN_UNASCHECK.

    The idn_decodename2() function provides the same functionality as idn_decodename() except that character encoding of from is supposed to be auxencoding. If IDN encoding is Punycode and auxencoding is ISO8859-2, for example, it is assumed that the Punycode string stored in from is written in ISO8859-2.

    In the IDN decode procedure, IDN_NAMEPREP is done before IDN_IDNCONV, and some non-ASCII characters are converted to ASCII characters as the result of IDN_NAMEPREP. Therefore, ACE string specified by from might contains those non-ASCII characters. That is the reason docode_name2() exists.

    All of thsee functions return an error value of type idn_result_t. All values other than idn_success indicates some kind of failure.  

    Name Encoding

    Name encoding is a process that transforms the specified internationalized domain name to a certain string suitable for name resolution. For each label in a given domain name, the encoding processor performs:

    1.
    Convert to UTF-8 (IDN_LOCALCONV)

    Convert the encoding of the given domain name from application's local encoding (for example, ISO8859-1) to UTF-8.

    2.
    Delimiter mapping (IDN_DELIMMAP)

    Map domain name delimiters to `.' (U+002E). The reco- ginzed delimiters are: U+3002 (ideographic full stop), U+FF0E (fullwidth full stop), U+FF61 (halfwidth ideographic full stop).

    3.
    Local mapping (IDN_LOCALMAP)

    Apply character mapping whose rule is determined by the top-level domain name.

    4.
    NAMEPREP (IDN_NAMEPREP, IDN_UNASCHECK)

    Perform name preparation (NAMEPREP), which is a standard process for name canonicalizaion of internationalized domain names.

    NAMEPREP consists of 5 steps: mapping, normalization, prohibited character check, bidirectional text check, and unassigned codepoint check. The first four steps are done by IDN_NAMEPREP, and the last step is done by IDN_UNASCHECK.

    5.
    ASCII range character check (IDN_ASCCHECK)

    Checks if the domain name contains non-LDH ASCII characters (not letter, digit, or hyphen characters), or it begins or end with hyphen.

    6.
    Convert to ACE (IDN_IDNCONV)

    Convert the NAMEPREPed name to a special encoding designed for representing internationalized domain names.

    The encoding is known as ACE (ASCII Compatible Encoding) since a string in the encoding is just like a traditional ASCII domain name consisting of only letters, digits and hyphens.

    7.
    Label length check (IDN_LENCHECK)

    For each label, check the number of characters in it. It must be in the range of 1 to 63.

     

    Name Decoding

    Name decoding is a reverse process of the name encoding. It transforms the specified internationalized 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.

    For each label in a given domain name, the decoding processor performs:

    1.
    Delimiter mapping (IDN_DELIMMAP)

    Map domain name delimiters to `.' (U+002E). The recoginzed delimiters are: U+3002 (ideographic full stop), U+FF0E (fullwidth full stop), U+FF61 (halfwidth ideographic full stop).

    2.
    NAMEPREP (IDN_NAMEPREP, IDN_UNASCHECK)

    Perform name preparation (NAMEPREP), which is a standard process for name canonicalizaion of internationalized domain names.

    3.
    Convert to UTF-8 (IDN_IDNCONV)

    Convert the encoding of the given domain name from ACE to UTF-8.

    4.
    Round trip check (IDN_RTCHECK)

    Encode the result of (3) using the Name Encoding scheme, and then compare it with the result of the step (2). If they are different, the check is failed. If IDN_UNASCHECK, IDN_ASCCHECK or both are specified, they are also done in the encoding processes.

    5.
    Convert to local encoding

    Convert the result of (3) from UTF-8 to the application's local encoding (for example, ISO8859-1).

    If prohibited character check, unassigned codepoint check or bidirectional text check at step (2) failed, or if round trip check at step (4) failed, the original input label is returned.  

    Disabling IDN

    If your application should always disable internationalized domain name support for some reason, call

    (void) idn_enable(0);
    

    before performing encoding/decoding. Afterward, you can enable the support by calling

    (void) idn_enable(1);
    

     

    RETURN VALUES

    These functions return values of type idn_result_t to indicate the status of the call. The following is a complete list of the status codes.

    idn_success

    Not an error. The call succeeded.

    idn_notfound

    Specified information does not exist.

    idn_invalid_encoding

    The encoding of the specified string is invalid.

    idn_invalid_syntax

    There is a syntax error in internal configuration file(s).

    idn_invalid_name

    The specified name is not valid.

    idn_invalid_message

    The specified message is not valid.

    idn_invalid_action

    The specified action contains invalid flags.

    idn_invalid_codepoint

    The specified Unicode code point value is not valid.

    idn_invalid_length

    The number of characters in an ACE label is not in the range of 1 to 63.

    idn_buffer_overflow

    The specified buffer is too small to hold the result.

    idn_noentry

    The specified key does not exist in the hash table.

    idn_nomemory

    Memory allocation using malloc failed.

    idn_nofile

    The specified file could not be opened.

    idn_nomapping

    Some characters do not have the mapping to the target character set.

    idn_context_required

    Context information is required.

    idn_prohibited

    The specified string contains some prohibited characters.

    idn_failure

    Generic error which is not covered by the above codes.

     

    EXAMPLES

    Example 1 Get the address of an internationalized domain name.

    To get the address of an internationalized domain name in the application's local codeset, use idn_encodename() to convert the name to the format suitable for passing to resolver functions.

    #include <idn/api.h>
    #include <sys/socket.h>
    #include <netdb.h>
    
    ...
    
    idn_result_t r;
    char ace_name[256];
    struct hostent *hp;
    int error_num;
    
    ...
    
    r = idn_encodename(IDN_ENCODE_APP, name, ace_name,
                      sizeof(ace_name));
    if (r != idn_success) {
       fprintf(stderr, gettext("idn_encodename failed.\n"));
       exit(1);
    }
    
    hp = getipnodebyname(ace_name, AF_INET6, AI_DEFAULT, &error_num);
    
    ...
    

    Example 2 Decode the internationalized domain name.

    To decode the internationalized domain name returned from a resolver function, use idn_decodename().

    #include <idn/api.h>
    #include <sys/socket.h>
    #include <netdb.h>
    
    ...
    
    idn_result_t r;
    char local_name[256];
    struct hostent *hp;
    int error_num;
    
    ...
    
    hp = getipnodebyname(name, AF_INET, AI_DEFAULT, &error_num);
    if (hp != (struct hostent *)NULL) {
        r = idn_decodename(IDN_DECODE_APP, hp->h_name, local_name,
                      sizeof(local_name));
        if (r != idn_success) {
             fprintf(stderr, gettext("idn_decodename failed.\n"));
             exit(1);
        }
        printf(gettext("name: %s\n"), local_name);
    }
    
    ...
    

     

    ATTRIBUTES

    See attributes(5) for descriptions of the following attributes:

    ATTRIBUTE TYPEATTRIBUTE VALUE

    AvailabilitySUNWidnl, SUNWidnd

    CSI

    Interface Stability

    MT-Level

     

    SEE ALSO

    intro(3), libidnkit(3LIB), setlocale(3C), hosts(4), attributes(5), environ(5)

    RFC 3490

    Internationalizing Domain Names in Applications (IDNA)

    RFC 3491

    Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)

    RFC 3492

    Punycode: A Bootstring encoding of Unicode for Internationalized Domain Names in Applications (IDNA)

    RFC 3454

    Preparation of Internationalized Strings ("stringprep")

    RFC 952

    DoD Internet Host Table Specification

    RFC 921

    Domain Name System Implementation Schedule - Revised

    STD 3, RFC 1122

    Requirements for Internet Hosts -- Communication Layers

    STD 3, RFC 1123

    Requirements for Internet Hosts -- Applications and Support

    Unicode Standard Annex #15: Unicode Normalization Forms, Version 3.2.0. http://www.unicode.org

    International Language Environments Guide (for this version of Solaris)  

    COPYRIGHT AND LICENSE

    Copyright (c) 2000-2002 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) 2000-2002 Japan Network Information Center. All rights reserved."
    4.
    The name of JPNIC may not 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.
     

    NOTES

    The idn_nameinit() function checks internal system configuration files such as /etc/idn/idn.conf and /etc/idn/idnalias.conf if they are in the proper access mode and owership. If they are not in the proper access mode or ownership, the function will not read and use the configurations defined in the files but use default values. In this case the function will also issue a warning message such as:

    idn_nameinit: warning: config file (/etc/idn/idn.conf) not in proper 
                          access mode or ownership - the file ignored.
    

    The proper access mode and the ownership are described in the package prototype file of SUNWidnl. It is also recommended not to change the system configuration files.


     

    Index

    NAME
    SYNOPSIS
    DESCRIPTION
    Name Encoding
    Name Decoding
    Disabling IDN
    RETURN VALUES
    EXAMPLES
    ATTRIBUTES
    SEE ALSO
    COPYRIGHT AND LICENSE
    NOTES


    Поиск по тексту MAN-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру