usprep.h File Reference

C API: Implements the StringPrep algorithm. More...

`#include "unicode/utypes.h"`
`#include "unicode/localpointer.h"`
`#include "unicode/parseerr.h"`

Go to the source code of this file.

## Namespaces

| icu
| File coll.h.

## Macros

#define | USPREP_DEFAULT 0x0000
| Option to prohibit processing of unassigned code points in the input. More...
#define | USPREP_ALLOW_UNASSIGNED 0x0001
| Option to allow processing of unassigned code points in the input. More...

## Typedefs

typedef struct UStringPrepProfile | UStringPrepProfile
| StringPrep API implements the StingPrep framework as described by RFC 3454. More...
typedef enum UStringPrepProfileType | UStringPrepProfileType
| enums for the standard stringprep profile types supported by usprep_openByType. More...

## Enumerations

enum

UStringPrepProfileType {
USPREP_RFC3491_NAMEPREP , USPREP_RFC3530_NFS4_CS_PREP , USPREP_RFC3530_NFS4_CS_PREP_CI , USPREP_RFC3530_NFS4_CIS_PREP ,
USPREP_RFC3530_NFS4_MIXED_PREP_PREFIX , USPREP_RFC3530_NFS4_MIXED_PREP_SUFFIX , USPREP_RFC3722_ISCSI , USPREP_RFC3920_NODEPREP ,
USPREP_RFC3920_RESOURCEPREP , USPREP_RFC4011_MIB , USPREP_RFC4013_SASLPREP , USPREP_RFC4505_TRACE ,
USPREP_RFC4518_LDAP , USPREP_RFC4518_LDAP_CI
}

| enums for the standard stringprep profile types supported by usprep_openByType. More...

## Functions

U_CAPI UStringPrepProfile * | usprep_open (const char *path, const char *fileName, UErrorCode *status)
| Creates a StringPrep profile from the data file. More...
U_CAPI UStringPrepProfile * | usprep_openByType (UStringPrepProfileType type, UErrorCode *status)
| Creates a StringPrep profile for the specified profile type. More...
U_CAPI void | usprep_close (UStringPrepProfile *profile)
| Closes the profile. More...
U_CAPI int32_t | usprep_prepare (const UStringPrepProfile *prep, const UChar *src, int32_t srcLength, UChar *dest, int32_t destCapacity, int32_t options, UParseError *parseError, UErrorCode *status)
| Prepare the input buffer for use in applications with the given profile. More...

## Detailed Description

C API: Implements the StringPrep algorithm.

Definition in file usprep.h.

## Macro Definition Documentation

## USPREP_ALLOW_UNASSIGNED

#define USPREP_ALLOW_UNASSIGNED 0x0001

Option to allow processing of unassigned code points in the input.

See also
  usprep_prepare

Stable:
  ICU 2.8

Definition at line 90 of file usprep.h.

## USPREP_DEFAULT

#define USPREP_DEFAULT 0x0000

Option to prohibit processing of unassigned code points in the input.

See also
  usprep_prepare

Stable:
  ICU 2.8

Definition at line 82 of file usprep.h.

## Typedef Documentation

## UStringPrepProfile

typedef struct UStringPrepProfile UStringPrepProfile

StringPrep API implements the StingPrep framework as described by RFC 3454.

StringPrep prepares Unicode strings for use in network protocols. Profiles of StingPrep are set of rules and data according to with the Unicode Strings are prepared. Each profiles contains tables which describe how a code point should be treated. The tables are broadly classified into

- Unassigned Table: Contains code points that are unassigned in the Unicode Version supported by StringPrep. Currently RFC 3454 supports Unicode 3.2.
- Prohibited Table: Contains code points that are prohibited from the output of the StringPrep processing function.
- Mapping Table: Contains code points that are deleted from the output or case mapped.

The procedure for preparing Unicode strings:

1. Map: For each character in the input, check if it has a mapping and, if so, replace it with its mapping.
2. Normalize: Possibly normalize the result of step 1 using Unicode normalization.
3. Prohibit: Check for any characters that are not allowed in the output. If any are found, return an error.
4. Check bidi: Possibly check for right-to-left characters, and if any are found, make sure that the whole string satisfies the requirements for bidirectional strings. If the string does not satisfy the requirements for bidirectional strings, return an error.

Author
  Ram Viswanadha The StringPrep profile

Stable:
  ICU 2.8

Definition at line 1 of file usprep.h.

## UStringPrepProfileType

typedef enum UStringPrepProfileType UStringPrepProfileType

enums for the standard stringprep profile types supported by usprep_openByType.

See also
  usprep_openByType

Stable:
  ICU 4.2

## Enumeration Type Documentation

## UStringPrepProfileType

enum UStringPrepProfileType

enums for the standard stringprep profile types supported by usprep_openByType.

See also
  usprep_openByType

Stable:
  ICU 4.2

Enumerator

USPREP_RFC3491_NAMEPREP

RFC3491 Nameprep.

Stable:
  ICU 4.2

USPREP_RFC3530_NFS4_CS_PREP

RFC3530 nfs4_cs_prep.

Stable:
  ICU 4.2

USPREP_RFC3530_NFS4_CS_PREP_CI

RFC3530 nfs4_cs_prep with case insensitive option.

Stable:
  ICU 4.2

USPREP_RFC3530_NFS4_CIS_PREP

RFC3530 nfs4_cis_prep.

Stable:
  ICU 4.2

USPREP_RFC3530_NFS4_MIXED_PREP_PREFIX

RFC3530 nfs4_mixed_prep for prefix.

Stable:
  ICU 4.2

USPREP_RFC3530_NFS4_MIXED_PREP_SUFFIX

RFC3530 nfs4_mixed_prep for suffix.

Stable:
  ICU 4.2

USPREP_RFC3722_ISCSI

RFC3722 iSCSI.

Stable:
  ICU 4.2

USPREP_RFC3920_NODEPREP

RFC3920 XMPP Nodeprep.

Stable:
  ICU 4.2

USPREP_RFC3920_RESOURCEPREP

RFC3920 XMPP Resourceprep.

Stable:
  ICU 4.2

USPREP_RFC4011_MIB

RFC4011 Policy MIB Stringprep.

Stable:
  ICU 4.2

USPREP_RFC4013_SASLPREP

RFC4013 SASLprep.

Stable:
  ICU 4.2

USPREP_RFC4505_TRACE

RFC4505 trace.

Stable:
  ICU 4.2

USPREP_RFC4518_LDAP

RFC4518 LDAP.

Stable:
  ICU 4.2

USPREP_RFC4518_LDAP_CI

RFC4518 LDAP for case ignore, numeric and stored prefix matching rules.

Stable:
  ICU 4.2

Definition at line 98 of file usprep.h.

## Function Documentation

## usprep_close()

U_CAPI void usprep_close | ( | UStringPrepProfile * | profile | ) |

Closes the profile.

Parameters

  profile | The profile to close

Stable:
  ICU 2.8

## usprep_open()

U_CAPI UStringPrepProfile* usprep_open | ( | const char * | path,
|  | const char * | fileName,
|  | UErrorCode * | status
| ) |  |

Creates a StringPrep profile from the data file.

Parameters

  path | string containing the full path pointing to the directory where the profile reside followed by the package name e.g. "/usr/resource/my_app/profiles/mydata" on a Unix system. if NULL, ICU default data files will be used.
  fileName | name of the profile file to be opened
  status | ICU error code in/out parameter. Must not be NULL. Must fulfill U_SUCCESS before the function call.

Returns
  Pointer to UStringPrepProfile that is opened. Should be closed by calling usprep_close()

See also
  usprep_close()

Stable:
  ICU 2.8

## usprep_openByType()

U_CAPI UStringPrepProfile* usprep_openByType | ( | UStringPrepProfileType | type,
|  | UErrorCode * | status
| ) |  |

Creates a StringPrep profile for the specified profile type.

Parameters

  type | The profile type
  status | ICU error code in/out parameter. Must not be NULL. Must fulfill U_SUCCESS before the function call.

Returns
  Pointer to UStringPrepProfile that is opened. Should be closed by calling usprep_close()

See also
  usprep_close()

Stable:
  ICU 4.2

## usprep_prepare()

U_CAPI int32_t usprep_prepare | ( | const UStringPrepProfile * | prep,
|  | const UChar * | src,
|  | int32_t | srcLength,
|  | UChar * | dest,
|  | int32_t | destCapacity,
|  | int32_t | options,
|  | UParseError * | parseError,
|  | UErrorCode * | status
| ) |  |

Prepare the input buffer for use in applications with the given profile.

This operation maps, normalizes(NFKC), checks for prohibited and BiDi characters in the order defined by RFC 3454 depending on the options specified in the profile.

Parameters

  prep | The profile to use
  src | Pointer to UChar buffer containing the string to prepare
  srcLength | Number of characters in the source string
  dest | Pointer to the destination buffer to receive the output
  destCapacity | The capacity of destination array
  options | A bit set of options:

- USPREP_DEFAULT Prohibit processing of unassigned code points in the input
- USPREP_ALLOW_UNASSIGNED Treat the unassigned code points are in the input as normal Unicode code points.

Parameters

  parseError | Pointer to UParseError struct to receive information on position of error if an error is encountered. Can be NULL.
  status | ICU in/out error code parameter. U_INVALID_CHAR_FOUND if src contains unmatched single surrogates. U_INDEX_OUTOFBOUNDS_ERROR if src contains too many code points. U_BUFFER_OVERFLOW_ERROR if destCapacity is not enough

Returns
  The number of UChars in the destination buffer

Stable:
  ICU 2.8