libidn: Stringprep Functions
1
1 4 Stringprep Functions
1 **********************
1
1 Stringprep describes a framework for preparing Unicode text strings in
1 order to increase the likelihood that string input and string comparison
1 work in ways that make sense for typical users throughout the world.
1 The stringprep protocol is useful for protocol identifier values,
1 company and personal names, internationalized domain names, and other
1 text strings.
1
1 4.1 Header file ‘stringprep.h’
1 ==============================
1
1 To use the functions explained in this chapter, you need to include the
1 file ‘stringprep.h’ using:
1
1 #include <stringprep.h>
1
1 4.2 Defining A Stringprep Profile
1 =================================
1
1 Further types and structures are defined for applications that want to
1 specify their own stringprep profile. As these are fairly obscure, and
1 by necessity tied to the implementation, we do not document them here.
1 Look into the ‘stringprep.h’ header file, and the ‘profiles.c’ source
1 code for the details.
1
1 4.3 Control Flags
1 =================
1
1 -- Stringprep flags: Stringprep_profile_flags STRINGPREP_NO_NFKC
1 Disable the NFKC normalization, as well as selecting the non-NFKC
1 case folding tables. Usually the profile specifies BIDI and NFKC
1 settings, and applications should not override it unless in special
1 situations.
1
1 -- Stringprep flags: Stringprep_profile_flags STRINGPREP_NO_BIDI
1 Disable the BIDI step. Usually the profile specifies BIDI and NFKC
1 settings, and applications should not override it unless in special
1 situations.
1
1 -- Stringprep flags: Stringprep_profile_flags STRINGPREP_NO_UNASSIGNED
1 Make the library return with an error if string contains unassigned
1 characters according to profile.
1
1 4.4 Core Functions
1 ==================
1
1 stringprep_4i
1 -------------
1
1 -- Function: int stringprep_4i (uint32_t * UCS4, size_t * LEN, size_t
1 MAXUCS4LEN, Stringprep_profile_flags FLAGS, const
1 Stringprep_profile * PROFILE)
1 UCS4: input/output array with string to prepare.
1
1 LEN: on input, length of input array with Unicode code points, on
1 exit, length of output array with Unicode code points.
1
1 MAXUCS4LEN: maximum length of input/output array.
1
1 FLAGS: a ‘Stringprep_profile_flags’ value, or 0.
1
1 PROFILE: pointer to ‘Stringprep_profile’ to use.
1
1 Prepare the input UCS-4 string according to the stringprep profile,
1 and write back the result to the input string.
1
1 The input is not required to be zero terminated ( ‘ucs4’ [ ‘len’ ]
1 = 0). The output will not be zero terminated unless ‘ucs4’ [ ‘len’
1 ] = 0. Instead, see ‘stringprep_4zi()’ if your input is zero
1 terminated or if you want the output to be.
1
1 Since the stringprep operation can expand the string, ‘maxucs4len’
1 indicate how large the buffer holding the string is. This function
1 will not read or write to code points outside that size.
1
1 The ‘flags’ are one of ‘Stringprep_profile_flags’ values, or 0.
1
1 The ‘profile’ contain the ‘Stringprep_profile’ instructions to
1 perform. Your application can define new profiles, possibly
1 re-using the generic stringprep tables that always will be part of
1 the library, or use one of the currently supported profiles.
1
1 Return value: Returns ‘STRINGPREP_OK’ iff successful, or an
1 ‘Stringprep_rc’ error code.
1
1 stringprep_4zi
1 --------------
1
1 -- Function: int stringprep_4zi (uint32_t * UCS4, size_t MAXUCS4LEN,
1 Stringprep_profile_flags FLAGS, const Stringprep_profile *
1 PROFILE)
1 UCS4: input/output array with zero terminated string to prepare.
1
1 MAXUCS4LEN: maximum length of input/output array.
1
1 FLAGS: a ‘Stringprep_profile_flags’ value, or 0.
1
1 PROFILE: pointer to ‘Stringprep_profile’ to use.
1
1 Prepare the input zero terminated UCS-4 string according to the
1 stringprep profile, and write back the result to the input string.
1
1 Since the stringprep operation can expand the string, ‘maxucs4len’
1 indicate how large the buffer holding the string is. This function
1 will not read or write to code points outside that size.
1
1 The ‘flags’ are one of ‘Stringprep_profile_flags’ values, or 0.
1
1 The ‘profile’ contain the ‘Stringprep_profile’ instructions to
1 perform. Your application can define new profiles, possibly
1 re-using the generic stringprep tables that always will be part of
1 the library, or use one of the currently supported profiles.
1
1 Return value: Returns ‘STRINGPREP_OK’ iff successful, or an
1 ‘Stringprep_rc’ error code.
1
1 stringprep
1 ----------
1
1 -- Function: int stringprep (char * IN, size_t MAXLEN,
1 Stringprep_profile_flags FLAGS, const Stringprep_profile *
1 PROFILE)
1 IN: input/ouput array with string to prepare.
1
1 MAXLEN: maximum length of input/output array.
1
1 FLAGS: a ‘Stringprep_profile_flags’ value, or 0.
1
1 PROFILE: pointer to ‘Stringprep_profile’ to use.
1
1 Prepare the input zero terminated UTF-8 string according to the
1 stringprep profile, and write back the result to the input string.
1
1 Note that you must convert strings entered in the systems locale
1 into UTF-8 before using this function, see
1 ‘stringprep_locale_to_utf8()’ .
1
1 Since the stringprep operation can expand the string, ‘maxlen’
1 indicate how large the buffer holding the string is. This function
1 will not read or write to characters outside that size.
1
1 The ‘flags’ are one of ‘Stringprep_profile_flags’ values, or 0.
1
1 The ‘profile’ contain the ‘Stringprep_profile’ instructions to
1 perform. Your application can define new profiles, possibly
1 re-using the generic stringprep tables that always will be part of
1 the library, or use one of the currently supported profiles.
1
1 Return value: Returns ‘STRINGPREP_OK’ iff successful, or an error
1 code.
1
1 stringprep_profile
1 ------------------
1
1 -- Function: int stringprep_profile (const char * IN, char ** OUT,
1 const char * PROFILE, Stringprep_profile_flags FLAGS)
1 IN: input array with UTF-8 string to prepare.
1
1 OUT: output variable with pointer to newly allocate string.
1
1 PROFILE: name of stringprep profile to use.
1
1 FLAGS: a ‘Stringprep_profile_flags’ value, or 0.
1
1 Prepare the input zero terminated UTF-8 string according to the
1 stringprep profile, and return the result in a newly allocated
1 variable.
1
1 Note that you must convert strings entered in the systems locale
1 into UTF-8 before using this function, see
1 ‘stringprep_locale_to_utf8()’ .
1
1 The output ‘out’ variable must be deallocated by the caller.
1
1 The ‘flags’ are one of ‘Stringprep_profile_flags’ values, or 0.
1
1 The ‘profile’ specifies the name of the stringprep profile to use.
1 It must be one of the internally supported stringprep profiles.
1
1 Return value: Returns ‘STRINGPREP_OK’ iff successful, or an error
1 code.
1
1 4.5 Error Handling
1 ==================
1
1 stringprep_strerror
1 -------------------
1
1 -- Function: const char * stringprep_strerror (Stringprep_rc RC)
1 RC: a ‘Stringprep_rc’ return code.
1
1 Convert a return code integer to a text string. This string can be
1 used to output a diagnostic message to the user.
1
1 *STRINGPREP_OK:* Successful operation. This value is guaranteed to
1 always be zero, the remaining ones are only guaranteed to hold
1 non-zero values, for logical comparison purposes.
1
1 *STRINGPREP_CONTAINS_UNASSIGNED:* String contain unassigned Unicode
1 code points, which is forbidden by the profile.
1
1 *STRINGPREP_CONTAINS_PROHIBITED:* String contain code points
1 prohibited by the profile.
1
1 *STRINGPREP_BIDI_BOTH_L_AND_RAL:* String contain code points with
1 conflicting bidirection category.
1
1 *STRINGPREP_BIDI_LEADTRAIL_NOT_RAL:* Leading and trailing character
1 in string not of proper bidirectional category.
1
1 *STRINGPREP_BIDI_CONTAINS_PROHIBITED:* Contains prohibited code
1 points detected by bidirectional code.
1
1 *STRINGPREP_TOO_SMALL_BUFFER:* Buffer handed to function was too
1 small. This usually indicate a problem in the calling application.
1
1 *STRINGPREP_PROFILE_ERROR:* The stringprep profile was
1 inconsistent. This usually indicate an internal error in the
1 library.
1
1 *STRINGPREP_FLAG_ERROR:* The supplied flag conflicted with profile.
1 This usually indicate a problem in the calling application.
1
1 *STRINGPREP_UNKNOWN_PROFILE:* The supplied profile name was not
1 known to the library.
1
1 *STRINGPREP_ICONV_ERROR:* Could not convert string in locale
1 encoding.
1
1 *STRINGPREP_NFKC_FAILED:* The Unicode NFKC operation failed. This
1 usually indicate an internal error in the library.
1
1 *STRINGPREP_MALLOC_ERROR:* The ‘malloc()’ was out of memory. This
1 is usually a fatal error.
1
1 Return value: Returns a pointer to a statically allocated string
1 containing a description of the error with the return code ‘rc’ .
1
1 4.6 Stringprep Profile Macros
1 =============================
1
1 -- Function: int stringprep_nameprep_no_unassigned (char * IN, int
1 MAXLEN)
1
1 IN: input/ouput array with string to prepare.
1
1 MAXLEN: maximum length of input/output array.
1
1 Prepare the input UTF-8 string according to the nameprep profile.
1 The AllowUnassigned flag is false, use ‘stringprep_nameprep’ for
1 true AllowUnassigned. Returns 0 iff successful, or an error code.
1
1 -- Function: int stringprep_iscsi (char * IN, int MAXLEN)
1
1 IN: input/ouput array with string to prepare.
1
1 MAXLEN: maximum length of input/output array.
1
1 Prepare the input UTF-8 string according to the draft iSCSI
1 stringprep profile. Returns 0 iff successful, or an error code.
1
1 -- Function: int stringprep_plain (char * IN, int MAXLEN)
1
1 IN: input/ouput array with string to prepare.
1
1 MAXLEN: maximum length of input/output array.
1
1 Prepare the input UTF-8 string according to the draft SASL
1 ANONYMOUS profile. Returns 0 iff successful, or an error code.
1
1 -- Function: int stringprep_xmpp_nodeprep (char * IN, int MAXLEN)
1
1 IN: input/ouput array with string to prepare.
1
1 MAXLEN: maximum length of input/output array.
1
1 Prepare the input UTF-8 string according to the draft XMPP node
1 identifier profile. Returns 0 iff successful, or an error code.
1
1 -- Function: int stringprep_xmpp_resourceprep (char * IN, int MAXLEN)
1
1 IN: input/ouput array with string to prepare.
1
1 MAXLEN: maximum length of input/output array.
1
1 Prepare the input UTF-8 string according to the draft XMPP resource
1 identifier profile. Returns 0 iff successful, or an error code.
1