1/*
2 *******************************************************************************
3 *
4 *   Copyright (C) 2003-2010, International Business Machines
5 *   Corporation and others.  All Rights Reserved.
6 *
7 *******************************************************************************
8 *   file name:  usprep.h
9 *   encoding:   US-ASCII
10 *   tab size:   8 (not used)
11 *   indentation:4
12 *
13 *   created on: 2003jul2
14 *   created by: Ram Viswanadha
15 */
16
17#ifndef __USPREP_H__
18#define __USPREP_H__
19
20/**
21 * \file
22 * \brief C API: Implements the StringPrep algorithm.
23 */
24
25#include "unicode/utypes.h"
26#include "unicode/localpointer.h"
27
28/**
29 *
30 * StringPrep API implements the StingPrep framework as described by RFC 3454.
31 * StringPrep prepares Unicode strings for use in network protocols.
32 * Profiles of StingPrep are set of rules and data according to with the
33 * Unicode Strings are prepared. Each profiles contains tables which describe
34 * how a code point should be treated. The tables are broadly classied into
35 * <ul>
36 *     <li> Unassinged Table: Contains code points that are unassigned
37 *          in the Unicode Version supported by StringPrep. Currently
38 *          RFC 3454 supports Unicode 3.2. </li>
39 *     <li> Prohibited Table: Contains code points that are prohibted from
40 *          the output of the StringPrep processing function. </li>
41 *     <li> Mapping Table: Contains code ponts that are deleted from the output or case mapped. </li>
42 * </ul>
43 *
44 * The procedure for preparing Unicode strings:
45 * <ol>
46 *      <li> Map: For each character in the input, check if it has a mapping
47 *           and, if so, replace it with its mapping. </li>
48 *      <li> Normalize: Possibly normalize the result of step 1 using Unicode
49 *           normalization. </li>
50 *      <li> Prohibit: Check for any characters that are not allowed in the
51 *        output.  If any are found, return an error.</li>
52 *      <li> Check bidi: Possibly check for right-to-left characters, and if
53 *           any are found, make sure that the whole string satisfies the
54 *           requirements for bidirectional strings.  If the string does not
55 *           satisfy the requirements for bidirectional strings, return an
56 *           error.  </li>
57 * </ol>
58 * @author Ram Viswanadha
59 */
60#if !UCONFIG_NO_IDNA
61
62#include "unicode/parseerr.h"
63
64/**
65 * The StringPrep profile
66 * @stable ICU 2.8
67 */
68typedef struct UStringPrepProfile UStringPrepProfile;
69
70
71/**
72 * Option to prohibit processing of unassigned code points in the input
73 *
74 * @see  usprep_prepare
75 * @stable ICU 2.8
76 */
77#define USPREP_DEFAULT 0x0000
78
79/**
80 * Option to allow processing of unassigned code points in the input
81 *
82 * @see  usprep_prepare
83 * @stable ICU 2.8
84 */
85#define USPREP_ALLOW_UNASSIGNED 0x0001
86
87/**
88 * enums for the standard stringprep profile types
89 * supported by usprep_openByType.
90 * @see usprep_openByType
91 * @stable ICU 4.2
92 */
93typedef enum UStringPrepProfileType {
94    /**
95     * RFC3491 Nameprep
96     * @stable ICU 4.2
97     */
98    USPREP_RFC3491_NAMEPREP,
99    /**
100     * RFC3530 nfs4_cs_prep
101     * @stable ICU 4.2
102     */
103	USPREP_RFC3530_NFS4_CS_PREP,
104    /**
105     * RFC3530 nfs4_cs_prep with case insensitive option
106     * @stable ICU 4.2
107     */
108	USPREP_RFC3530_NFS4_CS_PREP_CI,
109    /**
110     * RFC3530 nfs4_cis_prep
111     * @stable ICU 4.2
112     */
113	USPREP_RFC3530_NFS4_CIS_PREP,
114    /**
115     * RFC3530 nfs4_mixed_prep for prefix
116     * @stable ICU 4.2
117     */
118	USPREP_RFC3530_NFS4_MIXED_PREP_PREFIX,
119    /**
120     * RFC3530 nfs4_mixed_prep for suffix
121     * @stable ICU 4.2
122     */
123	USPREP_RFC3530_NFS4_MIXED_PREP_SUFFIX,
124    /**
125     * RFC3722 iSCSI
126     * @stable ICU 4.2
127     */
128	USPREP_RFC3722_ISCSI,
129    /**
130     * RFC3920 XMPP Nodeprep
131     * @stable ICU 4.2
132     */
133	USPREP_RFC3920_NODEPREP,
134    /**
135     * RFC3920 XMPP Resourceprep
136     * @stable ICU 4.2
137     */
138	USPREP_RFC3920_RESOURCEPREP,
139    /**
140     * RFC4011 Policy MIB Stringprep
141     * @stable ICU 4.2
142     */
143	USPREP_RFC4011_MIB,
144    /**
145     * RFC4013 SASLprep
146     * @stable ICU 4.2
147     */
148    USPREP_RFC4013_SASLPREP,
149    /**
150     * RFC4505 trace
151     * @stable ICU 4.2
152     */
153	USPREP_RFC4505_TRACE,
154    /**
155     * RFC4518 LDAP
156     * @stable ICU 4.2
157     */
158	USPREP_RFC4518_LDAP,
159    /**
160     * RFC4518 LDAP for case ignore, numeric and stored prefix
161     * matching rules
162     * @stable ICU 4.2
163     */
164	USPREP_RFC4518_LDAP_CI
165} UStringPrepProfileType;
166
167/**
168 * Creates a StringPrep profile from the data file.
169 *
170 * @param path      string containing the full path pointing to the directory
171 *                  where the profile reside followed by the package name
172 *                  e.g. "/usr/resource/my_app/profiles/mydata" on a Unix system.
173 *                  if NULL, ICU default data files will be used.
174 * @param fileName  name of the profile file to be opened
175 * @param status    ICU error code in/out parameter. Must not be NULL.
176 *                  Must fulfill U_SUCCESS before the function call.
177 * @return Pointer to UStringPrepProfile that is opened. Should be closed by
178 * calling usprep_close()
179 * @see usprep_close()
180 * @stable ICU 2.8
181 */
182U_STABLE UStringPrepProfile* U_EXPORT2
183usprep_open(const char* path,
184            const char* fileName,
185            UErrorCode* status);
186
187/**
188 * Creates a StringPrep profile for the specified profile type.
189 *
190 * @param type		The profile type
191 * @param status    ICU error code in/out parameter. Must not be NULL.
192 *                  Must fulfill U_SUCCESS before the function call.
193 * @return          Pointer to UStringPrepProfile that is opened. Should be closed by
194 *                  calling usprep_close()
195 * @see usprep_close()
196 * @stable ICU 4.2
197 */
198U_STABLE UStringPrepProfile* U_EXPORT2
199usprep_openByType(UStringPrepProfileType type,
200				  UErrorCode* status);
201
202/**
203 * Closes the profile
204 * @param profile The profile to close
205 * @stable ICU 2.8
206 */
207U_STABLE void U_EXPORT2
208usprep_close(UStringPrepProfile* profile);
209
210#if U_SHOW_CPLUSPLUS_API
211
212U_NAMESPACE_BEGIN
213
214/**
215 * \class LocalUStringPrepProfilePointer
216 * "Smart pointer" class, closes a UStringPrepProfile via usprep_close().
217 * For most methods see the LocalPointerBase base class.
218 *
219 * @see LocalPointerBase
220 * @see LocalPointer
221 * @stable ICU 4.4
222 */
223U_DEFINE_LOCAL_OPEN_POINTER(LocalUStringPrepProfilePointer, UStringPrepProfile, usprep_close);
224
225U_NAMESPACE_END
226
227#endif
228
229/**
230 * Prepare the input buffer for use in applications with the given profile. This operation maps, normalizes(NFKC),
231 * checks for prohited and BiDi characters in the order defined by RFC 3454
232 * depending on the options specified in the profile.
233 *
234 * @param prep          The profile to use
235 * @param src           Pointer to UChar buffer containing the string to prepare
236 * @param srcLength     Number of characters in the source string
237 * @param dest          Pointer to the destination buffer to receive the output
238 * @param destCapacity  The capacity of destination array
239 * @param options       A bit set of options:
240 *
241 *  - USPREP_NONE               Prohibit processing of unassigned code points in the input
242 *
243 *  - USPREP_ALLOW_UNASSIGNED   Treat the unassigned code points are in the input
244 *                              as normal Unicode code points.
245 *
246 * @param parseError        Pointer to UParseError struct to receive information on position
247 *                          of error if an error is encountered. Can be NULL.
248 * @param status            ICU in/out error code parameter.
249 *                          U_INVALID_CHAR_FOUND if src contains
250 *                          unmatched single surrogates.
251 *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
252 *                          too many code points.
253 *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
254 * @return The number of UChars in the destination buffer
255 * @stable ICU 2.8
256 */
257
258U_STABLE int32_t U_EXPORT2
259usprep_prepare(   const UStringPrepProfile* prep,
260                  const UChar* src, int32_t srcLength,
261                  UChar* dest, int32_t destCapacity,
262                  int32_t options,
263                  UParseError* parseError,
264                  UErrorCode* status );
265
266
267#endif /* #if !UCONFIG_NO_IDNA */
268
269#endif
270