1 /* $Id: api.h,v 1.1 2003/06/04 00:25:35 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_API_H 46 #define IDN_API_H 1 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 #include <idn/export.h> 53 #include <idn/result.h> 54 #include <idn/res.h> 55 56 /* 57 * Application Programming Interface for Internationalized Domain Name 58 * Handling. This module provides high-level APIs for ordinary applications. 59 * Low-level APIs are also available. See "res.h" for details. 60 */ 61 62 /* 63 * Enable or disable IDN conversion scheme. 64 * 65 * If on_off is 0, IDN conversion scheme is disabled. Otherwise, IDN 66 * conversion is enabled even when IDN_DISABLE is defined. 67 */ 68 IDN_EXPORT void 69 idn_enable(int on_off); 70 71 /* 72 * Set configuration file name. 73 * This function is for private use only. 74 * 75 * When idn_nameinit(1) is called, this module loads `file'. 76 * 77 * Returns: 78 * idn_success -- ok. 79 * idn_nomemory -- malloc failed. 80 * idn_failure -- idn_nameinit() has already been 81 * called. 82 */ 83 extern idn_result_t 84 idn__setconffile(const char *file); 85 86 /* 87 * Initialize this module, and load configuration from the default 88 * configuration file (idn.conf). 89 * 90 * The initialization will be done only once when this function is 91 * called first, while either loading of the configuration file or 92 * setting the defaults behavior without the configuration file will 93 * be done every time it is called. 94 * 95 * If load_file is 0, this will set the defaults behavior without the 96 * configuration file. Otherwise, loading of the configuration file 97 * occurs. 98 * 99 * If 'idn_encodename' or 'idn_decodename' is called without calling 100 * this function, implicit initialization without the configuration 101 * file will be done prior to encoding/decoding process. 102 * 103 * Returns: 104 * idn_success -- ok. 105 * idn_nofile -- cannot open the configuration file. 106 * idn_invalid_syntax -- syntax error found in the file. 107 * idn_invalid_name -- there are invalid names (encoding, 108 * normalization etc.). 109 * idn_nomemory -- malloc failed. 110 */ 111 IDN_EXPORT idn_result_t 112 idn_nameinit(int load_file); 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 */ 196 IDN_EXPORT idn_result_t 197 idn_encodename(idn_action_t actions, const char *from, char *to, size_t tolen); 198 199 /* 200 * Decode internationalized domain name. 201 * 202 * The decoding process consists of the following 5 steps. 203 * 204 * 1. delimiter mapping 205 * Maps certain characters to period (U+002E, FULL STOP). 206 * 2. NAMEPREP 207 * Perform NAME preparation described in RFC3491. 208 * This step consists of the following 4 steps: 209 * 2.1. Mapping 210 * 2.2. Normalization 211 * 2.3. Prohibited character check 212 * 2.4. Unassigned check 213 * 3. IDN encoding to UTF-8 conversion. 214 * Converts the domain name from ACE (e.g. Punycode) to UCS4. 215 * 4. Perform round-trip check. 216 * Encode the result of step 3, and then compare it with the result 217 * of the step 2. If they are different, the check is failed. 218 * 5. Convert UTF-8 to local encoding. 219 * If a character in the domain name cannot be converted to local 220 * encoding, the conversion is failed. 221 * 222 * 'actions' specifies actions of the decoding procedure. 223 * Its value is a bitwise-or of the following flags: 224 * 225 * IDN_DELIMMAP -- perform delimiter mapping (step 1) 226 * IDN_MAP -- perform mapping (step 2.1) 227 * IDN_NORMALIZE -- perform normalization (step 2.2) 228 * IDN_PROHCHECK -- perform prohibited character check (step 2.3) 229 * IDN_UNASCHECK -- perform unassigned codepoint check (step 2.4) 230 * IDN_IDNCONV -- perform IDN encoding to UTF-8 conversion (step 3) 231 * IDN_RTCHECK -- perform round-trip check (step 4) 232 * IDN_ASCCHECK -- perform ASCII range character check while 233 * round-trip check (step 4.1) 234 * IDN_LOCALCONV -- perform UTF-8 to local encoding conversion (step 5) 235 * 236 * Also the following flags are provided for the convenience: 237 * 238 * IDN_DECODE_QUERY -- On libidnkit, perform step 1..5, except for step 239 * 2.4 and 4.1. 240 * On libidnkitlite, perform step 1..3, except for 241 * step 2.4 and 4.1. 242 * IDN_DECODE_STORED -- On libidnkit, perform step 1..5, except for step 243 * 4.1. 244 * On libidnkitlite, perform step 1..3, except for 245 * step 4.1. 246 * IDN_DECODE_APP -- Same as IDN_DECODE_QUERY. 247 * IDN_NAMEPREP -- perform NAMEPREP (step 2) without unassigned 248 * codepoint check (step 2.4). 249 * 250 * If any step fails, the original input name is returned. 251 * 'actions' specifies what actions to take when decoding, and is 252 * a bitwise-or of the following flags: 253 * 254 * Note that if no flags are specified, 'idn_decodename' does nothing 255 * but copying the given name verbatim. 256 * 257 * Returns: 258 * idn_success -- ok. 259 * idn_invalid_action -- invalid action flag specified. 260 * idn_invalid_encoding -- the given string has invalid/illegal 261 * byte sequence. 262 * idn_buffer_overflow -- 'tolen' is too small. 263 * idn_invalid_length -- length of a label is not 1..63 characters. 264 * idn_nomemory -- malloc failed. 265 * 266 * Also, if this function is called without calling 'idn_nameinit', 267 * the following error codes might be returned. 268 * idn_nofile -- cannot open the configuration file. 269 * idn_invalid_syntax -- syntax error found in the file. 270 * idn_invalid_name -- there are invalid names (encoding, 271 * normalization etc.). 272 */ 273 IDN_EXPORT idn_result_t 274 idn_decodename(idn_action_t actions, const char *from, char *to, size_t tolen); 275 276 /* 277 * Decode internationalized domain name with auxiliary encoding 278 * support. 279 * 280 * This is another API for IDN string decode. The difference between 281 * two is whether the encoding conversion from auxiliary encoding to 282 * UTF-8 occurs prior to the actual decode process (read description 283 * of idn_res_decodename() above) or not. 284 * 285 * If auxencoding is NULL, from is treated as UTF-8 encoded string. 286 * 287 * Other arguments serve exactly same role as those of 288 * idn_res_decodename(). 289 */ 290 idn_result_t 291 idn_decodename2(idn_action_t actions, const char *from, char *to, size_t tolen, 292 const char *auxencoding); 293 294 #ifdef __cplusplus 295 } 296 #endif 297 298 #endif /* IDN_API_H */ 299