1/* $Id: converter.h,v 1.1 2003/06/04 00:25:36 marka Exp $ */ 2/* 3 * Copyright (c) 2000 Japan Network Information Center. All rights reserved. 4 * 5 * By using this file, you agree to the terms and conditions set forth bellow. 6 * 7 * LICENSE TERMS AND CONDITIONS 8 * 9 * The following License Terms and Conditions apply, unless a different 10 * license is obtained from Japan Network Information Center ("JPNIC"), 11 * a Japanese association, Kokusai-Kougyou-Kanda Bldg 6F, 2-3-4 Uchi-Kanda, 12 * Chiyoda-ku, Tokyo 101-0047, Japan. 13 * 14 * 1. Use, Modification and Redistribution (including distribution of any 15 * modified or derived work) in source and/or binary forms is permitted 16 * under this License Terms and Conditions. 17 * 18 * 2. Redistribution of source code must retain the copyright notices as they 19 * appear in each source code file, this License Terms and Conditions. 20 * 21 * 3. Redistribution in binary form must reproduce the Copyright Notice, 22 * this License Terms and Conditions, in the documentation and/or other 23 * materials provided with the distribution. For the purposes of binary 24 * distribution the "Copyright Notice" refers to the following language: 25 * "Copyright (c) 2000-2002 Japan Network Information Center. All rights reserved." 26 * 27 * 4. The name of JPNIC may not be used to endorse or promote products 28 * derived from this Software without specific prior written approval of 29 * JPNIC. 30 * 31 * 5. Disclaimer/Limitation of Liability: THIS SOFTWARE IS PROVIDED BY JPNIC 32 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 33 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 34 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JPNIC BE LIABLE 35 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 36 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 37 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 38 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 39 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 40 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 41 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 42 */ 43 44#ifndef IDN_CONVERTER_H 45#define IDN_CONVERTER_H 1 46 47#ifdef __cplusplus 48extern "C" { 49#endif 50 51/* 52 * Codeset converter. 53 * 54 * This module provides conversions from some local codeset to UCS4 55 * and vice versa. 56 */ 57 58#include <idn/export.h> 59#include <idn/result.h> 60 61/* 62 * Converter context type (opaque). 63 */ 64typedef struct idn_converter *idn_converter_t; 65 66/* 67 * Conversion flags. 68 */ 69#define IDN_CONVERTER_DELAYEDOPEN 1 70#define IDN_CONVERTER_RTCHECK 2 71 72/* 73 * Encoding types. 74 */ 75#define IDN_NONACE 0 76#define IDN_ACE_STRICTCASE 1 77#define IDN_ACE_LOOSECASE 2 78 79/* 80 * Initialize module. Must be called before any other calls of 81 * the functions of this module. 82 * 83 * Returns: 84 * idn_success -- ok. 85 * idn_nomemory -- malloc failed. 86 */ 87IDN_EXPORT idn_result_t 88idn_converter_initialize(void); 89 90/* 91 * Create a conversion context. 92 * 93 * Returns: 94 * idn_success -- ok. 95 * idn_invalid_name -- specified codeset is not supported. 96 * idn_nomemory -- malloc failed. 97 * idn_failure -- other failure (unknown cause). 98 */ 99IDN_EXPORT idn_result_t 100idn_converter_create(const char *name, idn_converter_t *ctxp, 101 int flags); 102 103/* 104 * Decrement reference count of the converter `ctx' created by 105 * 'idn_converter_create', if it is still refered by another object. 106 * Otherwise, release all the memory allocated to the converter. 107 */ 108IDN_EXPORT void 109idn_converter_destroy(idn_converter_t ctx); 110 111/* 112 * Increment reference count of the converter `ctx' created by 113 * 'idn_converter_create'. 114 */ 115IDN_EXPORT void 116idn_converter_incrref(idn_converter_t ctx); 117 118/* 119 * Convert between local codeset and UCS4. Note that each conversion 120 * is started with initial state. 121 * 122 * Returns: 123 * idn_success -- ok. 124 * idn_buffer_overflow -- output buffer is too small. 125 * idn_invalid_encoding -- the input string has invalid/illegal 126 * byte sequence. 127 * idn_invalid_name -- codeset is not supported (this error 128 * should happen only if 'delayedopen' 129 * flag was set when idn_converter_create 130 * was called) 131 * idn_failure -- other failure. 132 */ 133IDN_EXPORT idn_result_t 134idn_converter_convfromucs4(idn_converter_t ctx, 135 const unsigned long *from, char *to, size_t tolen); 136 137IDN_EXPORT idn_result_t 138idn_converter_convtoucs4(idn_converter_t ctx, 139 const char *from, unsigned long *to, size_t tolen); 140 141/* 142 * Get the name of local codeset. The returned name may be different from 143 * the one specified to idn_converter_create, if the specified one was an 144 * alias. 145 * 146 * Returns: 147 * the local codeset name. 148 */ 149IDN_EXPORT char * 150idn_converter_localencoding(idn_converter_t ctx); 151 152/* 153 * Return the encoding type of this local encoding. 154 * 155 * Returns: 156 * IDN_NONACE -- encoding is not ACE. 157 * IDN_ACE_STRICTCASE -- encoding is ACE. 158 * decoder of this ACE preserve letter case. 159 * IDN_ACE_LOOSECASE -- encoding type is ACE. 160 * decoder cannot preserve letter case. 161 */ 162IDN_EXPORT int 163idn_converter_encodingtype(idn_converter_t ctx); 164 165/* 166 * Return if this local encoding is ACE (Ascii Compatible Encoding). 167 * 168 * Returns: 169 * 1 -- yes, it is ACE. 170 * 0 -- no. 171 */ 172IDN_EXPORT int 173idn_converter_isasciicompatible(idn_converter_t ctx); 174 175/* 176 * Register an alias for a codeset name. 177 * 178 * If first_item is 0, alias pattern is placed as the last item of the 179 * alias list. Otherwise, it is done as the first item. 180 * 181 * Returns: 182 * idn_success -- ok. 183 * idn_nomemory -- malloc failed. 184 */ 185IDN_EXPORT idn_result_t 186idn_converter_addalias(const char *alias_name, const char *real_name, 187 int first_item); 188 189/* 190 * Register aliases defined by the specified file. 191 * 192 * Returns: 193 * idn_success -- ok. 194 * idn_nofile -- no such file. 195 * idn_invalid_syntax -- file is malformed. 196 * idn_nomemory -- malloc failed. 197 */ 198IDN_EXPORT idn_result_t 199idn_converter_aliasfile(const char *path); 200 201/* 202 * Unregister all the aliases. 203 */ 204IDN_EXPORT idn_result_t 205idn_converter_resetalias(void); 206 207/* 208 * resolve real encoding name from alias information. 209 */ 210IDN_EXPORT const char * 211idn_converter_getrealname(const char *name); 212 213 214/* 215 * New converter registration. 216 */ 217 218/* 219 * Conversion operation functions. 220 */ 221typedef idn_result_t (*idn_converter_openproc_t)(idn_converter_t ctx, 222 void **privdata); 223typedef idn_result_t (*idn_converter_closeproc_t)(idn_converter_t ctx, 224 void *privdata); 225typedef idn_result_t 226 (*idn_converter_convfromucs4proc_t)(idn_converter_t ctx, 227 void *privdata, 228 const unsigned long *from, 229 char *to, size_t tolen); 230typedef idn_result_t 231 (*idn_converter_convtoucs4proc_t)(idn_converter_t ctx, 232 void *privdata, 233 const char *from, 234 unsigned long *to, 235 size_t tolen); 236 237/* 238 * Register a new converter. 239 * 'encoding_type' is a value which idn_converter_encodingtype() returns. 240 * 241 * Returns: 242 * idn_success -- ok. 243 * idn_nomemory -- malloc failed. 244 */ 245IDN_EXPORT idn_result_t 246idn_converter_register(const char *name, 247 idn_converter_openproc_t openfromucs4, 248 idn_converter_openproc_t opentoucs4, 249 idn_converter_convfromucs4proc_t convfromucs4, 250 idn_converter_convtoucs4proc_t convtoucs4, 251 idn_converter_closeproc_t close, 252 int encoding_type); 253 254#ifdef __cplusplus 255} 256#endif 257 258#endif /* IDN_CONVERTER_H */ 259