punycode.h

   1 /* punycode.h   Declarations for punycode functions.
   2  * Copyright (C) 2002  Adam M. Costello
   3  * Copyright (C) 2002  Simon Josefsson
   4  *
   5  * This file is part of Libstringprep.
   6  *
   7  * Libstringprep is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * Libstringprep is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with Libstringprep; if not, write to the Free Software
  19  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  20  *
  21  */
  22
  23 /*
  24  * This file is derived from from draft-ietf-idn-punycode-03.txt by
  25  * Adam M. Costello.
  26  *
  27  * Disclaimer and license: Regarding this entire document or any
  28  * portion of it (including the pseudocode and C code), the author
  29  * makes no guarantees and is not responsible for any damage resulting
  30  * from its use.  The author grants irrevocable permission to anyone
  31  * to use, modify, and distribute it in any way that does not diminish
  32  * the rights of anyone else to use, modify, and distribute it,
  33  * provided that redistributed derivative works do not contain
  34  * misleading author or version information.  Derivative works need
  35  * not be licensed under similar terms.
  36  *
  37  */
  38
  39 #ifndef _PUNYCODE_H
  40 #define _PUNYCODE_H
  41
  42 #ifdef __cplusplus
  43 extern "C"
  44 {
  45 #endif
  46
  47   enum
  48   {
  49     PUNYCODE_SUCCESS = 0,
  50     PUNYCODE_BAD_INPUT,         /* Input is invalid.                       */
  51     PUNYCODE_BIG_OUTPUT,        /* Output would exceed the space provided. */
  52     PUNYCODE_OVERFLOW           /* Input needs wider integers to process.  */
  53   };
  54
  55   int punycode_encode (size_t input_length,
  56                        const unsigned long input[],
  57                        const unsigned char case_flags[],
  58                        size_t * output_length, char output[]);
  59 \f
  60 /* punycode_encode() converts Unicode to Punycode.  The input     */
  61 /* is represented as an array of Unicode code points (not code    */
  62 /* units; surrogate pairs are not allowed), and the output        */
  63 /* will be represented as an array of ASCII code points.  The     */
  64 /* output string is *not* null-terminated; it will contain        */
  65 /* zeros if and only if the input contains zeros.  (Of course     */
  66 /* the caller can leave room for a terminator and add one if      */
  67 /* needed.)  The input_length is the number of code points in     */
  68 /* the input.  The output_length is an in/out argument: the       */
  69 /* caller passes in the maximum number of code points that it     */
  70 /* can receive, and on successful return it will contain the      */
  71 /* number of code points actually output.  The case_flags array   */
  72 /* holds input_length boolean values, where nonzero suggests that */
  73 /* the corresponding Unicode character be forced to uppercase     */
  74 /* after being decoded (if possible), and zero suggests that      */
  75 /* it be forced to lowercase (if possible).  ASCII code points    */
  76 /* are encoded literally, except that ASCII letters are forced    */
  77 /* to uppercase or lowercase according to the corresponding       */
  78 /* uppercase flags.  If case_flags is a null pointer then ASCII   */
  79 /* letters are left as they are, and other code points are        */
  80 /* treated as if their uppercase flags were zero.  The return     */
  81 /* value can be any of the punycode_status values defined above   */
  82 /* except punycode_bad_input; if not punycode_success, then       */
  83 /* output_size and output might contain garbage.                  */
  84
  85   int punycode_decode (size_t input_length,
  86                        const char input[],
  87                        size_t * output_length,
  88                        unsigned long output[], unsigned char case_flags[]);
  89
  90 /* punycode_decode() converts Punycode to Unicode.  The input is  */
  91 /* represented as an array of ASCII code points, and the output   */
  92 /* will be represented as an array of Unicode code points.  The   */
  93 /* input_length is the number of code points in the input.  The   */
  94 /* output_length is an in/out argument: the caller passes in      */
  95 /* the maximum number of code points that it can receive, and     */
  96 /* on successful return it will contain the actual number of      */
  97 /* code points output.  The case_flags array needs room for at    */
  98 /* least output_length values, or it can be a null pointer if the */
  99 /* case information is not needed.  A nonzero flag suggests that  */
 100 /* the corresponding Unicode character be forced to uppercase     */
 101 /* by the caller (if possible), while zero suggests that it be    */
 102 /* forced to lowercase (if possible).  ASCII code points are      */
 103 /* output already in the proper case, but their flags will be set */
 104 /* appropriately so that applying the flags would be harmless.    */
 105 /* The return value can be any of the punycode_status values      */
 106 /* defined above; if not punycode_success, then output_length,    */
 107 /* output, and case_flags might contain garbage.  On success, the */
 108 /* decoder will never need to write an output_length greater than */
 109 /* input_length, because of how the encoding is defined.          */
 110
 111 #ifdef __cplusplus
 112 }
 113 #endif
 114 #endif                          /* _PUNYCODE_H */