include/unicode/usprep.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004  *******************************************************************************
0005  *
0006  *   Copyright (C) 2003-2014, International Business Machines
0007  *   Corporation and others.  All Rights Reserved.
0008  *
0009  *******************************************************************************
0010  *   file name:  usprep.h
0011  *   encoding:   UTF-8
0012  *   tab size:   8 (not used)
0013  *   indentation:4
0014  *
0015  *   created on: 2003jul2
0016  *   created by: Ram Viswanadha
0017  */
0018
0019 #ifndef __USPREP_H__
0020 #define __USPREP_H__
0021
0022 /**
0023  * \file
0024  * \brief C API: Implements the StringPrep algorithm.
0025  */
0026
0027 #include "unicode/utypes.h"
0028
0029 #if U_SHOW_CPLUSPLUS_API
0030 #include "unicode/localpointer.h"
0031 #endif   // U_SHOW_CPLUSPLUS_API
0032
0033 /**
0034  *
0035  * StringPrep API implements the StingPrep framework as described by RFC 3454.
0036  * StringPrep prepares Unicode strings for use in network protocols.
0037  * Profiles of StingPrep are set of rules and data according to with the
0038  * Unicode Strings are prepared. Each profiles contains tables which describe
0039  * how a code point should be treated. The tables are broadly classified into
0040  * <ul>
0041  *     <li> Unassigned Table: Contains code points that are unassigned
0042  *          in the Unicode Version supported by StringPrep. Currently
0043  *          RFC 3454 supports Unicode 3.2. </li>
0044  *     <li> Prohibited Table: Contains code points that are prohibited from
0045  *          the output of the StringPrep processing function. </li>
0046  *     <li> Mapping Table: Contains code points that are deleted from the output or case mapped. </li>
0047  * </ul>
0048  *
0049  * The procedure for preparing Unicode strings:
0050  * <ol>
0051  *      <li> Map: For each character in the input, check if it has a mapping
0052  *           and, if so, replace it with its mapping. </li>
0053  *      <li> Normalize: Possibly normalize the result of step 1 using Unicode
0054  *           normalization. </li>
0055  *      <li> Prohibit: Check for any characters that are not allowed in the
0056  *        output.  If any are found, return an error.</li>
0057  *      <li> Check bidi: Possibly check for right-to-left characters, and if
0058  *           any are found, make sure that the whole string satisfies the
0059  *           requirements for bidirectional strings.  If the string does not
0060  *           satisfy the requirements for bidirectional strings, return an
0061  *           error.  </li>
0062  * </ol>
0063  * @author Ram Viswanadha
0064  */
0065 #if !UCONFIG_NO_IDNA
0066
0067 #include "unicode/parseerr.h"
0068
0069 /**
0070  * The StringPrep profile
0071  * @stable ICU 2.8
0072  */
0073 typedef struct UStringPrepProfile UStringPrepProfile;
0074
0075
0076 /**
0077  * Option to prohibit processing of unassigned code points in the input
0078  *
0079  * @see  usprep_prepare
0080  * @stable ICU 2.8
0081  */
0082 #define USPREP_DEFAULT 0x0000
0083
0084 /**
0085  * Option to allow processing of unassigned code points in the input
0086  *
0087  * @see  usprep_prepare
0088  * @stable ICU 2.8
0089  */
0090 #define USPREP_ALLOW_UNASSIGNED 0x0001
0091
0092 /**
0093  * enums for the standard stringprep profile types
0094  * supported by usprep_openByType.
0095  * @see usprep_openByType
0096  * @stable ICU 4.2
0097  */
0098 typedef enum UStringPrepProfileType {
0099     /**
0100      * RFC3491 Nameprep
0101      * @stable ICU 4.2
0102      */
0103     USPREP_RFC3491_NAMEPREP,
0104     /**
0105      * RFC3530 nfs4_cs_prep
0106      * @stable ICU 4.2
0107      */
0108     USPREP_RFC3530_NFS4_CS_PREP,
0109     /**
0110      * RFC3530 nfs4_cs_prep with case insensitive option
0111      * @stable ICU 4.2
0112      */
0113     USPREP_RFC3530_NFS4_CS_PREP_CI,
0114     /**
0115      * RFC3530 nfs4_cis_prep
0116      * @stable ICU 4.2
0117      */
0118     USPREP_RFC3530_NFS4_CIS_PREP,
0119     /**
0120      * RFC3530 nfs4_mixed_prep for prefix
0121      * @stable ICU 4.2
0122      */
0123     USPREP_RFC3530_NFS4_MIXED_PREP_PREFIX,
0124     /**
0125      * RFC3530 nfs4_mixed_prep for suffix
0126      * @stable ICU 4.2
0127      */
0128     USPREP_RFC3530_NFS4_MIXED_PREP_SUFFIX,
0129     /**
0130      * RFC3722 iSCSI
0131      * @stable ICU 4.2
0132      */
0133     USPREP_RFC3722_ISCSI,
0134     /**
0135      * RFC3920 XMPP Nodeprep
0136      * @stable ICU 4.2
0137      */
0138     USPREP_RFC3920_NODEPREP,
0139     /**
0140      * RFC3920 XMPP Resourceprep
0141      * @stable ICU 4.2
0142      */
0143     USPREP_RFC3920_RESOURCEPREP,
0144     /**
0145      * RFC4011 Policy MIB Stringprep
0146      * @stable ICU 4.2
0147      */
0148     USPREP_RFC4011_MIB,
0149     /**
0150      * RFC4013 SASLprep
0151      * @stable ICU 4.2
0152      */
0153     USPREP_RFC4013_SASLPREP,
0154     /**
0155      * RFC4505 trace
0156      * @stable ICU 4.2
0157      */
0158     USPREP_RFC4505_TRACE,
0159     /**
0160      * RFC4518 LDAP
0161      * @stable ICU 4.2
0162      */
0163     USPREP_RFC4518_LDAP,
0164     /**
0165      * RFC4518 LDAP for case ignore, numeric and stored prefix
0166      * matching rules
0167      * @stable ICU 4.2
0168      */
0169     USPREP_RFC4518_LDAP_CI
0170 } UStringPrepProfileType;
0171
0172 /**
0173  * Creates a StringPrep profile from the data file.
0174  *
0175  * @param path      string containing the full path pointing to the directory
0176  *                  where the profile reside followed by the package name
0177  *                  e.g. "/usr/resource/my_app/profiles/mydata" on a Unix system.
0178  *                  if NULL, ICU default data files will be used.
0179  * @param fileName  name of the profile file to be opened
0180  * @param status    ICU error code in/out parameter. Must not be NULL.
0181  *                  Must fulfill U_SUCCESS before the function call.
0182  * @return Pointer to UStringPrepProfile that is opened. Should be closed by
0183  * calling usprep_close()
0184  * @see usprep_close()
0185  * @stable ICU 2.8
0186  */
0187 U_CAPI UStringPrepProfile* U_EXPORT2
0188 usprep_open(const char* path,
0189             const char* fileName,
0190             UErrorCode* status);
0191
0192 /**
0193  * Creates a StringPrep profile for the specified profile type.
0194  *
0195  * @param type      The profile type
0196  * @param status    ICU error code in/out parameter. Must not be NULL.
0197  *                  Must fulfill U_SUCCESS before the function call.
0198  * @return          Pointer to UStringPrepProfile that is opened. Should be closed by
0199  *                  calling usprep_close()
0200  * @see usprep_close()
0201  * @stable ICU 4.2
0202  */
0203 U_CAPI UStringPrepProfile* U_EXPORT2
0204 usprep_openByType(UStringPrepProfileType type,
0205                   UErrorCode* status);
0206
0207 /**
0208  * Closes the profile
0209  * @param profile The profile to close
0210  * @stable ICU 2.8
0211  */
0212 U_CAPI void U_EXPORT2
0213 usprep_close(UStringPrepProfile* profile);
0214
0215 #if U_SHOW_CPLUSPLUS_API
0216
0217 U_NAMESPACE_BEGIN
0218
0219 /**
0220  * \class LocalUStringPrepProfilePointer
0221  * "Smart pointer" class, closes a UStringPrepProfile via usprep_close().
0222  * For most methods see the LocalPointerBase base class.
0223  *
0224  * @see LocalPointerBase
0225  * @see LocalPointer
0226  * @stable ICU 4.4
0227  */
0228 U_DEFINE_LOCAL_OPEN_POINTER(LocalUStringPrepProfilePointer, UStringPrepProfile, usprep_close);
0229
0230 U_NAMESPACE_END
0231
0232 #endif
0233
0234 /**
0235  * Prepare the input buffer for use in applications with the given profile. This operation maps, normalizes(NFKC),
0236  * checks for prohibited and BiDi characters in the order defined by RFC 3454
0237  * depending on the options specified in the profile.
0238  *
0239  * @param prep          The profile to use
0240  * @param src           Pointer to UChar buffer containing the string to prepare
0241  * @param srcLength     Number of characters in the source string
0242  * @param dest          Pointer to the destination buffer to receive the output
0243  * @param destCapacity  The capacity of destination array
0244  * @param options       A bit set of options:
0245  *
0246  *  - USPREP_DEFAULT            Prohibit processing of unassigned code points in the input
0247  *
0248  *  - USPREP_ALLOW_UNASSIGNED   Treat the unassigned code points are in the input
0249  *                              as normal Unicode code points.
0250  *
0251  * @param parseError        Pointer to UParseError struct to receive information on position
0252  *                          of error if an error is encountered. Can be NULL.
0253  * @param status            ICU in/out error code parameter.
0254  *                          U_INVALID_CHAR_FOUND if src contains
0255  *                          unmatched single surrogates.
0256  *                          U_INDEX_OUTOFBOUNDS_ERROR if src contains
0257  *                          too many code points.
0258  *                          U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough
0259  * @return The number of UChars in the destination buffer
0260  * @stable ICU 2.8
0261  */
0262
0263 U_CAPI int32_t U_EXPORT2
0264 usprep_prepare(   const UStringPrepProfile* prep,
0265                   const UChar* src, int32_t srcLength,
0266                   UChar* dest, int32_t destCapacity,
0267                   int32_t options,
0268                   UParseError* parseError,
0269                   UErrorCode* status );
0270
0271
0272 #endif /* #if !UCONFIG_NO_IDNA */
0273
0274 #endif