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