lib/silcutil/silcutil.h

   1 /*
   2
   3   silcutil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 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 Utilities
  21  *
  22  * DESCRIPTION
  23  *
  24  *    Utility functions.
  25  *
  26  ***/
  27
  28 #ifndef SILCUTIL_H
  29 #define SILCUTIL_H
  30
  31 /****f* silcutil/SilcUtilAPI/silc_gets
  32  *
  33  * SYNOPSIS
  34  *
  35  *    int silc_gets(char *dest, int destlen, const char *src, int srclen,
  36  *                  int begin);
  37  *
  38  * DESCRIPTION
  39  *
  40  *    Gets line from a buffer. Stops reading when a newline or EOF occurs.
  41  *    This doesn't remove the newline sign from the destination buffer. The
  42  *    argument begin is returned and should be passed again for the function.
  43  *
  44  ***/
  45 int silc_gets(char *dest, int destlen, const char *src, int srclen, int begin);
  46
  47 /****f* silcutil/SilcUtilAPI/silc_to_upper
  48  *
  49  * SYNOPSIS
  50  *
  51  *    SilcBool silc_to_upper(const char *string, char *dest,
  52  *                           SilcUInt32 dest_size);
  53  *
  54  * DESCRIPTION
  55  *
  56  *    Converts string to capital characters.
  57  *
  58  ***/
  59 SilcBool silc_to_upper(const char *string, char *dest, SilcUInt32 dest_size);
  60
  61 /****f* silcutil/SilcUtilAPI/silc_to_lower
  62  *
  63  * SYNOPSIS
  64  *
  65  *    SilcBool silc_to_lower(const char *string, char *dest,
  66  *                           SilcUInt32 dest_size);
  67  *
  68  * DESCRIPTION
  69  *
  70  *    Converts string to capital characters.
  71  *
  72  ***/
  73 SilcBool silc_to_lower(const char *string, char *dest, SilcUInt32 dest_size);
  74
  75 /****f* silcutil/SilcUtilAPI/silc_parse_userfqdn
  76  *
  77  * SYNOPSIS
  78  *
  79  *    int silc_parse_userfqdn(const char *string,
  80  *                            char *user, SilcUInt32 user_size,
  81  *                            char *fqdn, SilcUInt32 fqdn_size);
  82  *
  83  * DESCRIPTION
  84  *
  85  *    Parse userfqdn string which is in user@fqdn format.  Returns 0 on
  86  *    error, 1 if `user' was filled and 2 if both `user' and `fqdn'
  87  *    was filled.
  88  *
  89  ***/
  90 int silc_parse_userfqdn(const char *string,
  91                         char *user, SilcUInt32 user_size,
  92                         char *fqdn, SilcUInt32 fqdn_size);
  93
  94 /****f* silcutil/SilcUtilAPI/silc_parse_command_line
  95  *
  96  * SYNOPSIS
  97  *
  98  *    void silc_parse_command_line(unsigned char *buffer,
  99  *                                 unsigned char ***parsed,
 100  *                                 SilcUInt32 **parsed_lens,
 101  *                                 SilcUInt32 **parsed_types,
 102  *                                 SilcUInt32 *parsed_num,
 103  *                                 SilcUInt32 max_args);
 104  *
 105  * DESCRIPTION
 106  *
 107  *    Parses command line. At most `max_args' is taken. Rest of the line
 108  *    will be allocated as the last argument if there are more than `max_args'
 109  *    arguments in the line. Note that the command name is counted as one
 110  *    argument and is saved.
 111  *
 112  ***/
 113 void silc_parse_command_line(unsigned char *buffer,
 114                              unsigned char ***parsed,
 115                              SilcUInt32 **parsed_lens,
 116                              SilcUInt32 **parsed_types,
 117                              SilcUInt32 *parsed_num,
 118                              SilcUInt32 max_args);
 119
 120 /****f* silcutil/SilcUtilAPI/silc_format
 121  *
 122  * SYNOPSIS
 123  *
 124  *    char *silc_format(char *fmt, ...);
 125  *
 126  * DESCRIPTION
 127  *
 128  *    Formats arguments to a string and returns it after allocating memory
 129  *    for it. It must be remembered to free it later.
 130  *
 131  ***/
 132 char *silc_format(char *fmt, ...);
 133
 134 /****f* silcutil/SilcUtilAPI/silc_hash_id
 135  *
 136  * SYNOPSIS
 137  *
 138  *    SilcUInt32 silc_hash_id(void *key, void *user_context);
 139  *
 140  * DESCRIPTION
 141  *
 142  *    Hash a ID. The `user_context' is the ID type.
 143  *
 144  ***/
 145 SilcUInt32 silc_hash_id(void *key, void *user_context);
 146
 147 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_hash
 148  *
 149  * SYNOPSIS
 150  *
 151  *    SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context)
 152  *
 153  * DESCRIPTION
 154  *
 155  *    Hash Client ID's hash.
 156  *
 157  ***/
 158 SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context);
 159
 160 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare
 161  *
 162  * SYNOPSIS
 163  *
 164  *    SilcBool silc_hash_id_compare(void *key1, void *key2,
 165  *                                  void *user_context);
 166  *
 167  * DESCRIPTION
 168  *
 169  *    Compares two ID's. May be used as SilcHashTable comparison function.
 170  *    The Client ID's compares only the hash of the Client ID not any other
 171  *    part of the Client ID. Other ID's are fully compared.
 172  *
 173  ***/
 174 SilcBool silc_hash_id_compare(void *key1, void *key2, void *user_context);
 175
 176 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare_full
 177  *
 178  * SYNOPSIS
 179  *
 180  *    SilcBool silc_hash_id_compare_full(void *key1, void *key2,
 181  *                                       void *user_context)
 182  *
 183  * DESCRIPTION
 184  *
 185  *    Compares two ID's. May be used as SilcHashTable comparison function.
 186  *    To compare full ID's instead of only partial, like the
 187  *    silc_hash_id_compare does, use this function.
 188  *
 189  ***/
 190 SilcBool silc_hash_id_compare_full(void *key1, void *key2, void *user_context);
 191
 192 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_compare
 193  *
 194  * SYNOPSIS
 195  *
 196  *    SilcBool silc_hash_client_id_compare(void *key1, void *key2,
 197  *                                         void *user_context);
 198  *
 199  * DESCRIPTION
 200  *
 201  *    Compare two Client ID's entirely and not just the hash from the ID.
 202  *
 203  ***/
 204 SilcBool silc_hash_client_id_compare(void *key1, void *key2,
 205                                      void *user_context);
 206
 207 /****f* silcutil/SilcUtilAPI/silc_fingerprint
 208  *
 209  * SYNOPSIS
 210  *
 211  *    char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 212  *
 213  * DESCRIPTION
 214  *
 215  *    Return a textual representation of the fingerprint in *data, the
 216  *    caller must free the returned string.  Returns NULL on error.  If
 217  *    the `data_len' is longer than 255 bytes, only the first 255 bytes are
 218  *    used to create the fingerprint.
 219  *
 220  ***/
 221 char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 222
 223 /****f* silcutil/SilcUtilAPI/silc_string_is_ascii
 224  *
 225  * SYNOPSIS
 226  *
 227  *    SilcBool silc_string_is_ascii(const unsigned char *data,
 228  *                              SilcUInt32 data_len);
 229  *
 230  * DESCRIPTION
 231  *
 232  *    Return TRUE if the `data' is ASCII string.
 233  *
 234  ***/
 235 SilcBool silc_string_is_ascii(const unsigned char *data, SilcUInt32 data_len);
 236
 237 /****f* silcutil/SilcUtilAPI/silc_get_input
 238  *
 239  * SYNOPSIS
 240  *
 241  *    char *silc_get_input(const char *prompt, SilcBool echo_off);
 242  *
 243  * DESCRIPTION
 244  *
 245  *    Displays input prompt on command line and takes input data from user.
 246  *
 247  ***/
 248 char *silc_get_input(const char *prompt, SilcBool echo_off);
 249
 250 /* System dependant prototypes */
 251
 252 /****f* silcutil/SilcUtilAPI/silc_get_username
 253  *
 254  * SYNOPSIS
 255  *
 256  *    char *silc_get_username();
 257  *
 258  * DESCRIPTION
 259  *
 260  *    Returns the username of the user. If the global variable LOGNAME
 261  *    does not exists we will get the name from the passwd file.  The
 262  *    caller must free the returned name.
 263  *
 264  *    This function is system dependant.
 265  *
 266  ***/
 267 char *silc_get_username();
 268
 269 /****f* silcutil/SilcUtilAPI/silc_get_real_name
 270  *
 271  * SYNOPSIS
 272  *
 273  *    char *silc_get_real_name();
 274  *
 275  * DESCRIPTION
 276  *
 277  *    Returns the real name of ther user from the passwd file.  The
 278  *    caller must free the returned name.
 279  *
 280  *    This function is system dependant.
 281  *
 282  ***/
 283 char *silc_get_real_name();
 284
 285 /****f* silcutil/SilcUtilAPI/silc_va_copy
 286  *
 287  * SYNOPSIS
 288  *
 289  *    void silc_va_copy(va_list dest, va_list src);
 290  *
 291  * DESCRIPTION
 292  *
 293  *    Copies variable argument list.  This must be called in case the
 294  *    variable argument list must be evaluated multiple times.  For each
 295  *    evaluation the list must be copied and va_end must be called for
 296  *    each copied list.
 297  *
 298  ***/
 299 #if defined(HAVE_VA_COPY)
 300 #define silc_va_copy(dest, src) va_copy(dest, src);
 301 #elif defined(HAVE___VA_COPY)
 302 #define silc_va_copy(dest, src) __va_copy(dest, src);
 303 #elif defined(SILC_VA_COPY_ARRAY)
 304 #define silc_va_copy(dest, src) memmove(dest, src, sizeof(va_list));
 305 #else
 306 #define silc_va_copy(dest, src) dest = src;
 307 #endif
 308
 309 /****f* silcutil/SilcUtilAPI/silc_hexdump
 310  *
 311  * SYNOPSIS
 312  *
 313  *    void silc_hexdump(const unsigned char *data, SilcUInt32 data_len,
 314  *                      FILE *output);
 315  *
 316  * DESCRIPTION
 317  *
 318  *    Dumps the `data' of length of `data_len' bytes as HEX.  The `output'
 319  *    file specifies the destination.
 320  *
 321  ***/
 322 void silc_hexdump(const unsigned char *data, SilcUInt32 data_len,
 323                   FILE *output);
 324
 325 /****f* silcutil/SilcUtilAPI/silc_hex2data
 326  *
 327  * SYNOPSIS
 328  *
 329  *    SilcBool silc_hex2data(const char *hex, unsigned char *data,
 330  *                           SilcUInt32 data_size, SilcUInt32 *ret_data_len);
 331  *
 332  * DESCRIPTION
 333  *
 334  *    Converts HEX character string to binary data.  Each HEX numbers must
 335  *    have two characters in the `hex' string.
 336  *
 337  ***/
 338 SilcBool silc_hex2data(const char *hex, unsigned char *data,
 339                        SilcUInt32 data_size, SilcUInt32 *ret_data_len);
 340
 341 /****f* silcutil/SilcUtilAPI/silc_data2hex
 342  *
 343  * SYNOPSIS
 344  *
 345  *    SilcBool silc_data2hex(const unsigned char *data, SilcUInt32 data_len,
 346  *                           char *hex, SilcUInt32 hex_size);
 347  *
 348  * DESCRIPTION
 349  *
 350  *    Converts binary data to HEX string.  This NULL terminates the `hex'
 351  *    buffer automatically.
 352  *
 353  ***/
 354 SilcBool silc_data2hex(const unsigned char *data, SilcUInt32 data_len,
 355                        char *hex, SilcUInt32 hex_size);
 356
 357 #endif  /* !SILCUTIL_H */