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.
 217  *
 218  ***/
 219 char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 220
 221 /****f* silcutil/SilcUtilAPI/silc_string_is_ascii
 222  *
 223  * SYNOPSIS
 224  *
 225  *    SilcBool silc_string_is_ascii(const unsigned char *data,
 226  *                              SilcUInt32 data_len);
 227  *
 228  * DESCRIPTION
 229  *
 230  *    Return TRUE if the `data' is ASCII string.
 231  *
 232  ***/
 233 SilcBool silc_string_is_ascii(const unsigned char *data, SilcUInt32 data_len);
 234
 235 /****f* silcutil/SilcUtilAPI/silc_get_input
 236  *
 237  * SYNOPSIS
 238  *
 239  *    char *silc_get_input(const char *prompt, SilcBool echo_off);
 240  *
 241  * DESCRIPTION
 242  *
 243  *    Displays input prompt on command line and takes input data from user.
 244  *
 245  ***/
 246 char *silc_get_input(const char *prompt, SilcBool echo_off);
 247
 248 /* System dependant prototypes */
 249
 250 /****f* silcutil/SilcUtilAPI/silc_get_username
 251  *
 252  * SYNOPSIS
 253  *
 254  *    char *silc_get_username();
 255  *
 256  * DESCRIPTION
 257  *
 258  *    Returns the username of the user. If the global variable LOGNAME
 259  *    does not exists we will get the name from the passwd file.  The
 260  *    caller must free the returned name.
 261  *
 262  *    This function is system dependant.
 263  *
 264  ***/
 265 char *silc_get_username();
 266
 267 /****f* silcutil/SilcUtilAPI/silc_get_real_name
 268  *
 269  * SYNOPSIS
 270  *
 271  *    char *silc_get_real_name();
 272  *
 273  * DESCRIPTION
 274  *
 275  *    Returns the real name of ther user from the passwd file.  The
 276  *    caller must free the returned name.
 277  *
 278  *    This function is system dependant.
 279  *
 280  ***/
 281 char *silc_get_real_name();
 282
 283 /****f* silcutil/SilcUtilAPI/silc_va_copy
 284  *
 285  * SYNOPSIS
 286  *
 287  *    void silc_va_copy(va_list dest, va_list src);
 288  *
 289  * DESCRIPTION
 290  *
 291  *    Copies variable argument list.  This must be called in case the
 292  *    variable argument list must be evaluated multiple times.  For each
 293  *    evaluation the list must be copied and va_end must be called for
 294  *    each copied list.
 295  *
 296  ***/
 297 #if defined(HAVE_VA_COPY)
 298 #define silc_va_copy(dest, src) va_copy(dest, src);
 299 #elif defined(HAVE___VA_COPY)
 300 #define silc_va_copy(dest, src) __va_copy(dest, src);
 301 #elif defined(SILC_VA_COPY_ARRAY)
 302 #define silc_va_copy(dest, src) memmove(dest, src, sizeof(va_list));
 303 #else
 304 #define silc_va_copy(dest, src) dest = src;
 305 #endif
 306
 307 /****f* silcutil/SilcUtilAPI/silc_hexdump
 308  *
 309  * SYNOPSIS
 310  *
 311  *    void silc_hexdump(const unsigned char *data, SilcUInt32 data_len,
 312  *                      FILE *output);
 313  *
 314  * DESCRIPTION
 315  *
 316  *    Dumps the `data' of length of `data_len' bytes as HEX.  The `output'
 317  *    file specifies the destination.
 318  *
 319  ***/
 320 void silc_hexdump(const unsigned char *data, SilcUInt32 data_len,
 321                   FILE *output);
 322
 323 /****f* silcutil/SilcUtilAPI/silc_hex2data
 324  *
 325  * SYNOPSIS
 326  *
 327  *    SilcBool silc_hex2data(const char *hex, unsigned char *data,
 328  *                           SilcUInt32 data_size, SilcUInt32 *ret_data_len);
 329  *
 330  * DESCRIPTION
 331  *
 332  *    Converts HEX character string to binary data.  Each HEX numbers must
 333  *    have two characters in the `hex' string.
 334  *
 335  ***/
 336 SilcBool silc_hex2data(const char *hex, unsigned char *data,
 337                        SilcUInt32 data_size, SilcUInt32 *ret_data_len);
 338
 339 /****f* silcutil/SilcUtilAPI/silc_data2hex
 340  *
 341  * SYNOPSIS
 342  *
 343  *    SilcBool silc_data2hex(const unsigned char *data, SilcUInt32 data_len,
 344  *                           char *hex, SilcUInt32 hex_size);
 345  *
 346  * DESCRIPTION
 347  *
 348  *    Converts binary data to HEX string.  This NULL terminates the `hex'
 349  *    buffer automatically.
 350  *
 351  ***/
 352 SilcBool silc_data2hex(const unsigned char *data, SilcUInt32 data_len,
 353                        char *hex, SilcUInt32 hex_size);
 354
 355 #endif  /* !SILCUTIL_H */