lib/silcutil/silcstrutil.h

   1 /*
   2
   3   silcstrutil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2002 - 2007 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 String Utilities
  21  *
  22  * DESCRIPTION
  23  *
  24  * String manipulation utility routines.  These routines provides
  25  * various helper functions for encoding, decoding and otherwise
  26  * managing strings.
  27  *
  28  ***/
  29
  30 #ifndef SILCSTRUTIL_H
  31 #define SILCSTRUTIL_H
  32
  33 /****d* silcutil/SilcStrUtilAPI/SilcStringEncoding
  34  *
  35  * NAME
  36  *
  37  *    typedef enum { ... } SilcStringEncoding;
  38  *
  39  * DESCRIPTION
  40  *
  41  *    String encoding definitions used with various string manipulation
  42  *    routines.  By default, applications are suggested to use
  43  *    SILC_STRING_LOCALE since it encodes and decodes correctly according
  44  *    to local system language and character set (locale).
  45  *
  46  * SOURCE
  47  */
  48 typedef enum {
  49   SILC_STRING_ASCII         = 0,  /* Any 8 bit ASCII encoding (default) */
  50   SILC_STRING_ASCII_ESC     = 1,  /* 7 bit ASCII (>0x7f escaped) */
  51   SILC_STRING_BMP           = 2,  /* 16 bit, UCS-2, BMP, ISO/IEC 10646 */
  52   SILC_STRING_BMP_LSB       = 3,  /* BMP, least significant byte first */
  53   SILC_STRING_UNIVERSAL     = 4,  /* 32 bit, UCS-4, Universal, ISO/IEC 10646 */
  54   SILC_STRING_UNIVERSAL_LSB = 5,  /* Universal, least significant byte first */
  55   SILC_STRING_LOCALE        = 6,  /* A locale specific conversion on
  56                                      those platforms that support iconv().
  57                                      Fallback is SILC_STRING_ASCII. */
  58   SILC_STRING_UTF8          = 7,  /* UTF-8 encoding */
  59   SILC_STRING_PRINTABLE     = 8,  /* Printable ASCII (no escaping) */
  60   SILC_STRING_VISIBLE       = 9,  /* Visible ASCII string */
  61   SILC_STRING_TELETEX       = 10, /* Teletex ASCII string */
  62   SILC_STRING_NUMERICAL     = 11, /* Numerical ASCII string (digits) */
  63   SILC_STRING_LDAP_DN       = 12, /* Strings for LDAP DNs, RFC 2253 */
  64   SILC_STRING_UTF8_ESCAPE   = 12, /* Escaped UTF-8 as defined in RFC 2253 */
  65
  66   SILC_STRING_LANGUAGE      = 6,  /* _Deprecated_, use SILC_STRING_LOCALE. */
  67 } SilcStringEncoding;
  68 /***/
  69
  70 /****f* silcutil/SilcStrUtilAPI/silc_base64_encode
  71  *
  72  * SYNOPSIS
  73  *
  74  *    char *silc_base64_encode(unsigned char *data, SilcUInt32 len);
  75  *
  76  * DESCRIPTION
  77  *
  78  *    Encodes data into Base 64 (PEM) encoding. Returns NULL terminated
  79  *    Base 64 encoded data string.
  80  *
  81  ***/
  82 char *silc_base64_encode(unsigned char *data, SilcUInt32 len);
  83
  84 /****f* silcutil/SilcStrUtilAPI/silc_base64_encode_file
  85  *
  86  * SYNOPSIS
  87  *
  88  *    char *silc_base64_encode_file(unsigned char *data, SilcUInt32 data_len);
  89  *
  90  * DESCRIPTION
  91  *
  92  *    Same as silc_base64_encode() but puts newline ('\n') every 72
  93  *    characters.
  94  *
  95  ***/
  96 char *silc_base64_encode_file(unsigned char *data, SilcUInt32 data_len);
  97
  98 /****f* silcutil/SilcStrUtilAPI/silc_base_decode
  99  *
 100  * SYNOPSIS
 101  *
 102  *    unsigned char *silc_base_decode(unsigned char *base64,
 103  *                                    SilcUInt32 base64_len,
 104  *                                    SilcUInt32 *ret_len);
 105  *
 106  * DESCRIPTION
 107  *
 108  *    Decodes Base 64 (PEM) into data. Returns the decoded data.
 109  *
 110  ***/
 111 unsigned char *silc_base64_decode(unsigned char *base64,
 112                                   SilcUInt32 base64_len,
 113                                   SilcUInt32 *ret_len);
 114
 115 /****f* silcutil/SilcStrStrUtilAPI/silc_strncat
 116  *
 117  * SYNOPSIS
 118  *
 119  *    char *silc_strncat(char *dest, SilcUInt32 dest_size,
 120  *                       const char *src, SilcUInt32 src_len);
 121  *
 122  * DESCRIPTION
 123  *
 124  *    Concatenates the `src' into `dest'.  If `src_len' is more than the
 125  *    size of the `dest' (minus NULL at the end) the `src' will be
 126  *    truncated to fit.
 127  *
 128  ***/
 129 char *silc_strncat(char *dest, SilcUInt32 dest_size,
 130                    const char *src, SilcUInt32 src_len);
 131
 132 /****f* silcutil/SilcStrUtilAPI/silc_string_regexify
 133  *
 134  * SYNOPSIS
 135  *
 136  *    char *silc_string_regexify(const char *string);
 137  *
 138  * DESCRIPTION
 139  *
 140  *    Inspects the `string' for wildcards and returns regex string that can
 141  *    be used by the GNU regex library. A comma (`,') in the `string' means
 142  *    that the string is list.
 143  *
 144  *    This function is system dependant.
 145  *
 146  ***/
 147 char *silc_string_regexify(const char *string);
 148
 149 /****f* silcutil/SilcStrUtilAPI/silc_string_regex_match
 150  *
 151  * SYNOPSIS
 152  *
 153  *    int silc_string_regex_match(const char *regex, const char *string);
 154  *
 155  * DESCRIPTION
 156  *
 157  *    Matches the two strings and returns TRUE if the strings match.
 158  *
 159  *    This function is system dependant.
 160  *
 161  ***/
 162 int silc_string_regex_match(const char *regex, const char *string);
 163
 164 /****f* silcutil/SilcStrUtilAPI/silc_string_match
 165  *
 166  * SYNOPSIS
 167  *
 168  *    int silc_string_match(const char *string1, const char *string2);
 169  *
 170  * DESCRIPTION
 171  *
 172  *    Do regex match to the two strings `string1' and `string2'. If the
 173  *    `string2' matches the `string1' this returns TRUE.
 174  *
 175  *    This function is system dependant.
 176  *
 177  ***/
 178 int silc_string_match(const char *string1, const char *string2);
 179
 180 /****f* silcutil/SilcStrUtilAPI/silc_string_compare
 181  *
 182  * SYNOPSIS
 183  *
 184  *    int silc_string_compare(char *string1, char *string2);
 185  *
 186  * DESCRIPTION
 187  *
 188  *    Compares two strings. Strings may include wildcards '*' and '?'.
 189  *    Returns TRUE if strings match.
 190  *
 191  ***/
 192 int silc_string_compare(char *string1, char *string2);
 193
 194 /****f* silcutil/SilcStrUtilAPI/silc_string_split
 195  *
 196  * SYNOPSIS
 197  *
 198  *    char **silc_string_split(const char *string, char ch, int *ret_count);
 199  *
 200  * DESCRIPTION
 201  *
 202  *    Splits a `string' that has a separator `ch' into an array of strings
 203  *    and returns the array.  The `ret_count' will contain the number of
 204  *    strings in the array.  Caller must free the strings and the array.
 205  *    Returns NULL on error.  If the string does not have `ch' separator
 206  *    this returns the `string' in the array.
 207  *
 208  ***/
 209 char **silc_string_split(const char *string, char ch, int *ret_count);
 210
 211 #endif /* SILCSTRUTIL_H */