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,
  46               int *begin);
  47
  48 /****f* silcutil/SilcUtilAPI/silc_check_line
  49  *
  50  * SYNOPSIS
  51  *
  52  *    int silc_check_line(char *buf);
  53  *
  54  * DESCRIPTION
  55  *
  56  *    Checks line for illegal characters. Return -1 when illegal character
  57  *    were found. This is used to check for bad lines when reading data from
  58  *    for example a configuration file.
  59  *
  60  ***/
  61 int silc_check_line(char *buf);
  62
  63 /****f* silcutil/SilcUtilAPI/silc_get_time
  64  *
  65  * SYNOPSIS
  66  *
  67  *    const char *silc_get_time(SilcUInt32 timeval)
  68  *
  69  * DESCRIPTION
  70  *
  71  *    Returns time as string.  If the the `timeval' is non-zero that
  72  *    value is returned as string.  If it is zero the current time of the
  73  *    local machine is returned.
  74  *
  75  ***/
  76 const char *silc_get_time(SilcUInt32 timeval);
  77
  78 /****f* silcutil/SilcUtilAPI/silc_to_upper
  79  *
  80  * SYNOPSIS
  81  *
  82  *    bool silc_to_upper(const char *string, char *dest, SilcUInt32 dest_size);
  83  *
  84  * DESCRIPTION
  85  *
  86  *    Converts string to capital characters.
  87  *
  88  ***/
  89 bool silc_to_upper(const char *string, char *dest, SilcUInt32 dest_size);
  90
  91 /****f* silcutil/SilcUtilAPI/silc_to_lower
  92  *
  93  * SYNOPSIS
  94  *
  95  *    bool silc_to_lower(const char *string, char *dest, SilcUInt32 dest_size);
  96  *
  97  * DESCRIPTION
  98  *
  99  *    Converts string to capital characters.
 100  *
 101  ***/
 102 bool silc_to_lower(const char *string, char *dest, SilcUInt32 dest_size);
 103
 104 /****f* silcutil/SilcUtilAPI/silc_parse_userfqdn
 105  *
 106  * SYNOPSIS
 107  *
 108  *    bool silc_parse_userfqdn(const char *string, char **left, char **right);
 109  *
 110  * DESCRIPTION
 111  *
 112  *    Parse userfqdn string which is in user@fqdn format.
 113  *
 114  ***/
 115 bool silc_parse_userfqdn(const char *string, char **left, char **right);
 116
 117 /****f* silcutil/SilcUtilAPI/silc_parse_command_line
 118  *
 119  * SYNOPSIS
 120  *
 121  *    void silc_parse_command_line(unsigned char *buffer,
 122  *                                 unsigned char ***parsed,
 123  *                                 SilcUInt32 **parsed_lens,
 124  *                                 SilcUInt32 **parsed_types,
 125  *                                 SilcUInt32 *parsed_num,
 126  *                                 SilcUInt32 max_args);
 127  *
 128  * DESCRIPTION
 129  *
 130  *    Parses command line. At most `max_args' is taken. Rest of the line
 131  *    will be allocated as the last argument if there are more than `max_args'
 132  *    arguments in the line. Note that the command name is counted as one
 133  *    argument and is saved.
 134  *
 135  ***/
 136 void silc_parse_command_line(unsigned char *buffer,
 137                              unsigned char ***parsed,
 138                              SilcUInt32 **parsed_lens,
 139                              SilcUInt32 **parsed_types,
 140                              SilcUInt32 *parsed_num,
 141                              SilcUInt32 max_args);
 142
 143 /****f* silcutil/SilcUtilAPI/silc_format
 144  *
 145  * SYNOPSIS
 146  *
 147  *    char *silc_format(char *fmt, ...);
 148  *
 149  * DESCRIPTION
 150  *
 151  *    Formats arguments to a string and returns it after allocating memory
 152  *    for it. It must be remembered to free it later.
 153  *
 154  ***/
 155 char *silc_format(char *fmt, ...);
 156
 157 /****f* silcutil/SilcUtilAPI/silc_id_render
 158  *
 159  * SYNOPSIS
 160  *
 161  *    char *silc_id_render(void *id, SilcUInt16 type);
 162  *
 163  * DESCRIPTION
 164  *
 165  *    Renders ID to suitable to print for example to log file.
 166  *
 167  ***/
 168 char *silc_id_render(void *id, SilcUInt16 type);
 169
 170 /****f* silcutil/SilcUtilAPI/silc_string_compare
 171  *
 172  * SYNOPSIS
 173  *
 174  *    int silc_string_compare(char *string1, char *string2);
 175  *
 176  * DESCRIPTION
 177  *
 178  *    Compares two strings. Strings may include wildcards '*' and '?'.
 179  *    Returns TRUE if strings match.
 180  *
 181  ***/
 182 int silc_string_compare(char *string1, char *string2);
 183
 184 /****f* silcutil/SilcUtilAPI/silc_hash_string
 185  *
 186  * SYNOPSIS
 187  *
 188  *    SilcUInt32 silc_hash_string(void *key, void *user_context);
 189  *
 190  * DESCRIPTION
 191  *
 192  *    Basic has function to hash strings. May be used with the SilcHashTable.
 193  *    Note that this lowers the characters of the string (with tolower()) so
 194  *    this is used usually with nicknames, channel and server names to provide
 195  *    case insensitive keys.
 196  *
 197  ***/
 198 SilcUInt32 silc_hash_string(void *key, void *user_context);
 199
 200 /****f* silcutil/SilcUtilAPI/silc_hash_uint
 201  *
 202  * SYNOPSIS
 203  *
 204  *    SilcUInt32 silc_hash_uint(void *key, void *user_context);
 205  *
 206  * DESCRIPTION
 207  *
 208  *    Basic hash function to hash integers. May be used with the SilcHashTable.
 209  *
 210  ***/
 211 SilcUInt32 silc_hash_uint(void *key, void *user_context);
 212
 213 /****f* silcutil/SilcUtilAPI/silc_hash_ptr
 214  *
 215  * SYNOPSIS
 216  *
 217  *    SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 218  *
 219  * DESCRIPTION
 220  *
 221  *    Basic hash funtion to hash pointers. May be used with the SilcHashTable.
 222  *
 223  ***/
 224 SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 225
 226 /****f* silcutil/SilcUtilAPI/silc_hash_id
 227  *
 228  * SYNOPSIS
 229  *
 230  *    SilcUInt32 silc_hash_id(void *key, void *user_context);
 231  *
 232  * DESCRIPTION
 233  *
 234  *    Hash a ID. The `user_context' is the ID type.
 235  *
 236  ***/
 237 SilcUInt32 silc_hash_id(void *key, void *user_context);
 238
 239 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_hash
 240  *
 241  * SYNOPSIS
 242  *
 243  *    SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context)
 244  *
 245  * DESCRIPTION
 246  *
 247  *    Hash Client ID's hash.
 248  *
 249  ***/
 250 SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context);
 251
 252 /****f* silcutil/SilcUtilAPI/silc_hash_data
 253  *
 254  * SYNOPSIS
 255  *
 256  *    SilcUInt32 silc_hash_data(void *key, void *user_context);
 257  *
 258  * DESCRIPTION
 259  *
 260  *    Hash binary data. The `user_context' is the data length.
 261  *
 262  ***/
 263 SilcUInt32 silc_hash_data(void *key, void *user_context);
 264
 265 /****f* silcutil/SilcUtilAPI/silc_hash_public_key
 266  *
 267  * SYNOPSIS
 268  *
 269  *    SilcUInt32 silc_hash_public_key(void *key, void *user_context);
 270  *
 271  * DESCRIPTION
 272  *
 273  *    Hashed SILC Public key.
 274  *
 275  ***/
 276 SilcUInt32 silc_hash_public_key(void *key, void *user_context);
 277
 278 /****f* silcutil/SilcUtilAPI/silc_hash_string_compare
 279  *
 280  * SYNOPSIS
 281  *
 282  *    bool silc_hash_string_compare(void *key1, void *key2,
 283  *                                  void *user_context);
 284  *
 285  * DESCRIPTION
 286  *
 287  *    Compares two strings. It may be used as SilcHashTable comparison
 288  *    function.
 289  *
 290  ***/
 291 bool silc_hash_string_compare(void *key1, void *key2, void *user_context);
 292
 293 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare
 294  *
 295  * SYNOPSIS
 296  *
 297  *    bool silc_hash_id_compare(void *key1, void *key2, void *user_context);
 298  *
 299  * DESCRIPTION
 300  *
 301  *    Compares two ID's. May be used as SilcHashTable comparison function.
 302  *    The Client ID's compares only the hash of the Client ID not any other
 303  *    part of the Client ID. Other ID's are fully compared.
 304  *
 305  ***/
 306 bool silc_hash_id_compare(void *key1, void *key2, void *user_context);
 307
 308 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_compare
 309  *
 310  * SYNOPSIS
 311  *
 312  *    bool silc_hash_client_id_compare(void *key1, void *key2, void *user_context);
 313  *
 314  * DESCRIPTION
 315  *
 316  *    Compare two Client ID's entirely and not just the hash from the ID.
 317  *
 318  ***/
 319 bool silc_hash_client_id_compare(void *key1, void *key2, void *user_context);
 320
 321 /****f* silcutil/SilcUtilAPI/silc_hash_data_compare
 322  *
 323  * SYNOPSIS
 324  *
 325  *    bool silc_hash_data_compare(void *key1, void *key2, void *user_context);
 326  *
 327  * DESCRIPTION
 328  *
 329  *    Compares binary data. May be used as SilcHashTable comparison function.
 330  *
 331  ***/
 332 bool silc_hash_data_compare(void *key1, void *key2, void *user_context);
 333
 334 /****f* silcutil/SilcUtilAPI/silc_hash_public_key_compare
 335  *
 336  * SYNOPSIS
 337  *
 338  *    bool silc_hash_public_key_compare(void *key1, void *key2, 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 */