lib/silcutil/silcstrutil.h

   1 /*
   2
   3   silcstrutil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2002 - 2003 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 /****f* silcutil/SilcStrUtilAPI/silc_pem_encode
  34  *
  35  * SYNOPSIS
  36  *
  37  *    char *silc_pem_encode(unsigned char *data, SilcUInt32 len);
  38  *
  39  * DESCRIPTION
  40  *
  41  *    Encodes data into PEM encoding. Returns NULL terminated PEM encoded
  42  *    data string. Note: This is originally public domain code and is
  43  *    still PD.
  44  *
  45  ***/
  46 char *silc_pem_encode(unsigned char *data, SilcUInt32 len);
  47
  48 /****f* silcutil/SilcStrUtilAPI/silc_pem_encode_file
  49  *
  50  * SYNOPSIS
  51  *
  52  *    char *silc_pem_encode_file(unsigned char *data, SilcUInt32 data_len);
  53  *
  54  * DESCRIPTION
  55  *
  56  *    Same as silc_pem_encode() but puts newline ('\n') every 72 characters.
  57  *
  58  ***/
  59 char *silc_pem_encode_file(unsigned char *data, SilcUInt32 data_len);
  60
  61 /****f* silcutil/SilcStrUtilAPI/silc_pem_decode
  62  *
  63  * SYNOPSIS
  64  *
  65  *    unsigned char *silc_pem_decode(unsigned char *pem, SilcUInt32 pem_len,
  66  *                                   SilcUInt32 *ret_len);
  67  *
  68  * DESCRIPTION
  69  *
  70  *    Decodes PEM into data. Returns the decoded data. Note: This is
  71  *    originally public domain code and is still PD.
  72  *
  73  ***/
  74 unsigned char *silc_pem_decode(unsigned char *pem, SilcUInt32 pem_len,
  75                                SilcUInt32 *ret_len);
  76
  77 /****d* silcutil/SilcStrUtilAPI/SilcStringEncoding
  78  *
  79  * NAME
  80  *
  81  *    typedef enum { ... } SilcStringEncoding;
  82  *
  83  * DESCRIPTION
  84  *
  85  *    String encoding definitions used with the UTF-8 encoding and
  86  *    decoding functions.  By default, systems should use SILC_STRING_LANGUAGE
  87  *    since it encodes and decodes correctly according to local system
  88  *    language and character set.
  89  *
  90  * SOURCE
  91  */
  92 typedef enum {
  93   SILC_STRING_ASCII         = 0,  /* Any 8 bit ASCII encoding (default) */
  94   SILC_STRING_ASCII_ESC     = 1,  /* 7 bit ASCII (>0x7f escaped) */
  95   SILC_STRING_BMP           = 2,  /* 16 bit, UCS-2, BMP, ISO/IEC 10646 */
  96   SILC_STRING_BMP_LSB       = 3,  /* BMP, least significant byte first */
  97   SILC_STRING_UNIVERSAL     = 4,  /* 32 bit, UCS-4, Universal, ISO/IEC 10646 */
  98   SILC_STRING_UNIVERSAL_LSB = 5,  /* Universal, least significant byte first */
  99   SILC_STRING_LANGUAGE      = 6,  /* Language and charset specific conversion
 100                                      on those platforms that support iconv().
 101                                      Fallback is SILC_STRING_ASCII. */
 102 } SilcStringEncoding;
 103 /***/
 104
 105 /****f* silcutil/SilcStrUtilAPI/silc_utf8_encode
 106  *
 107  * SYNOPSIS
 108  *
 109  *    SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len,
 110  *                                SilcStringEncoding bin_encoding,
 111  *                                unsigned char *utf8, SilcUInt32 utf8_size);
 112  *
 113  * DESCRIPTION
 114  *
 115  *    Encodes the string `bin' of which encoding is `bin_encoding' to the
 116  *    UTF-8 encoding into the buffer `utf8' which is of size of `utf8_size'.
 117  *    Returns the length of the UTF-8 encoded string, or zero (0) on error.
 118  *    By default `bin_encoding' is ASCII, and the caller needs to know the
 119  *    encoding of the input string if it is anything else.
 120  *
 121  ***/
 122 SilcUInt32 silc_utf8_encode(const unsigned char *bin, SilcUInt32 bin_len,
 123                             SilcStringEncoding bin_encoding,
 124                             unsigned char *utf8, SilcUInt32 utf8_size);
 125
 126 /****f* silcutil/SilcStrUtilAPI/silc_utf8_decode
 127  *
 128  * SYNOPSIS
 129  *
 130  *    SilcUInt32 silc_utf8_decode(const unsigned char *utf8,
 131  *                                SilcUInt32 utf8_len,
 132  *                                SilcStringEncoding bin_encoding,
 133  *                                unsigned char *bin, SilcUInt32 bin_size);
 134  *
 135  * DESCRIPTION
 136  *
 137  *    Decodes UTF-8 encoded string `utf8' to string of which encoding is
 138  *    to be `bin_encoding', into the `bin' buffer of size of `bin_size'.
 139  *    Returns the length of the decoded buffer, or zero (0) on error.
 140  *    By default `bin_encoding' is ASCII, and the caller needs to know to
 141  *    which encoding the output string is to be encoded if ASCII is not
 142  *    desired.
 143  *
 144  ***/
 145 SilcUInt32 silc_utf8_decode(const unsigned char *utf8, SilcUInt32 utf8_len,
 146                             SilcStringEncoding bin_encoding,
 147                             unsigned char *bin, SilcUInt32 bin_size);
 148
 149 /****f* silcutil/SilcStrUtilAPI/silc_utf8_encoded_len
 150  *
 151  * SYNOPSIS
 152  *
 153  *    SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin,
 154  *                                     SilcUInt32 bin_len,
 155  *                                     SilcStringEncoding bin_encoding);
 156  *
 157  * DESCRIPTION
 158  *
 159  *    Returns the length of UTF-8 encoded string if the `bin' of
 160  *    encoding of `bin_encoding' is encoded with silc_utf8_encode.
 161  *
 162  ***/
 163 SilcUInt32 silc_utf8_encoded_len(const unsigned char *bin, SilcUInt32 bin_len,
 164                                  SilcStringEncoding bin_encoding);
 165
 166 /****f* silcutil/SilcStrUtilAPI/silc_utf8_decoded_len
 167  *
 168  * SYNOPSIS
 169  *
 170  *    SilcUInt32 silc_utf8_decoded_len(const unsigned char *bin,
 171  *                                     SilcUInt32 bin_len,
 172  *                                     SilcStringEncoding bin_encoding);
 173  *
 174  * DESCRIPTION
 175  *
 176  *    Returns the length of decoded string if the `bin' of encoding of
 177  *    `bin_encoding' is decoded with silc_utf8_decode.
 178  *
 179  ***/
 180 SilcUInt32 silc_utf8_decoded_len(const unsigned char *bin, SilcUInt32 bin_len,
 181                                  SilcStringEncoding bin_encoding);
 182
 183 /****f* silcutil/SilcStrUtilAPI/silc_utf8_valid
 184  *
 185  * SYNOPSIS
 186  *
 187  *    bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len);
 188  *
 189  * DESCRIPTION
 190  *
 191  *    Returns TRUE if the `utf8' string of length of `utf8_len' is valid
 192  *    UTF-8 encoded string, FALSE if it is not UTF-8 encoded string.
 193  *
 194  ***/
 195 bool silc_utf8_valid(const unsigned char *utf8, SilcUInt32 utf8_len);
 196
 197 /****f* silcutil/SilcStrUtilAPI/silc_mime_parse
 198  *
 199  * SYNOPSIS
 200  *
 201  *    bool
 202  *    silc_mime_parse(const unsigned char *mime, SilcUInt32 mime_len,
 203  *                    char *version, SilcUInt32 version_size,
 204  *                    char *content_type, SilcUInt32 content_type_size,
 205  *                    char *transfer_encoding,
 206  *                    SilcUInt32 transfer_encoding_size,
 207  *                    unsigned char **mime_data_ptr,
 208  *                    SilcUInt32 *mime_data_len);
 209  *
 210  * DESCRIPTION
 211  *
 212  *    Parses MIME header indicated by `mime' data block of length of
 213  *    `mime_len'.  Returns TRUE if the `mime' is valid MIME object.
 214  *    Parses from the MIME header the MIME Version (if present) and
 215  *    copies it to the `version' pointer if provided, content type
 216  *    indicating the data in the MIME object and copies it to the
 217  *    `content_type' if provided, and the tranfer encoding (if present)
 218  *    indicating the encoding of the data and copies it to the
 219  *    `content_transfer_encoding' if provided.
 220  *
 221  *    The pointer to the actual data in the MIME object is saved into
 222  *    `mime_data_ptr'.  The pointer is a location in the `mime' and it
 223  *    does not allocate or copy anything, ie. the `mime_data_ptr' is a
 224  *    pointer to the `mime'.  The `mime_data_len' indicates the length of
 225  *    the data without the MIME header.  The caller is responsible of
 226  *    NULL terminating the buffers it provides.
 227  *
 228  ***/
 229 bool
 230 silc_mime_parse(const unsigned char *mime, SilcUInt32 mime_len,
 231                 char *version, SilcUInt32 version_size,
 232                 char *content_type, SilcUInt32 content_type_size,
 233                 char *transfer_encoding, SilcUInt32 transfer_encoding_size,
 234                 unsigned char **mime_data_ptr, SilcUInt32 *mime_data_len);
 235
 236 /****f* silcutil/SilcStrUtilAPI/silc_strncat
 237  *
 238  * SYNOPSIS
 239  *
 240  *    char *silc_strncat(char *dest, SilcUInt32 dest_size,
 241  *                       const char *src, SilcUInt32 src_len);
 242  *
 243  * DESCRIPTION
 244  *
 245  *    Concatenates the `src' into `dest'.  If `src_len' is more than the
 246  *    size of the `dest' (minus NULL at the end) the `src' will be
 247  *    truncated to fit.
 248  *
 249  ***/
 250 char *silc_strncat(char *dest, SilcUInt32 dest_size,
 251                    const char *src, SilcUInt32 src_len);
 252
 253 #endif /* SILCSTRUTIL_H */