lib/silcutil/silcstringprep.h

   1 /*
   2
   3   silcstringprep.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2004 - 2005 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC Stringprep
  21  *
  22  * DESCRIPTION
  23  *
  24  * Interface for the stringprep (RFC3454) standard, that is used to prepare
  25  * strings for internationalization.  The interface can be used to prepare
  26  * strings according to various stringprep profiles.  The profiles defines
  27  * what characters the strings may contain, what characters are prohibited
  28  * and how the strings are prepared.
  29  *
  30  ***/
  31
  32 #ifndef SILCSTRINGPREP_H
  33 #define SILCSTRINGPREP_H
  34
  35 /****d* silcutil/SilcStringprep/SilcStringprepStatus
  36  *
  37  * NAME
  38  *
  39  *    typedef enum { ... } SilcStringprepStatus;
  40  *
  41  * DESCRIPTION
  42  *
  43  *    Status and errors returned by silc_stringprep.
  44  *
  45  * SOURCE
  46  */
  47 typedef enum {
  48   SILC_STRINGPREP_OK,                     /* Preparation success */
  49   SILC_STRINGPREP_ERR_UNASSIGNED,         /* Contains unassigned characters */
  50   SILC_STRINGPREP_ERR_PROHIBITED,         /* Contains prohibited characters */
  51   SILC_STRINGPREP_ERR_BIDI_PROHIBITED,    /* BIDI contains prohibited chars */
  52   SILC_STRINGPREP_ERR_BIDI_RAL_WITH_L,    /* BIDI has both R/AL and L */
  53   SILC_STRINGPREP_ERR_BIDI_RAL,           /* BIDI has R/AL but not as leading
  54                                              and/or trailing character. */
  55   SILC_STRINGPREP_ERR_OUT_OF_MEMORY,      /* System out of memory */
  56   SILC_STRINGPREP_ERR_ENCODING,           /* Character encoding error */
  57   SILC_STRINGPREP_ERR_UNSUP_ENCODING,     /* Unsupported character encoding  */
  58   SILC_STRINGPREP_ERR_UNSUP_PROFILE,      /* Unsupported profile */
  59   SILC_STRINGPREP_ERR,                    /* Unknown error */
  60 } SilcStringprepStatus;
  61 /***/
  62
  63 /****d* silcutil/SilcStringprep/SilcStringprepFlags
  64  *
  65  * NAME
  66  *
  67  *    typedef enum { ... } SilcStringprepFlags;
  68  *
  69  * DESCRIPTION
  70  *
  71  *    Flags that change how the strings are prepared with silc_stringprep.
  72  *
  73  * SOURCE
  74  */
  75 typedef enum {
  76   SILC_STRINGPREP_NONE               = 0x00,  /* No flags */
  77   SILC_STRINGPREP_ALLOW_UNASSIGNED   = 0x01,  /* Allow unassigned characters
  78                                                  without returning error. */
  79 } SilcStringprepFlags;
  80 /***/
  81
  82 /* Profiles */
  83 #define SILC_IDENTIFIER_PREP "silc-identifier-prep"
  84 #define SILC_IDENTIFIERC_PREP "silc-identifierc-prep"
  85 #define SILC_IDENTIFIER_CH_PREP "silc-identifier-ch-prep"
  86 #define SILC_CASEFOLD_PREP "silc-casefold-prep"
  87
  88 /****f* silcutil/SilcStringprep/silc_stringprep
  89  *
  90  * SYNOPSIS
  91  *
  92  *    SilcStringprepStatus
  93  *    silc_stringprep(const unsigned char *bin, SilcUInt32 bin_len,
  94  *                    SilcStringEncoding bin_encoding,
  95  *                    const char *profile_name,
  96  *                    SilcStringprepFlags flags,
  97  *                    unsigned char **out, SilcUInt32 *out_len,
  98  *                    SilcStringEncoding out_encoding);
  99  *
 100  * DESCRIPTION
 101  *
 102  *    Prepares the input string 'bin' of length 'bin_len' of encoding
 103  *    'bin_encoding' according to the stringrep profile 'profile_name'.
 104  *    Returns the prepared and allocated string into 'out'.  The 'out_len'
 105  *    indicates the length of the prepared string.  This returns the
 106  *    SilcStringprepStatus which indicates the status of the preparation.
 107  *    For example, if the input string contains prohibited characters
 108  *    (according to the used profile) this function will return error.
 109  *    The 'flags' however can be used to modify the behavior of this
 110  *    function.  Caller must free the returned 'out' string.
 111  *
 112  *    The output string will be encoded into the character encoding
 113  *    defined by the 'out_encoding'.  This allows caller to have for
 114  *    example the input string as locale specific string and output string
 115  *    as UTF-8 encoded string.
 116  *
 117  *    If the 'out' is NULL this function merely performs the preparation
 118  *    process, but does not return anything.  In this case this function
 119  *    could be used to for example verify that an input string that ought
 120  *    to have been prepared correctly was done so.
 121  *
 122  *    Available profile names:
 123  *
 124  *      SILC_IDENTIFIER_PREP            Prepares SILC identifier strings
 125  *      SILC_IDENTIFIER_CH_PREP         Prepares SILC channel name strings
 126  *      SILC_IDENTIFIERC_PREP           Casefolds identifier strings
 127  *      SILC_CASEFOLD_PREP              Casefolding and normalizing
 128  *
 129  ***/
 130 SilcStringprepStatus
 131 silc_stringprep(const unsigned char *bin, SilcUInt32 bin_len,
 132                 SilcStringEncoding bin_encoding,
 133                 const char *profile_name,
 134                 SilcStringprepFlags flags,
 135                 unsigned char **out, SilcUInt32 *out_len,
 136                 SilcStringEncoding out_encoding);
 137
 138 #endif /* SILCSTRINGPREP_H */