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_string
 135  *
 136  * SYNOPSIS
 137  *
 138  *    SilcUInt32 silc_hash_string(void *key, void *user_context);
 139  *
 140  * DESCRIPTION
 141  *
 142  *    Basic has function to hash strings. May be used with the SilcHashTable.
 143  *    Note that this lowers the characters of the string (with tolower()) so
 144  *    this can be used to provide case-insensitive hashing.
 145  *
 146  ***/
 147 SilcUInt32 silc_hash_string(void *key, void *user_context);
 148
 149 /****f* silcutil/SilcUtilAPI/silc_hash_utf8_string
 150  *
 151  * SYNOPSIS
 152  *
 153  *    SilcUInt32 silc_hash_utf8_string(void *key, void *user_context);
 154  *
 155  * DESCRIPTION
 156  *
 157  *    Basic has function to hash UTF-8 strings. May be used with the
 158  *    SilcHashTable.  Used with identifier strings.  The key is
 159  *    expected to be casefolded.
 160  *
 161  ***/
 162 SilcUInt32 silc_hash_utf8_string(void *key, void *user_context);
 163
 164 /****f* silcutil/SilcUtilAPI/silc_hash_uint
 165  *
 166  * SYNOPSIS
 167  *
 168  *    SilcUInt32 silc_hash_uint(void *key, void *user_context);
 169  *
 170  * DESCRIPTION
 171  *
 172  *    Basic hash function to hash integers. May be used with the SilcHashTable.
 173  *
 174  ***/
 175 SilcUInt32 silc_hash_uint(void *key, void *user_context);
 176
 177 /****f* silcutil/SilcUtilAPI/silc_hash_ptr
 178  *
 179  * SYNOPSIS
 180  *
 181  *    SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 182  *
 183  * DESCRIPTION
 184  *
 185  *    Basic hash funtion to hash pointers. May be used with the SilcHashTable.
 186  *
 187  ***/
 188 SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 189
 190 /****f* silcutil/SilcUtilAPI/silc_hash_id
 191  *
 192  * SYNOPSIS
 193  *
 194  *    SilcUInt32 silc_hash_id(void *key, void *user_context);
 195  *
 196  * DESCRIPTION
 197  *
 198  *    Hash a ID. The `user_context' is the ID type.
 199  *
 200  ***/
 201 SilcUInt32 silc_hash_id(void *key, void *user_context);
 202
 203 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_hash
 204  *
 205  * SYNOPSIS
 206  *
 207  *    SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context)
 208  *
 209  * DESCRIPTION
 210  *
 211  *    Hash Client ID's hash.
 212  *
 213  ***/
 214 SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context);
 215
 216 /****f* silcutil/SilcUtilAPI/silc_hash_data
 217  *
 218  * SYNOPSIS
 219  *
 220  *    SilcUInt32 silc_hash_data(void *key, void *user_context);
 221  *
 222  * DESCRIPTION
 223  *
 224  *    Hash binary data. The `user_context' is the data length.
 225  *
 226  ***/
 227 SilcUInt32 silc_hash_data(void *key, void *user_context);
 228
 229 /****f* silcutil/SilcUtilAPI/silc_hash_string_compare
 230  *
 231  * SYNOPSIS
 232  *
 233  *    SilcBool silc_hash_string_compare(void *key1, void *key2,
 234  *                                  void *user_context);
 235  *
 236  * DESCRIPTION
 237  *
 238  *    Compares two strings. This ignores the case while comparing.  It may
 239  *    be used as SilcHashTable comparison function.
 240  *
 241  ***/
 242 SilcBool silc_hash_string_compare(void *key1, void *key2, void *user_context);
 243
 244 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare
 245  *
 246  * SYNOPSIS
 247  *
 248  *    SilcBool silc_hash_id_compare(void *key1, void *key2,
 249  *                                  void *user_context);
 250  *
 251  * DESCRIPTION
 252  *
 253  *    Compares two ID's. May be used as SilcHashTable comparison function.
 254  *    The Client ID's compares only the hash of the Client ID not any other
 255  *    part of the Client ID. Other ID's are fully compared.
 256  *
 257  ***/
 258 SilcBool silc_hash_id_compare(void *key1, void *key2, void *user_context);
 259
 260 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare_full
 261  *
 262  * SYNOPSIS
 263  *
 264  *    SilcBool silc_hash_id_compare_full(void *key1, void *key2,
 265  *                                       void *user_context)
 266  *
 267  * DESCRIPTION
 268  *
 269  *    Compares two ID's. May be used as SilcHashTable comparison function.
 270  *    To compare full ID's instead of only partial, like the
 271  *    silc_hash_id_compare does, use this function.
 272  *
 273  ***/
 274 SilcBool silc_hash_id_compare_full(void *key1, void *key2, void *user_context);
 275
 276 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_compare
 277  *
 278  * SYNOPSIS
 279  *
 280  *    SilcBool silc_hash_client_id_compare(void *key1, void *key2,
 281  *                                         void *user_context);
 282  *
 283  * DESCRIPTION
 284  *
 285  *    Compare two Client ID's entirely and not just the hash from the ID.
 286  *
 287  ***/
 288 SilcBool silc_hash_client_id_compare(void *key1, void *key2,
 289                                      void *user_context);
 290
 291 /****f* silcutil/SilcUtilAPI/silc_hash_data_compare
 292  *
 293  * SYNOPSIS
 294  *
 295  *    SilcBool silc_hash_data_compare(void *key1, void *key2,
 296  *                                    void *user_context);
 297  *
 298  * DESCRIPTION
 299  *
 300  *    Compares binary data. May be used as SilcHashTable comparison function.
 301  *
 302  ***/
 303 SilcBool silc_hash_data_compare(void *key1, void *key2, void *user_context);
 304
 305 /****f* silcutil/SilcUtilAPI/silc_hash_utf8_compare
 306  *
 307  * SYNOPSIS
 308  *
 309  *    SilcBool silc_hash_utf8_compare(void *key1, void *key2,
 310  *                                    void *user_context);
 311  *
 312  * DESCRIPTION
 313  *
 314  *    Compares UTF-8 strings.  Casefolded and NULL terminated strings are
 315  *    expected.  May be used as SilcHashTable comparison function.
 316  *
 317  ***/
 318 SilcBool silc_hash_utf8_compare(void *key1, void *key2, void *user_context);
 319
 320 /****f* silcutil/SilcUtilAPI/silc_fingerprint
 321  *
 322  * SYNOPSIS
 323  *
 324  *    char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 325  *
 326  * DESCRIPTION
 327  *
 328  *    Return a textual representation of the fingerprint in *data, the
 329  *    caller must free the returned string.
 330  *
 331  ***/
 332 char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 333
 334 /****f* silcutil/SilcUtilAPI/silc_string_is_ascii
 335  *
 336  * SYNOPSIS
 337  *
 338  *    SilcBool silc_string_is_ascii(const unsigned char *data,
 339  *                              SilcUInt32 data_len);
 340  *
 341  * DESCRIPTION
 342  *
 343  *    Return TRUE if the `data' is ASCII string.
 344  *
 345  ***/
 346 SilcBool silc_string_is_ascii(const unsigned char *data, SilcUInt32 data_len);
 347
 348 /****f* silcutil/SilcUtilAPI/silc_get_input
 349  *
 350  * SYNOPSIS
 351  *
 352  *    char *silc_get_input(const char *prompt, SilcBool echo_off);
 353  *
 354  * DESCRIPTION
 355  *
 356  *    Displays input prompt on command line and takes input data from user.
 357  *
 358  ***/
 359 char *silc_get_input(const char *prompt, SilcBool echo_off);
 360
 361 /* System dependant prototypes */
 362
 363 /****f* silcutil/SilcUtilAPI/silc_get_username
 364  *
 365  * SYNOPSIS
 366  *
 367  *    char *silc_get_username();
 368  *
 369  * DESCRIPTION
 370  *
 371  *    Returns the username of the user. If the global variable LOGNAME
 372  *    does not exists we will get the name from the passwd file.  The
 373  *    caller must free the returned name.
 374  *
 375  *    This function is system dependant.
 376  *
 377  ***/
 378 char *silc_get_username();
 379
 380 /****f* silcutil/SilcUtilAPI/silc_get_real_name
 381  *
 382  * SYNOPSIS
 383  *
 384  *    char *silc_get_real_name();
 385  *
 386  * DESCRIPTION
 387  *
 388  *    Returns the real name of ther user from the passwd file.  The
 389  *    caller must free the returned name.
 390  *
 391  *    This function is system dependant.
 392  *
 393  ***/
 394 char *silc_get_real_name();
 395
 396 /****f* silcutil/SilcUtilAPI/silc_va_copy
 397  *
 398  * SYNOPSIS
 399  *
 400  *    void silc_va_copy(va_list dest, va_list src);
 401  *
 402  * DESCRIPTION
 403  *
 404  *    Copies variable argument list.  This must be called in case the
 405  *    variable argument list must be evaluated multiple times.  For each
 406  *    evaluation the list must be copied and va_end must be called for
 407  *    each copied list.
 408  *
 409  ***/
 410 #if defined(HAVE_VA_COPY)
 411 #define silc_va_copy(dest, src) va_copy(dest, src);
 412 #elif defined(HAVE___VA_COPY)
 413 #define silc_va_copy(dest, src) __va_copy(dest, src);
 414 #elif defined(SILC_VA_COPY_ARRAY)
 415 #define silc_va_copy(dest, src) memmove(dest, src, sizeof(va_list));
 416 #else
 417 #define silc_va_copy(dest, src) dest = src;
 418 #endif
 419
 420 /****f* silcutil/SilcUtilAPI/silc_hexdump
 421  *
 422  * SYNOPSIS
 423  *
 424  *    void silc_hexdump(const unsigned char *data, SilcUInt32 data_len,
 425  *                      FILE *output);
 426  *
 427  * DESCRIPTION
 428  *
 429  *    Dumps the `data' of length of `data_len' bytes as HEX.  The `output'
 430  *    file specifies the destination.
 431  *
 432  ***/
 433 void silc_hexdump(const unsigned char *data, SilcUInt32 data_len,
 434                   FILE *output);
 435
 436 /****f* silcutil/SilcUtilAPI/silc_hex2data
 437  *
 438  * SYNOPSIS
 439  *
 440  *    SilcBool silc_hex2data(const char *hex, unsigned char *data,
 441  *                           SilcUInt32 data_size, SilcUInt32 *ret_data_len);
 442  *
 443  * DESCRIPTION
 444  *
 445  *    Converts HEX character string to binary data.  Each HEX numbers must
 446  *    have two characters in the `hex' string.
 447  *
 448  ***/
 449 SilcBool silc_hex2data(const char *hex, unsigned char *data,
 450                        SilcUInt32 data_size, SilcUInt32 *ret_data_len);
 451
 452 /****f* silcutil/SilcUtilAPI/silc_data2hex
 453  *
 454  * SYNOPSIS
 455  *
 456  *    SilcBool silc_data2hex(const unsigned char *data, SilcUInt32 data_len,
 457  *                           char *hex, SilcUInt32 hex_size);
 458  *
 459  * DESCRIPTION
 460  *
 461  *    Converts binary data to HEX string.  This NULL terminates the `hex'
 462  *    buffer automatically.
 463  *
 464  ***/
 465 SilcBool silc_data2hex(const unsigned char *data, SilcUInt32 data_len,
 466                        char *hex, SilcUInt32 hex_size);
 467
 468 #endif  /* !SILCUTIL_H */