1/* $Id: res.h,v 1.1 2003/06/04 00:25:41 marka Exp $ */ 2/* 3 * Copyright (c) 2001,2002 Japan Network Information Center. 4 * All rights reserved. 5 * 6 * By using this file, you agree to the terms and conditions set forth bellow. 7 * 8 * LICENSE TERMS AND CONDITIONS 9 * 10 * The following License Terms and Conditions apply, unless a different 11 * license is obtained from Japan Network Information Center ("JPNIC"), 12 * a Japanese association, Kokusai-Kougyou-Kanda Bldg 6F, 2-3-4 Uchi-Kanda, 13 * Chiyoda-ku, Tokyo 101-0047, Japan. 14 * 15 * 1. Use, Modification and Redistribution (including distribution of any 16 * modified or derived work) in source and/or binary forms is permitted 17 * under this License Terms and Conditions. 18 * 19 * 2. Redistribution of source code must retain the copyright notices as they 20 * appear in each source code file, this License Terms and Conditions. 21 * 22 * 3. Redistribution in binary form must reproduce the Copyright Notice, 23 * this License Terms and Conditions, in the documentation and/or other 24 * materials provided with the distribution. For the purposes of binary 25 * distribution the "Copyright Notice" refers to the following language: 26 * "Copyright (c) 2000-2002 Japan Network Information Center. All rights reserved." 27 * 28 * 4. The name of JPNIC may not be used to endorse or promote products 29 * derived from this Software without specific prior written approval of 30 * JPNIC. 31 * 32 * 5. Disclaimer/Limitation of Liability: THIS SOFTWARE IS PROVIDED BY JPNIC 33 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 34 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 35 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JPNIC BE LIABLE 36 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 37 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 38 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 39 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 40 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 41 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 42 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 43 */ 44 45#ifndef IDN_RES_H 46#define IDN_RES_H 1 47 48#ifdef __cplusplus 49extern "C" { 50#endif 51 52/* 53 * Resolver library support. 54 * 55 * All the functions provided by this module requires IDN resolver 56 * configuration context of type 'idn_resconf_t' as an argument. 57 * This context holds information described in the configuration file 58 * (idn.conf). See idn_resconf module for details. 59 * 60 * All functions also accept NULL as the context, but since 61 * no conversion/normalization will be done in this case, it is 62 * pretty useless. 63 */ 64 65#include <idn/export.h> 66#include <idn/resconf.h> 67#include <idn/result.h> 68 69typedef unsigned long idn_action_t; 70 71/* 72 * Actions 73 */ 74#define IDN_LOCALCONV 0x00000001 /* Local encoding <-> UTF-8 conversion */ 75#define IDN_DELIMMAP 0x00000002 /* Delimiter mapping */ 76#define IDN_LOCALMAP 0x00000004 /* Local mapping */ 77#define IDN_MAP 0x00000008 /* NAMEPREP map */ 78#define IDN_NORMALIZE 0x00000010 /* NAMEPREP normalize */ 79#define IDN_PROHCHECK 0x00000020 /* NAMEPREP prohibited character check */ 80#define IDN_UNASCHECK 0x00000040 /* Unassigned code point check */ 81#define IDN_BIDICHECK 0x00000080 /* bidirectional string check */ 82#define IDN_ASCCHECK 0x00000100 /* Non-LDH ASCII check */ 83#define IDN_IDNCONV 0x00000200 /* UTF-8 <-> IDN encoding conversion */ 84#define IDN_LENCHECK 0x00000400 /* Label length check */ 85#define IDN_RTCHECK 0x00000800 /* Round trip check */ 86#define IDN_UNDOIFERR 0x00001000 /* Option: undo if error occurs */ 87 88#define IDN_ENCODE_QUERY 0x00002000 /* Encode query string */ 89#define IDN_DECODE_QUERY 0x00004000 /* Decode query string */ 90 91#define IDN_ENCODE_APP \ 92(IDN_ENCODE_QUERY | IDN_ASCCHECK) /* Standard encode */ 93#define IDN_DECODE_APP \ 94(IDN_DECODE_QUERY | IDN_ASCCHECK) /* Standard decode */ 95 96#define IDN_ENCODE_STORED \ 97(IDN_ENCODE_QUERY | IDN_ASCCHECK | IDN_UNASCHECK) /* Encode query string */ 98#define IDN_DECODE_STORED \ 99(IDN_DECODE_QUERY | IDN_ASCCHECK | IDN_UNASCHECK) /* Decode query string */ 100 101 102#define IDN_NAMEPREP \ 103(IDN_MAP | IDN_NORMALIZE | IDN_PROHCHECK | IDN_BIDICHECK) 104 105/* 106 * Enable or disable IDN conversion scheme. 107 * 108 * If on_off is 0, IDN conversion scheme is disabled. Otherwise, IDN 109 * conversion is enabled even when IDN_DISABLE is defined. 110 */ 111IDN_EXPORT void 112idn_res_enable(int on_off); 113 114/* 115 * Encode internationalized domain name. 116 * 117 * The encoding process consists of the following 7 steps. 118 * 119 * 1. Local encoding to UTF-8 conversion 120 * Converts a domain name written with local encoding (e.g. ISO- 121 * 8859-1) to UTF-8. 122 * 2. Delimiter mapping, 123 * Maps certain characters to period (U+002E, FULL STOP). 124 * 3. Local mapping 125 * Apply character mappings according with the TLD of the domain 126 * name. 127 * 4. NAMEPREP 128 * Perform NAME preparation described in RFC3491. 129 * This step consists of the following 4 steps: 130 * 4.1. Mapping 131 * 4.2. Normalization 132 * 4.3. Prohibited character check 133 * 4.4. Unassigned check 134 * 5. ASCII range character check 135 * Checks if the domain name contains non-LDH ASCII character (not 136 * alpha-numeric or hypen), or it begins or end with hypen. 137 * 6. UTF-8 to IDN encoding conversion. 138 * Converts the domain name from UTF-8 to ACE (e.g. Punycode). 139 * 7. Length check 140 * Checks the length of each label. 141 * 142 * 'actions' specifies actions and options of the encoding procedure. 143 * Its value is a bitwise-or of the following flags: 144 * 145 * IDN_LOCALCONV -- perform local encoding to UTF-8 conversion (step 1) 146 * IDN_DELIMMAP -- perform delimiter mapping (step 2) 147 * IDN_LOCALMAP -- perform local mapping (step 3) 148 * IDN_MAP -- perform mapping (step 4.1) 149 * IDN_NORMALIZE -- perform normalization (step 4.2) 150 * IDN_PROHCHECK -- perform prohibited character check (step 4.3) 151 * IDN_UNASCHECK -- perform unassigned codepoint check (step 4.4) 152 * IDN_ASCCHECK -- perform ASCII range character check (step 5) 153 * IDN_IDNCONV -- perform UTF-8 to IDN encoding conversion (step 6) 154 * IDN_LENCHECK -- perform length check (step 7) 155 * 156 * Also the following flags are provided for convinience: 157 * 158 * IDN_ENCODE_QUERY -- On libidnkit, perform step 1..7, except for step 159 * 4.4 and 5. 160 * On libidnkitlite, perform step 2..7, except for 161 * step 4.4 and 5. 162 * IDN_ENCODE_STORED -- On libidnkit, perform step 1..7, except for step 163 * 5. 164 * On libidnkitlite, perform step 2..7, except for 165 * step 5. 166 * IDN_ENCODE_APP -- Same as IDN_ENCODE_QUERY. 167 * IDN_NAMEPREP -- perform NAMEPREP (step 4) without unassigned 168 * codepoint check (step 4.4). 169 * 170 * The following flag does not corresponding to a particular action, 171 * but an option of conversion process: 172 * 173 * IDN_UNDOIFERR -- If any step fails, the original input name is 174 * returned. 175 * 176 * Note that if no flags are specified, 'idn_encodename' does nothing 177 * fancy, just copies the given name verbatim. 178 * 179 * Returns: 180 * idn_success -- ok. 181 * idn_invalid_action -- invalid action flag specified. 182 * idn_invalid_encoding -- the given string has invalid/illegal 183 * byte sequence. 184 * idn_invalid_length -- invalid length of a label. 185 * idn_prohibited -- prohibited/unassigned code point found. 186 * idn_buffer_overflow -- 'tolen' is too small. 187 * idn_nomemory -- malloc failed. 188 * 189 * Also, if this function is called without calling 'idn_nameinit', 190 * the following error codes might be returned. 191 * idn_nofile -- cannot open the configuration file. 192 * idn_invalid_syntax -- syntax error found in the file. 193 * idn_invalid_name -- there are invalid names (encoding, 194 * normalization etc.). 195 */ 196IDN_EXPORT idn_result_t 197idn_res_encodename(idn_resconf_t ctx, idn_action_t actions, const char *from, 198 char *to, size_t tolen); 199 200/* 201 * Decode internationalized domain name. 202 * 203 * The decoding process consists of the following 5 steps. 204 * 205 * 1. delimiter mapping 206 * Maps certain characters to period (U+002E, FULL STOP). 207 * 2. NAMEPREP 208 * Perform NAME preparation described in RFC3491. 209 * This step consists of the following 4 steps: 210 * 2.1. Mapping 211 * 2.2. Normalization 212 * 2.3. Prohibited character check 213 * 2.4. Unassigned check 214 * 3. IDN encoding to UTF-8 conversion. 215 * Converts the domain name from ACE (e.g. Punycode) to UCS4. 216 * 4. Perform round-trip check. 217 * Encode the result of step 3, and then compare it with the result 218 * of the step 2. If they are different, the check is failed. 219 * 5. Convert UTF-8 to local encoding. 220 * If a character in the domain name cannot be converted to local 221 * encoding, the conversion is failed. 222 * 223 * 'actions' specifies actions of the decoding procedure. 224 * Its value is a bitwise-or of the following flags: 225 * 226 * IDN_DELIMMAP -- perform delimiter mapping (step 1) 227 * IDN_MAP -- perform mapping (step 2.1) 228 * IDN_NORMALIZE -- perform normalization (step 2.2) 229 * IDN_PROHCHECK -- perform prohibited character check (step 2.3) 230 * IDN_UNASCHECK -- perform unassigned codepoint check (step 2.4) 231 * IDN_IDNCONV -- perform IDN encoding to UTF-8 conversion (step 3) 232 * IDN_RTCHECK -- perform round-trip check (step 4) 233 * IDN_ASCCHECK -- perform ASCII range character check while 234 * round-trip check (step 4.1) 235 * IDN_LOCALCONV -- perform UTF-8 to local encoding conversion (step 5) 236 * 237 * Also the following flags are provided for the convenience: 238 * 239 * IDN_DECODE_QUERY -- On libidnkit, perform step 1..5, except for step 240 * 2.4 and 4.1. 241 * On libidnkitlite, perform step 1..3, except for 242 * step 2.4 and 4.1. 243 * IDN_DECODE_STORED -- On libidnkit, perform step 1..5, except for step 244 * 4.1. 245 * On libidnkitlite, perform step 1..3, except for 246 * step 4.1. 247 * IDN_DECODE_APP -- Same as IDN_DECODE_QUERY. 248 * IDN_NAMEPREP -- perform NAMEPREP (step 2) without unassigned 249 * codepoint check (step 2.4). 250 * 251 * If any step fails, the original input name is returned. 252 * 'actions' specifies what actions to take when decoding, and is 253 * a bitwise-or of the following flags: 254 * 255 * Note that if no flags are specified, 'idn_decodename' does nothing 256 * but copying the given name verbatim. 257 * 258 * Returns: 259 * idn_success -- ok. 260 * idn_invalid_action -- invalid action flag specified. 261 * idn_invalid_encoding -- the given string has invalid/illegal 262 * byte sequence. 263 * idn_buffer_overflow -- 'tolen' is too small. 264 * idn_invalid_action -- length of a label is not 1..63 characters. 265 * idn_nomemory -- malloc failed. 266 * 267 * Also, if this function is called without calling 'idn_nameinit', 268 * the following error codes might be returned. 269 * idn_nofile -- cannot open the configuration file. 270 * idn_invalid_syntax -- syntax error found in the file. 271 * idn_invalid_name -- there are invalid names (encoding, 272 * normalization etc.). 273 */ 274IDN_EXPORT idn_result_t 275idn_res_decodename(idn_resconf_t ctx, idn_action_t actions, const char *from, 276 char *to, size_t tolen); 277 278/* 279 * Decode internationalized domain name with auxiliary encoding 280 * support. 281 * 282 * This is another API for IDN string decode. The difference between 283 * two is whether the encoding conversion from auxiliary encoding to 284 * UTF-8 occurs prior to the actual decode process (read description 285 * of idn_res_decodename() above) or not. 286 * 287 * If auxencoding is NULL, from is treated as UTF-8 encoded string. 288 * 289 * Other arguments serve exactly same role as those of 290 * idn_res_decodename(). 291 */ 292idn_result_t 293idn_res_decodename2(idn_resconf_t ctx, idn_action_t actions, const char *from, 294 char *to, size_t tolen, const char *auxencoding); 295 296/* 297 * Convert `actions' to a string, and then return the string. 298 * This function is for internal use only. 299 * 300 * Note that this function returns a pointer to static buffer. 301 */ 302extern const char * 303idn__res_actionstostring(idn_action_t actions); 304 305#ifdef __cplusplus 306} 307#endif 308 309#endif /* IDN_RES_H */ 310