lib/silcutil/silcutil.h

   1 /*
   2
   3   silcutil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 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 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_check_line
  48  *
  49  * SYNOPSIS
  50  *
  51  *    int silc_check_line(char *buf);
  52  *
  53  * DESCRIPTION
  54  *
  55  *    Checks line for illegal characters. Return -1 when illegal character
  56  *    were found. This is used to check for bad lines when reading data from
  57  *    for example a configuration file.
  58  *
  59  ***/
  60 int silc_check_line(char *buf);
  61
  62 /****f* silcutil/SilcUtilAPI/silc_get_time
  63  *
  64  * SYNOPSIS
  65  *
  66  *    const char *silc_get_time(SilcUInt32 timeval)
  67  *
  68  * DESCRIPTION
  69  *
  70  *    Returns time as string.  If the the `timeval' is non-zero that
  71  *    value is returned as string.  If it is zero the current time of the
  72  *    local machine is returned.
  73  *
  74  ***/
  75 const char *silc_get_time(SilcUInt32 timeval);
  76
  77 /****f* silcutil/SilcUtilAPI/silc_to_upper
  78  *
  79  * SYNOPSIS
  80  *
  81  *    bool silc_to_upper(const char *string, char *dest, SilcUInt32 dest_size);
  82  *
  83  * DESCRIPTION
  84  *
  85  *    Converts string to capital characters.
  86  *
  87  ***/
  88 bool silc_to_upper(const char *string, char *dest, SilcUInt32 dest_size);
  89
  90 /****f* silcutil/SilcUtilAPI/silc_to_lower
  91  *
  92  * SYNOPSIS
  93  *
  94  *    bool silc_to_lower(const char *string, char *dest, SilcUInt32 dest_size);
  95  *
  96  * DESCRIPTION
  97  *
  98  *    Converts string to capital characters.
  99  *
 100  ***/
 101 bool silc_to_lower(const char *string, char *dest, SilcUInt32 dest_size);
 102
 103 /****f* silcutil/SilcUtilAPI/silc_parse_userfqdn
 104  *
 105  * SYNOPSIS
 106  *
 107  *    bool silc_parse_userfqdn(const char *string, char **left, char **right);
 108  *
 109  * DESCRIPTION
 110  *
 111  *    Parse userfqdn string which is in user@fqdn format.
 112  *
 113  ***/
 114 bool silc_parse_userfqdn(const char *string, char **left, char **right);
 115
 116 /****f* silcutil/SilcUtilAPI/silc_parse_command_line
 117  *
 118  * SYNOPSIS
 119  *
 120  *    void silc_parse_command_line(unsigned char *buffer,
 121  *                                 unsigned char ***parsed,
 122  *                                 SilcUInt32 **parsed_lens,
 123  *                                 SilcUInt32 **parsed_types,
 124  *                                 SilcUInt32 *parsed_num,
 125  *                                 SilcUInt32 max_args);
 126  *
 127  * DESCRIPTION
 128  *
 129  *    Parses command line. At most `max_args' is taken. Rest of the line
 130  *    will be allocated as the last argument if there are more than `max_args'
 131  *    arguments in the line. Note that the command name is counted as one
 132  *    argument and is saved.
 133  *
 134  ***/
 135 void silc_parse_command_line(unsigned char *buffer,
 136                              unsigned char ***parsed,
 137                              SilcUInt32 **parsed_lens,
 138                              SilcUInt32 **parsed_types,
 139                              SilcUInt32 *parsed_num,
 140                              SilcUInt32 max_args);
 141
 142 /****f* silcutil/SilcUtilAPI/silc_format
 143  *
 144  * SYNOPSIS
 145  *
 146  *    char *silc_format(char *fmt, ...);
 147  *
 148  * DESCRIPTION
 149  *
 150  *    Formats arguments to a string and returns it after allocating memory
 151  *    for it. It must be remembered to free it later.
 152  *
 153  ***/
 154 char *silc_format(char *fmt, ...);
 155
 156 /****f* silcutil/SilcUtilAPI/silc_id_render
 157  *
 158  * SYNOPSIS
 159  *
 160  *    char *silc_id_render(void *id, SilcUInt16 type);
 161  *
 162  * DESCRIPTION
 163  *
 164  *    Renders ID to suitable to print for example to log file.
 165  *
 166  ***/
 167 char *silc_id_render(void *id, SilcUInt16 type);
 168
 169 /****f* silcutil/SilcUtilAPI/silc_string_compare
 170  *
 171  * SYNOPSIS
 172  *
 173  *    int silc_string_compare(char *string1, char *string2);
 174  *
 175  * DESCRIPTION
 176  *
 177  *    Compares two strings. Strings may include wildcards '*' and '?'.
 178  *    Returns TRUE if strings match.
 179  *
 180  ***/
 181 int silc_string_compare(char *string1, char *string2);
 182
 183 /****f* silcutil/SilcUtilAPI/silc_hash_string
 184  *
 185  * SYNOPSIS
 186  *
 187  *    SilcUInt32 silc_hash_string(void *key, void *user_context);
 188  *
 189  * DESCRIPTION
 190  *
 191  *    Basic has function to hash strings. May be used with the SilcHashTable.
 192  *    Note that this lowers the characters of the string (with tolower()) so
 193  *    this is used usually with nicknames, channel and server names to provide
 194  *    case insensitive keys.
 195  *
 196  ***/
 197 SilcUInt32 silc_hash_string(void *key, void *user_context);
 198
 199 /****f* silcutil/SilcUtilAPI/silc_hash_uint
 200  *
 201  * SYNOPSIS
 202  *
 203  *    SilcUInt32 silc_hash_uint(void *key, void *user_context);
 204  *
 205  * DESCRIPTION
 206  *
 207  *    Basic hash function to hash integers. May be used with the SilcHashTable.
 208  *
 209  ***/
 210 SilcUInt32 silc_hash_uint(void *key, void *user_context);
 211
 212 /****f* silcutil/SilcUtilAPI/silc_hash_ptr
 213  *
 214  * SYNOPSIS
 215  *
 216  *    SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 217  *
 218  * DESCRIPTION
 219  *
 220  *    Basic hash funtion to hash pointers. May be used with the SilcHashTable.
 221  *
 222  ***/
 223 SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 224
 225 /****f* silcutil/SilcUtilAPI/silc_hash_id
 226  *
 227  * SYNOPSIS
 228  *
 229  *    SilcUInt32 silc_hash_id(void *key, void *user_context);
 230  *
 231  * DESCRIPTION
 232  *
 233  *    Hash a ID. The `user_context' is the ID type.
 234  *
 235  ***/
 236 SilcUInt32 silc_hash_id(void *key, void *user_context);
 237
 238 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_hash
 239  *
 240  * SYNOPSIS
 241  *
 242  *    SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context)
 243  *
 244  * DESCRIPTION
 245  *
 246  *    Hash Client ID's hash.
 247  *
 248  ***/
 249 SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context);
 250
 251 /****f* silcutil/SilcUtilAPI/silc_hash_data
 252  *
 253  * SYNOPSIS
 254  *
 255  *    SilcUInt32 silc_hash_data(void *key, void *user_context);
 256  *
 257  * DESCRIPTION
 258  *
 259  *    Hash binary data. The `user_context' is the data length.
 260  *
 261  ***/
 262 SilcUInt32 silc_hash_data(void *key, void *user_context);
 263
 264 /****f* silcutil/SilcUtilAPI/silc_hash_public_key
 265  *
 266  * SYNOPSIS
 267  *
 268  *    SilcUInt32 silc_hash_public_key(void *key, void *user_context);
 269  *
 270  * DESCRIPTION
 271  *
 272  *    Hashed SILC Public key.
 273  *
 274  ***/
 275 SilcUInt32 silc_hash_public_key(void *key, void *user_context);
 276
 277 /****f* silcutil/SilcUtilAPI/silc_hash_string_compare
 278  *
 279  * SYNOPSIS
 280  *
 281  *    bool silc_hash_string_compare(void *key1, void *key2,
 282  *                                  void *user_context);
 283  *
 284  * DESCRIPTION
 285  *
 286  *    Compares two strings. It may be used as SilcHashTable comparison
 287  *    function.
 288  *
 289  ***/
 290 bool silc_hash_string_compare(void *key1, void *key2, void *user_context);
 291
 292 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare
 293  *
 294  * SYNOPSIS
 295  *
 296  *    bool silc_hash_id_compare(void *key1, void *key2, void *user_context);
 297  *
 298  * DESCRIPTION
 299  *
 300  *    Compares two ID's. May be used as SilcHashTable comparison function.
 301  *    The Client ID's compares only the hash of the Client ID not any other
 302  *    part of the Client ID. Other ID's are fully compared.
 303  *
 304  ***/
 305 bool silc_hash_id_compare(void *key1, void *key2, void *user_context);
 306
 307 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_compare
 308  *
 309  * SYNOPSIS
 310  *
 311  *    bool silc_hash_client_id_compare(void *key1, void *key2, void *user_context);
 312  *
 313  * DESCRIPTION
 314  *
 315  *    Compare two Client ID's entirely and not just the hash from the ID.
 316  *
 317  ***/
 318 bool silc_hash_client_id_compare(void *key1, void *key2, void *user_context);
 319
 320 /****f* silcutil/SilcUtilAPI/silc_hash_data_compare
 321  *
 322  * SYNOPSIS
 323  *
 324  *    bool silc_hash_data_compare(void *key1, void *key2, void *user_context);
 325  *
 326  * DESCRIPTION
 327  *
 328  *    Compares binary data. May be used as SilcHashTable comparison function.
 329  *
 330  ***/
 331 bool silc_hash_data_compare(void *key1, void *key2, void *user_context);
 332
 333 /****f* silcutil/SilcUtilAPI/silc_hash_public_key_compare
 334  *
 335  * SYNOPSIS
 336  *
 337  *    bool silc_hash_public_key_compare(void *key1, void *key2,
 338  *                                      void *user_context);
 339  *
 340  * DESCRIPTION
 341  *
 342  *    Compares two SILC Public keys. It may be used as SilcHashTable
 343  *    comparison function.
 344  *
 345  ***/
 346 bool silc_hash_public_key_compare(void *key1, void *key2, void *user_context);
 347
 348 /****f* silcutil/SilcUtilAPI/silc_client_chmode
 349  *
 350  * SYNOPSIS
 351  *
 352  *    char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
 353  *                             const char *hmac);
 354  *
 355  * DESCRIPTION
 356  *
 357  *    Parses mode mask and returns the mode as string.
 358  *
 359  ***/
 360 char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
 361                          const char *hmac);
 362
 363 /****f* silcutil/SilcUtilAPI/silc_client_chumode
 364  *
 365  * SYNOPSIS
 366  *
 367  *    char *silc_client_chumode(SilcUInt32 mode);
 368  *
 369  * DESCRIPTION
 370  *
 371  *    Parses channel user mode mask and returns te mode as string.
 372  *
 373  ***/
 374 char *silc_client_chumode(SilcUInt32 mode);
 375
 376 /****f* silcutil/SilcUtilAPI/silc_client_chumode_char
 377  *
 378  * SYNOPSIS
 379  *
 380  *    char *silc_client_chumode_char(SilcUInt32 mode);
 381  *
 382  * DESCRIPTION
 383  *
 384  *    Parses channel user mode and returns it as special mode character.
 385  *
 386  ***/
 387 char *silc_client_chumode_char(SilcUInt32 mode);
 388
 389 /****f* silcutil/SilcUtilAPI/silc_fingerprint
 390  *
 391  * SYNOPSIS
 392  *
 393  *    char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 394  *
 395  * DESCRIPTION
 396  *
 397  *    Return a textual representation of the fingerprint in *data, the
 398  *    caller must free the returned string.
 399  *
 400  ***/
 401 char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 402
 403 /****f* silcutil/SilcUtilAPI/silc_string_is_ascii
 404  *
 405  * SYNOPSIS
 406  *
 407  *    bool silc_string_is_ascii(const unsigned char *data,
 408  *                              SilcUInt32 data_len);
 409  *
 410  * DESCRIPTION
 411  *
 412  *    Return TRUE if the `data' is ASCII string.
 413  *
 414  ***/
 415 bool silc_string_is_ascii(const unsigned char *data, SilcUInt32 data_len);
 416
 417 /****f* silcutil/SilcUtilAPI/silc_parse_version_string
 418  *
 419  * SYNOPSIS
 420  *
 421  *    bool silc_parse_version_string(const char *version,
 422  *                                   SilcUInt32 *protocol_version,
 423  *                                   char **protocol_version_string,
 424  *                                   SilcUInt32 *software_version,
 425  *                                   char **software_version_string,
 426  *                                   char **vendor_version);
 427  *
 428  * DESCRIPTION
 429  *
 430  *    Parses SILC protocol style version string.
 431  *
 432  ***/
 433 bool silc_parse_version_string(const char *version,
 434                                SilcUInt32 *protocol_version,
 435                                char **protocol_version_string,
 436                                SilcUInt32 *software_version,
 437                                char **software_version_string,
 438                                char **vendor_version);
 439
 440 /****f* silcutil/SilcUtilAPI/silc_version_to_num
 441  *
 442  * SYNOPSIS
 443  *
 444  *    SilcUInt32 silc_version_to_num(const char *version);
 445  *
 446  * DESCRIPTION
 447  *
 448  *    Converts version string x.x into number representation.
 449  *
 450  ***/
 451 SilcUInt32 silc_version_to_num(const char *version);
 452
 453 /****f* silcutil/SilcUtilAPI/silc_get_input
 454  *
 455  * SYNOPSIS
 456  *
 457  *    char *silc_get_input(const char *prompt, bool echo_off);
 458  *
 459  * DESCRIPTION
 460  *
 461  *    Displays input prompt on command line and takes input data from user.
 462  *
 463  ***/
 464 char *silc_get_input(const char *prompt, bool echo_off);
 465
 466 /* System dependant prototypes */
 467
 468 /****f* silcutil/SilcUtilAPI/silc_gettimeofday
 469  *
 470  * SYNOPSIS
 471  *
 472  *    int silc_gettimeofday(struct timeval *p);
 473  *
 474  * DESCRIPTION
 475  *
 476  *    Return current time to struct timeval.  This function is system
 477  *    dependant.  Returns 0 on success and -1 on error.
 478  *
 479  ***/
 480 int silc_gettimeofday(struct timeval *p);
 481
 482 /****f* silcutil/SilcUtilAPI/silc_compare_timeval
 483  *
 484  * SYNOPSIS
 485  *
 486  *    bool silc_compare_timeval(struct timeval *smaller,
 487  *                              struct timeval *bigger)
 488  *
 489  * DESCRIPTION
 490  *
 491  *    Compare two timeval structures and return TRUE if the first
 492  *    time value is smaller than the second time value.
 493  *
 494  ***/
 495 bool silc_compare_timeval(struct timeval *smaller,
 496                           struct timeval *bigger);
 497
 498 /****f* silcutil/SilcUtilAPI/silc_string_regexify
 499  *
 500  * SYNOPSIS
 501  *
 502  *    char *silc_string_regexify(const char *string);
 503  *
 504  * DESCRIPTION
 505  *
 506  *    Inspects the `string' for wildcards and returns regex string that can
 507  *    be used by the GNU regex library. A comma (`,') in the `string' means
 508  *    that the string is list.
 509  *
 510  *    This function is system dependant.
 511  *
 512  ***/
 513 char *silc_string_regexify(const char *string);
 514
 515 /****f* silcutil/SilcUtilAPI/silc_string_regex_match
 516  *
 517  * SYNOPSIS
 518  *
 519  *    int silc_string_regex_match(const char *regex, const char *string);
 520  *
 521  * DESCRIPTION
 522  *
 523  *    Matches the two strings and returns TRUE if the strings match.
 524  *
 525  *    This function is system dependant.
 526  *
 527  ***/
 528 int silc_string_regex_match(const char *regex, const char *string);
 529
 530 /****f* silcutil/SilcUtilAPI/silc_string_match
 531  *
 532  * SYNOPSIS
 533  *
 534  *    int silc_string_match(const char *string1, const char *string2);
 535  *
 536  * DESCRIPTION
 537  *
 538  *    Do regex match to the two strings `string1' and `string2'. If the
 539  *    `string2' matches the `string1' this returns TRUE.
 540  *
 541  *    This function is system dependant.
 542  *
 543  ***/
 544 int silc_string_match(const char *string1, const char *string2);
 545
 546 /****f* silcutil/SilcUtilAPI/silc_get_username
 547  *
 548  * SYNOPSIS
 549  *
 550  *    char *silc_get_username();
 551  *
 552  * DESCRIPTION
 553  *
 554  *    Returns the username of the user. If the global variable LOGNAME
 555  *    does not exists we will get the name from the passwd file.  The
 556  *    caller must free the returned name.
 557  *
 558  *    This function is system dependant.
 559  *
 560  ***/
 561 char *silc_get_username();
 562
 563 /****f* silcutil/SilcUtilAPI/silc_get_real_name
 564  *
 565  * SYNOPSIS
 566  *
 567  *    char *silc_get_real_name();
 568  *
 569  * DESCRIPTION
 570  *
 571  *    Returns the real name of ther user from the passwd file.  The
 572  *    caller must free the returned name.
 573  *
 574  *    This function is system dependant.
 575  *
 576  ***/
 577 char *silc_get_real_name();
 578
 579 /****f* silcutil/SilcUtilAPI/silc_get_mode_list
 580  *
 581  * SYNOPSIS
 582  *
 583  *    bool silc_get_mode_list(SilcBuffer mode_list, SilcUInt32 mode_list_count,
 584  *                            SilcUInt32 **list);
 585  *
 586  * DESCRIPTION
 587  *
 588  *    Returns modes from list of 32 bit MSB first order values that are
 589  *    encoded one after the other in the `mode_list' into the `list'
 590  *    array.  The caller must free the returned list.  Return FALSE if
 591  *    there is error parsing the list.
 592  *
 593  ***/
 594 bool silc_get_mode_list(SilcBuffer mode_list, SilcUInt32 mode_list_count,
 595                         SilcUInt32 **list);
 596
 597 /****f* silcutil/SilcUtilAPI/silc_get_status_message
 598  *
 599  * SYNOPSIS
 600  *
 601  *    char *silc_get_status_message(SilcStatus status)
 602  *
 603  * DESCRIPTION
 604  *
 605  *    Returns status message string
 606  *
 607  ***/
 608 const char *silc_get_status_message(unsigned char status);
 609
 610 /****f* silcutil/SilcUtilAPI/silc_get_packet_name
 611  *
 612  * SYNOPSIS
 613  *
 614  *    char *silc_get_packet_name(SilcPacketType type);
 615  *
 616  * DESCRIPTION
 617  *
 618  *    Returns the name corresponding packet type `type'.
 619  *
 620  ***/
 621 const char *silc_get_packet_name(unsigned char type);
 622
 623 /****f* silcutil/SilcUtilAPI/silc_get_command_name
 624  *
 625  * SYNOPSIS
 626  *
 627  *    char *silc_get_command_name(SilcCommand command);
 628  *
 629  * DESCRIPTION
 630  *
 631  *    Returns the name corresponding SILC command `command'.
 632  *
 633  ***/
 634 const char *silc_get_command_name(unsigned char command);
 635
 636 #endif  /* !SILCUTIL_H */