1/* $Id: mapper.h,v 1.1 2003/06/04 00:25:38 marka Exp $ */
2/*
3 * Copyright (c) 2001 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_MAPPER_H
45#define IDN_MAPPER_H 1
46
47#ifdef __cplusplus
48extern "C" {
49#endif
50
51/*
52 * Mapper.
53 *
54 * Perfom mapping the specified domain name.
55 */
56
57#include <idn/export.h>
58#include <idn/result.h>
59#include <idn/filemapper.h>
60#include <idn/nameprep.h>
61
62/*
63 * Map object type.
64 */
65typedef struct idn_mapper *idn_mapper_t;
66
67/*
68 * Initialize module.  Must be called before any other calls of
69 * the functions of this module.
70 *
71 * Returns:
72 *      idn_success             -- ok.
73 *      idn_nomemory            -- malloc failed.
74 */
75IDN_EXPORT idn_result_t
76idn_mapper_initialize(void);
77
78/*
79 * Create a mapper context.
80 *
81 * Returns:
82 *      idn_success             -- ok.
83 *      idn_nomemory            -- malloc failed.
84 */
85IDN_EXPORT idn_result_t
86idn_mapper_create(idn_mapper_t *ctxp);
87
88/*
89 * Decrement reference count of the mapper `ctx' created by
90 * 'idn_mapper_create', if it is still refered by another object.
91 * Otherwise, release all the memory allocated to the mapper.
92 */
93IDN_EXPORT void
94idn_mapper_destroy(idn_mapper_t ctx);
95
96/*
97 * Increment reference count of the mapper `ctx' created by
98 * 'idn_mapper_create'.
99 */
100IDN_EXPORT void
101idn_mapper_incrref(idn_mapper_t ctx);
102
103/*
104 * Add mapping scheme `name' to the mapper to `ctx'.
105 *
106 * Returns:
107 *      idn_success             -- ok.
108 *      idn_invalid_name        -- the given name is not valid.
109 *      idn_nomemory            -- malloc failed.
110 */
111IDN_EXPORT idn_result_t
112idn_mapper_add(idn_mapper_t ctx, const char *name);
113
114IDN_EXPORT idn_result_t
115idn_mapper_addall(idn_mapper_t ctx, const char **names, int nnames);
116
117/*
118 * Map an UCS4 string.  All mapping schemes regsitered in `ctx'
119 * are applied in the regisration order.
120 *
121 * Returns:
122 *      idn_success             -- ok.
123 *      idn_nomemory            -- malloc failed.
124 *      idn_buffer_overflow     -- output buffer is too small.
125 */
126IDN_EXPORT idn_result_t
127idn_mapper_map(idn_mapper_t ctx, const unsigned long *from,
128	       unsigned long *to, size_t tolen);
129
130/*
131 * Mapping procedure type.
132 */
133typedef idn_result_t (*idn_mapper_createproc_t)(const char *parameter,
134						void **ctxp);
135typedef void         (*idn_mapper_destroyproc_t)(void *ctxp);
136typedef idn_result_t (*idn_mapper_mapproc_t)(void *ctx,
137					     const unsigned long *from,
138                                             unsigned long *, size_t);
139
140/*
141 * Register a new mapping scheme.
142 *
143 * You can override the default normalization schemes, if you want.
144 *
145 * Returns:
146 *      idn_success             -- ok.
147 *      idn_nomemory            -- malloc failed.
148 */
149IDN_EXPORT idn_result_t
150idn_mapper_register(const char *prefix,
151		    idn_mapper_createproc_t create,
152		    idn_mapper_destroyproc_t destroy,
153		    idn_mapper_mapproc_t map);
154
155#ifdef __cplusplus
156}
157#endif
158
159#endif /* IDN_MAPPER_H */
160