punycode.h

   1 /* punycode.h   Declarations for punycode functions.
   2  * Copyright (C) 2002, 2003  Simon Josefsson
   3  *
   4  * This file is part of GNU Libidn.
   5  *
   6  * GNU Libidn is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * GNU Libidn is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with GNU Libidn; if not, write to the Free Software
  18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  19  *
  20  */
  21
  22 /*
  23  * This file is derived from RFC 3492 written by Adam M. Costello.
  24  *
  25  * Disclaimer and license: Regarding this entire document or any
  26  * portion of it (including the pseudocode and C code), the author
  27  * makes no guarantees and is not responsible for any damage resulting
  28  * from its use.  The author grants irrevocable permission to anyone
  29  * to use, modify, and distribute it in any way that does not diminish
  30  * the rights of anyone else to use, modify, and distribute it,
  31  * provided that redistributed derivative works do not contain
  32  * misleading author or version information.  Derivative works need
  33  * not be licensed under similar terms.
  34  *
  35  * Copyright (C) The Internet Society (2003).  All Rights Reserved.
  36  *
  37  * This document and translations of it may be copied and furnished to
  38  * others, and derivative works that comment on or otherwise explain it
  39  * or assist in its implementation may be prepared, copied, published
  40  * and distributed, in whole or in part, without restriction of any
  41  * kind, provided that the above copyright notice and this paragraph are
  42  * included on all such copies and derivative works.  However, this
  43  * document itself may not be modified in any way, such as by removing
  44  * the copyright notice or references to the Internet Society or other
  45  * Internet organizations, except as needed for the purpose of
  46  * developing Internet standards in which case the procedures for
  47  * copyrights defined in the Internet Standards process must be
  48  * followed, or as required to translate it into languages other than
  49  * English.
  50  *
  51  * The limited permissions granted above are perpetual and will not be
  52  * revoked by the Internet Society or its successors or assigns.
  53  *
  54  * This document and the information contained herein is provided on an
  55  * "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
  56  * TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
  57  * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
  58  * HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
  59  * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  60  */
  61
  62 #ifndef _PUNYCODE_H
  63 #define _PUNYCODE_H
  64
  65 #ifdef __cplusplus
  66 extern "C"
  67 {
  68 #endif
  69
  70 #include <stddef.h>             /* size_t */
  71 #include <idn-int.h>            /* uint32_t */
  72
  73   enum punycode_status
  74   {
  75     PUNYCODE_SUCCESS = 0,
  76     PUNYCODE_BAD_INPUT,         /* Input is invalid.                       */
  77     PUNYCODE_BIG_OUTPUT,        /* Output would exceed the space provided. */
  78     PUNYCODE_OVERFLOW,          /* Input needs wider integers to process.  */
  79     /* For compatibility with RFC: */
  80     punycode_success = PUNYCODE_SUCCESS,
  81     punycode_bad_input = PUNYCODE_BAD_INPUT,
  82     punycode_big_output = PUNYCODE_BIG_OUTPUT,
  83     punycode_overflow = PUNYCODE_OVERFLOW
  84   };
  85
  86   int punycode_encode (size_t input_length,
  87                        const uint32_t input[],
  88                        const unsigned char case_flags[],
  89                        size_t * output_length,
  90                        char output[]);
  91
  92 /* punycode_encode() converts Unicode to Punycode.  The input     */
  93 /* is represented as an array of Unicode code points (not code    */
  94 /* units; surrogate pairs are not allowed), and the output        */
  95 /* will be represented as an array of ASCII code points.  The     */
  96 /* output string is *not* null-terminated; it will contain        */
  97 /* zeros if and only if the input contains zeros.  (Of course     */
  98 /* the caller can leave room for a terminator and add one if      */
  99 /* needed.)  The input_length is the number of code points in     */
 100 /* the input.  The output_length is an in/out argument: the       */
 101 /* caller passes in the maximum number of code points that it     */
 102 /* can receive, and on successful return it will contain the      */
 103 /* number of code points actually output.  The case_flags array   */
 104 /* holds input_length boolean values, where nonzero suggests that */
 105 /* the corresponding Unicode character be forced to uppercase     */
 106 /* after being decoded (if possible), and zero suggests that      */
 107 /* it be forced to lowercase (if possible).  ASCII code points    */
 108 /* are encoded literally, except that ASCII letters are forced    */
 109 /* to uppercase or lowercase according to the corresponding       */
 110 /* uppercase flags.  If case_flags is a null pointer then ASCII   */
 111 /* letters are left as they are, and other code points are        */
 112 /* treated as if their uppercase flags were zero.  The return     */
 113 /* value can be any of the punycode_status values defined above   */
 114 /* except punycode_bad_input; if not punycode_success, then       */
 115 /* output_size and output might contain garbage.                  */
 116
 117   int punycode_decode (size_t input_length,
 118                        const char input[],
 119                        size_t * output_length,
 120                        uint32_t output[],
 121                        unsigned char case_flags[]);
 122
 123 /* punycode_decode() converts Punycode to Unicode.  The input is  */
 124 /* represented as an array of ASCII code points, and the output   */
 125 /* will be represented as an array of Unicode code points.  The   */
 126 /* input_length is the number of code points in the input.  The   */
 127 /* output_length is an in/out argument: the caller passes in      */
 128 /* the maximum number of code points that it can receive, and     */
 129 /* on successful return it will contain the actual number of      */
 130 /* code points output.  The case_flags array needs room for at    */
 131 /* least output_length values, or it can be a null pointer if the */
 132 /* case information is not needed.  A nonzero flag suggests that  */
 133 /* the corresponding Unicode character be forced to uppercase     */
 134 /* by the caller (if possible), while zero suggests that it be    */
 135 /* forced to lowercase (if possible).  ASCII code points are      */
 136 /* output already in the proper case, but their flags will be set */
 137 /* appropriately so that applying the flags would be harmless.    */
 138 /* The return value can be any of the punycode_status values      */
 139 /* defined above; if not punycode_success, then output_length,    */
 140 /* output, and case_flags might contain garbage.  On success, the */
 141 /* decoder will never need to write an output_length greater than */
 142 /* input_length, because of how the encoding is defined.          */
 143
 144 #ifdef __cplusplus
 145 }
 146 #endif
 147 #endif                          /* _PUNYCODE_H */