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