/* punycode.h --- Declarations for punycode functions.

[0] Fix | Delete

Copyright (C) 2002-2016 Simon Josefsson

[1] Fix | Delete

[2] Fix | Delete

This file is part of GNU Libidn.

[3] Fix | Delete

[4] Fix | Delete

GNU Libidn is free software: you can redistribute it and/or

[5] Fix | Delete

modify it under the terms of either:

[6] Fix | Delete

[7] Fix | Delete

* the GNU Lesser General Public License as published by the Free

[8] Fix | Delete

Software Foundation; either version 3 of the License, or (at

[9] Fix | Delete

your option) any later version.

[10] Fix | Delete

[11] Fix | Delete

or

[12] Fix | Delete

[13] Fix | Delete

* the GNU General Public License as published by the Free

[14] Fix | Delete

Software Foundation; either version 2 of the License, or (at

[15] Fix | Delete

your option) any later version.

[16] Fix | Delete

[17] Fix | Delete

or both in parallel, as here.

[18] Fix | Delete

[19] Fix | Delete

GNU Libidn is distributed in the hope that it will be useful,

[20] Fix | Delete

but WITHOUT ANY WARRANTY; without even the implied warranty of

[21] Fix | Delete

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

[22] Fix | Delete

General Public License for more details.

[23] Fix | Delete

[24] Fix | Delete

You should have received copies of the GNU General Public License and

[25] Fix | Delete

the GNU Lesser General Public License along with this program. If

[26] Fix | Delete

not, see <http://www.gnu.org/licenses/>. */

[27] Fix | Delete

[28] Fix | Delete

/*

[29] Fix | Delete

* This file is derived from RFC 3492bis written by Adam M. Costello,

[30] Fix | Delete

* downloaded from http://www.nicemice.net/idn/punycode-spec.gz on

[31] Fix | Delete

* 2015-03-02 with SHA1 a966a8017f6be579d74a50a226accc7607c40133, a

[32] Fix | Delete

* copy of which is stored in the GNU Libidn version controlled

[33] Fix | Delete

* repository under doc/specification/punycode-spec.gz.

[34] Fix | Delete

*

[35] Fix | Delete

* The changes compared to Adam's file include: re-indentation, adding

[36] Fix | Delete

* the license boilerplate and this comment, adding the #ifndef

[37] Fix | Delete

* PUNYCODE_H and IDNAPI blocks, changing the return code of

[38] Fix | Delete

* punycode_encode and punycode_decode from enum to int, simplifying

[39] Fix | Delete

* the definition of punycode_uint by #include'ing idn-int.h and using

[40] Fix | Delete

* uint32_t instead of limit.h-based code, adding Punycode_status and

[41] Fix | Delete

* punycode_strerror, adding 'extern IDNAPI' declarations to function

[42] Fix | Delete

* prototypes, and mentioning variable names in function prototypes.

[43] Fix | Delete

*

[44] Fix | Delete

* Adam's file contains the following:

[45] Fix | Delete

*

[46] Fix | Delete

* punycode-sample.c 2.0.0 (2004-Mar-21-Sun)

[47] Fix | Delete

* http://www.nicemice.net/idn/

[48] Fix | Delete

* Adam M. Costello

[49] Fix | Delete

* http://www.nicemice.net/amc/

[50] Fix | Delete

*

[51] Fix | Delete

* This is ANSI C code (C89) implementing Punycode 1.0.x.

[52] Fix | Delete

*

[53] Fix | Delete

* Disclaimer and license: Regarding this entire document or any

[54] Fix | Delete

* portion of it (including the pseudocode and C code), the author

[55] Fix | Delete

* makes no guarantees and is not responsible for any damage resulting

[56] Fix | Delete

* from its use. The author grants irrevocable permission to anyone

[57] Fix | Delete

* to use, modify, and distribute it in any way that does not diminish

[58] Fix | Delete

* the rights of anyone else to use, modify, and distribute it,

[59] Fix | Delete

* provided that redistributed derivative works do not contain

[60] Fix | Delete

* misleading author or version information. Derivative works need

[61] Fix | Delete

* not be licensed under similar terms.

[62] Fix | Delete

*/

[63] Fix | Delete

[64] Fix | Delete

#ifndef PUNYCODE_H

[65] Fix | Delete

# define PUNYCODE_H

[66] Fix | Delete

[67] Fix | Delete

# ifndef IDNAPI

[68] Fix | Delete

# if defined LIBIDN_BUILDING && defined HAVE_VISIBILITY && HAVE_VISIBILITY

[69] Fix | Delete

# define IDNAPI __attribute__((__visibility__("default")))

[70] Fix | Delete

# elif defined LIBIDN_BUILDING && defined _MSC_VER && ! defined LIBIDN_STATIC

[71] Fix | Delete

# define IDNAPI __declspec(dllexport)

[72] Fix | Delete

# elif defined _MSC_VER && ! defined LIBIDN_STATIC

[73] Fix | Delete

# define IDNAPI __declspec(dllimport)

[74] Fix | Delete

# else

[75] Fix | Delete

# define IDNAPI

[76] Fix | Delete

# endif

[77] Fix | Delete

# endif

[78] Fix | Delete

[79] Fix | Delete

#ifdef __cplusplus

[80] Fix | Delete

extern "C"

[81] Fix | Delete

{

[82] Fix | Delete

#endif

[83] Fix | Delete

[84] Fix | Delete

/************************************************************/

[85] Fix | Delete

/* Public interface (would normally go in its own .h file): */

[86] Fix | Delete

[87] Fix | Delete

#include <stddef.h> /* size_t */

[88] Fix | Delete

#include <idn-int.h> /* uint32_t */

[89] Fix | Delete

[90] Fix | Delete

enum punycode_status

[91] Fix | Delete

{

[92] Fix | Delete

punycode_success = 0,

[93] Fix | Delete

punycode_bad_input = 1, /* Input is invalid. */

[94] Fix | Delete

punycode_big_output = 2, /* Output would exceed the space provided. */

[95] Fix | Delete

punycode_overflow = 3 /* Wider integers needed to process input. */

[96] Fix | Delete

};

[97] Fix | Delete

[98] Fix | Delete

typedef enum

[99] Fix | Delete

{

[100] Fix | Delete

PUNYCODE_SUCCESS = punycode_success,

[101] Fix | Delete

PUNYCODE_BAD_INPUT = punycode_bad_input,

[102] Fix | Delete

PUNYCODE_BIG_OUTPUT = punycode_big_output,

[103] Fix | Delete

PUNYCODE_OVERFLOW = punycode_overflow

[104] Fix | Delete

} Punycode_status;

[105] Fix | Delete

[106] Fix | Delete

extern IDNAPI const char *punycode_strerror (Punycode_status rc);

[107] Fix | Delete

[108] Fix | Delete

/* punycode_uint needs to be unsigned and needs to be */

[109] Fix | Delete

/* at least 26 bits wide. The particular type can be */

[110] Fix | Delete

/* specified by defining PUNYCODE_UINT, otherwise a */

[111] Fix | Delete

/* suitable type will be chosen automatically. */

[112] Fix | Delete

[113] Fix | Delete

typedef uint32_t punycode_uint;

[114] Fix | Delete

[115] Fix | Delete

extern IDNAPI int punycode_encode (size_t input_length,

[116] Fix | Delete

const punycode_uint input[],

[117] Fix | Delete

const unsigned char case_flags[],

[118] Fix | Delete

size_t * output_length, char output[]);

[119] Fix | Delete

[120] Fix | Delete

/*

[121] Fix | Delete

punycode_encode() converts a sequence of code points (presumed to be

[122] Fix | Delete

Unicode code points) to Punycode.

[123] Fix | Delete

[124] Fix | Delete

Input arguments (to be supplied by the caller):

[125] Fix | Delete

[126] Fix | Delete

input_length

[127] Fix | Delete

The number of code points in the input array and the number

[128] Fix | Delete

of flags in the case_flags array.

[129] Fix | Delete

[130] Fix | Delete

input

[131] Fix | Delete

An array of code points. They are presumed to be Unicode

[132] Fix | Delete

code points, but that is not strictly necessary. The

[133] Fix | Delete

array contains code points, not code units. UTF-16 uses

[134] Fix | Delete

code units D800 through DFFF to refer to code points

[135] Fix | Delete

10000..10FFFF. The code points D800..DFFF do not occur in

[136] Fix | Delete

any valid Unicode string. The code points that can occur in

[137] Fix | Delete

Unicode strings (0..D7FF and E000..10FFFF) are also called

[138] Fix | Delete

Unicode scalar values.

[139] Fix | Delete

[140] Fix | Delete

case_flags

[141] Fix | Delete

A null pointer or an array of boolean values parallel to

[142] Fix | Delete

the input array. Nonzero (true, flagged) suggests that the

[143] Fix | Delete

corresponding Unicode character be forced to uppercase after

[144] Fix | Delete

being decoded (if possible), and zero (false, unflagged)

[145] Fix | Delete

suggests that it be forced to lowercase (if possible).

[146] Fix | Delete

ASCII code points (0..7F) are encoded literally, except that

[147] Fix | Delete

ASCII letters are forced to uppercase or lowercase according

[148] Fix | Delete

to the corresponding case flags. If case_flags is a null

[149] Fix | Delete

pointer then ASCII letters are left as they are, and other

[150] Fix | Delete

code points are treated as unflagged.

[151] Fix | Delete

[152] Fix | Delete

Output arguments (to be filled in by the function):

[153] Fix | Delete

[154] Fix | Delete

output

[155] Fix | Delete

An array of ASCII code points. It is *not* null-terminated;

[156] Fix | Delete

it will contain zeros if and only if the input contains

[157] Fix | Delete

zeros. (Of course the caller can leave room for a

[158] Fix | Delete

terminator and add one if needed.)

[159] Fix | Delete

[160] Fix | Delete

Input/output arguments (to be supplied by the caller and overwritten

[161] Fix | Delete

by the function):

[162] Fix | Delete

[163] Fix | Delete

output_length

[164] Fix | Delete

The caller passes in the maximum number of ASCII code points

[165] Fix | Delete

that it can receive. On successful return it will contain

[166] Fix | Delete

the number of ASCII code points actually output.

[167] Fix | Delete

[168] Fix | Delete

Return value:

[169] Fix | Delete

[170] Fix | Delete

Can be any of the punycode_status values defined above except

[171] Fix | Delete

punycode_bad_input. If not punycode_success, then output_size

[172] Fix | Delete

and output might contain garbage.

[173] Fix | Delete

*/

[174] Fix | Delete

[175] Fix | Delete

extern IDNAPI int punycode_decode (size_t input_length,

[176] Fix | Delete

const char input[],

[177] Fix | Delete

size_t * output_length,

[178] Fix | Delete

punycode_uint output[],

[179] Fix | Delete

unsigned char case_flags[]);

[180] Fix | Delete

[181] Fix | Delete

/*

[182] Fix | Delete

punycode_decode() converts Punycode to a sequence of code points

[183] Fix | Delete

(presumed to be Unicode code points).

[184] Fix | Delete

[185] Fix | Delete

Input arguments (to be supplied by the caller):

[186] Fix | Delete

[187] Fix | Delete

input_length

[188] Fix | Delete

The number of ASCII code points in the input array.

[189] Fix | Delete

[190] Fix | Delete

input

[191] Fix | Delete

An array of ASCII code points (0..7F).

[192] Fix | Delete

[193] Fix | Delete

Output arguments (to be filled in by the function):

[194] Fix | Delete

[195] Fix | Delete

output

[196] Fix | Delete

An array of code points like the input argument of

[197] Fix | Delete

punycode_encode() (see above).

[198] Fix | Delete

[199] Fix | Delete

case_flags

[200] Fix | Delete

A null pointer (if the flags are not needed by the caller)

[201] Fix | Delete

or an array of boolean values parallel to the output array.

[202] Fix | Delete

Nonzero (true, flagged) suggests that the corresponding

[203] Fix | Delete

Unicode character be forced to uppercase by the caller (if

[204] Fix | Delete

possible), and zero (false, unflagged) suggests that it

[205] Fix | Delete

be forced to lowercase (if possible). ASCII code points

[206] Fix | Delete

(0..7F) are output already in the proper case, but their

[207] Fix | Delete

flags will be set appropriately so that applying the flags

[208] Fix | Delete

would be harmless.

[209] Fix | Delete

[210] Fix | Delete

Input/output arguments (to be supplied by the caller and overwritten

[211] Fix | Delete

by the function):

[212] Fix | Delete

[213] Fix | Delete

output_length

[214] Fix | Delete

The caller passes in the maximum number of code points

[215] Fix | Delete

that it can receive into the output array (which is also

[216] Fix | Delete

the maximum number of flags that it can receive into the

[217] Fix | Delete

case_flags array, if case_flags is not a null pointer). On

[218] Fix | Delete

successful return it will contain the number of code points

[219] Fix | Delete

actually output (which is also the number of flags actually

[220] Fix | Delete

output, if case_flags is not a null pointer). The decoder

[221] Fix | Delete

will never need to output more code points than the number

[222] Fix | Delete

of ASCII code points in the input, because of the way the

[223] Fix | Delete

encoding is defined. The number of code points output

[224] Fix | Delete

cannot exceed the maximum possible value of a punycode_uint,

[225] Fix | Delete

even if the supplied output_length is greater than that.

[226] Fix | Delete

[227] Fix | Delete

Return value:

[228] Fix | Delete

[229] Fix | Delete

Can be any of the punycode_status values defined above. If not

[230] Fix | Delete

punycode_success, then output_length, output, and case_flags

[231] Fix | Delete

might contain garbage.

[232] Fix | Delete

*/

[233] Fix | Delete

[234] Fix | Delete

#ifdef __cplusplus

[235] Fix | Delete

}

[236] Fix | Delete

#endif

[237] Fix | Delete

#endif /* PUNYCODE_H */

[238] Fix | Delete

[239] Fix | Delete