lib/silcutil/silcutil.h

   1 /*
   2
   3   silcutil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2005 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_utf8_string
 200  *
 201  * SYNOPSIS
 202  *
 203  *    SilcUInt32 silc_hash_utf8_string(void *key, void *user_context);
 204  *
 205  * DESCRIPTION
 206  *
 207  *    Basic has function to hash UTF-8 strings. May be used with the
 208  *    SilcHashTable.  Used with identifier strings.  The key is
 209  *    expected to be casefolded.
 210  *
 211  ***/
 212 SilcUInt32 silc_hash_utf8_string(void *key, void *user_context);
 213
 214 /****f* silcutil/SilcUtilAPI/silc_hash_uint
 215  *
 216  * SYNOPSIS
 217  *
 218  *    SilcUInt32 silc_hash_uint(void *key, void *user_context);
 219  *
 220  * DESCRIPTION
 221  *
 222  *    Basic hash function to hash integers. May be used with the SilcHashTable.
 223  *
 224  ***/
 225 SilcUInt32 silc_hash_uint(void *key, void *user_context);
 226
 227 /****f* silcutil/SilcUtilAPI/silc_hash_ptr
 228  *
 229  * SYNOPSIS
 230  *
 231  *    SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 232  *
 233  * DESCRIPTION
 234  *
 235  *    Basic hash funtion to hash pointers. May be used with the SilcHashTable.
 236  *
 237  ***/
 238 SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 239
 240 /****f* silcutil/SilcUtilAPI/silc_hash_id
 241  *
 242  * SYNOPSIS
 243  *
 244  *    SilcUInt32 silc_hash_id(void *key, void *user_context);
 245  *
 246  * DESCRIPTION
 247  *
 248  *    Hash a ID. The `user_context' is the ID type.
 249  *
 250  ***/
 251 SilcUInt32 silc_hash_id(void *key, void *user_context);
 252
 253 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_hash
 254  *
 255  * SYNOPSIS
 256  *
 257  *    SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context)
 258  *
 259  * DESCRIPTION
 260  *
 261  *    Hash Client ID's hash.
 262  *
 263  ***/
 264 SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context);
 265
 266 /****f* silcutil/SilcUtilAPI/silc_hash_data
 267  *
 268  * SYNOPSIS
 269  *
 270  *    SilcUInt32 silc_hash_data(void *key, void *user_context);
 271  *
 272  * DESCRIPTION
 273  *
 274  *    Hash binary data. The `user_context' is the data length.
 275  *
 276  ***/
 277 SilcUInt32 silc_hash_data(void *key, void *user_context);
 278
 279 /****f* silcutil/SilcUtilAPI/silc_hash_public_key
 280  *
 281  * SYNOPSIS
 282  *
 283  *    SilcUInt32 silc_hash_public_key(void *key, void *user_context);
 284  *
 285  * DESCRIPTION
 286  *
 287  *    Hashed SILC Public key.
 288  *
 289  ***/
 290 SilcUInt32 silc_hash_public_key(void *key, void *user_context);
 291
 292 /****f* silcutil/SilcUtilAPI/silc_hash_string_compare
 293  *
 294  * SYNOPSIS
 295  *
 296  *    bool silc_hash_string_compare(void *key1, void *key2,
 297  *                                  void *user_context);
 298  *
 299  * DESCRIPTION
 300  *
 301  *    Compares two strings. It may be used as SilcHashTable comparison
 302  *    function.
 303  *
 304  ***/
 305 bool silc_hash_string_compare(void *key1, void *key2, void *user_context);
 306
 307 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare
 308  *
 309  * SYNOPSIS
 310  *
 311  *    bool silc_hash_id_compare(void *key1, void *key2, void *user_context);
 312  *
 313  * DESCRIPTION
 314  *
 315  *    Compares two ID's. May be used as SilcHashTable comparison function.
 316  *    The Client ID's compares only the hash of the Client ID not any other
 317  *    part of the Client ID. Other ID's are fully compared.
 318  *
 319  ***/
 320 bool silc_hash_id_compare(void *key1, void *key2, void *user_context);
 321
 322 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_compare
 323  *
 324  * SYNOPSIS
 325  *
 326  *    bool silc_hash_client_id_compare(void *key1, void *key2, void *user_context);
 327  *
 328  * DESCRIPTION
 329  *
 330  *    Compare two Client ID's entirely and not just the hash from the ID.
 331  *
 332  ***/
 333 bool silc_hash_client_id_compare(void *key1, void *key2, void *user_context);
 334
 335 /****f* silcutil/SilcUtilAPI/silc_hash_data_compare
 336  *
 337  * SYNOPSIS
 338  *
 339  *    bool silc_hash_data_compare(void *key1, void *key2, void *user_context);
 340  *
 341  * DESCRIPTION
 342  *
 343  *    Compares binary data. May be used as SilcHashTable comparison function.
 344  *
 345  ***/
 346 bool silc_hash_data_compare(void *key1, void *key2, void *user_context);
 347
 348 /****f* silcutil/SilcUtilAPI/silc_hash_utf8_compare
 349  *
 350  * SYNOPSIS
 351  *
 352  *    bool silc_hash_utf8_compare(void *key1, void *key2, void *user_context);
 353  *
 354  * DESCRIPTION
 355  *
 356  *    Compares UTF-8 strings.  Casefolded and NULL terminated strings are
 357  *    expected.  May be used as SilcHashTable comparison function.
 358  *
 359  ***/
 360 bool silc_hash_utf8_compare(void *key1, void *key2, void *user_context);
 361
 362 /****f* silcutil/SilcUtilAPI/silc_hash_public_key_compare
 363  *
 364  * SYNOPSIS
 365  *
 366  *    bool silc_hash_public_key_compare(void *key1, void *key2,
 367  *                                      void *user_context);
 368  *
 369  * DESCRIPTION
 370  *
 371  *    Compares two SILC Public keys. It may be used as SilcHashTable
 372  *    comparison function.
 373  *
 374  ***/
 375 bool silc_hash_public_key_compare(void *key1, void *key2, void *user_context);
 376
 377 /****f* silcutil/SilcUtilAPI/silc_client_chmode
 378  *
 379  * SYNOPSIS
 380  *
 381  *    char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
 382  *                             const char *hmac);
 383  *
 384  * DESCRIPTION
 385  *
 386  *    Parses mode mask and returns the mode as string.
 387  *
 388  ***/
 389 char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
 390                          const char *hmac);
 391
 392 /****f* silcutil/SilcUtilAPI/silc_client_chumode
 393  *
 394  * SYNOPSIS
 395  *
 396  *    char *silc_client_chumode(SilcUInt32 mode);
 397  *
 398  * DESCRIPTION
 399  *
 400  *    Parses channel user mode mask and returns te mode as string.
 401  *
 402  ***/
 403 char *silc_client_chumode(SilcUInt32 mode);
 404
 405 /****f* silcutil/SilcUtilAPI/silc_client_chumode_char
 406  *
 407  * SYNOPSIS
 408  *
 409  *    char *silc_client_chumode_char(SilcUInt32 mode);
 410  *
 411  * DESCRIPTION
 412  *
 413  *    Parses channel user mode and returns it as special mode character.
 414  *
 415  ***/
 416 char *silc_client_chumode_char(SilcUInt32 mode);
 417
 418 /****f* silcutil/SilcUtilAPI/silc_fingerprint
 419  *
 420  * SYNOPSIS
 421  *
 422  *    char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 423  *
 424  * DESCRIPTION
 425  *
 426  *    Return a textual representation of the fingerprint in *data, the
 427  *    caller must free the returned string.
 428  *
 429  ***/
 430 char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 431
 432 /****f* silcutil/SilcUtilAPI/silc_string_is_ascii
 433  *
 434  * SYNOPSIS
 435  *
 436  *    bool silc_string_is_ascii(const unsigned char *data,
 437  *                              SilcUInt32 data_len);
 438  *
 439  * DESCRIPTION
 440  *
 441  *    Return TRUE if the `data' is ASCII string.
 442  *
 443  ***/
 444 bool silc_string_is_ascii(const unsigned char *data, SilcUInt32 data_len);
 445
 446 /****f* silcutil/SilcUtilAPI/silc_parse_version_string
 447  *
 448  * SYNOPSIS
 449  *
 450  *    bool silc_parse_version_string(const char *version,
 451  *                                   SilcUInt32 *protocol_version,
 452  *                                   char **protocol_version_string,
 453  *                                   SilcUInt32 *software_version,
 454  *                                   char **software_version_string,
 455  *                                   char **vendor_version);
 456  *
 457  * DESCRIPTION
 458  *
 459  *    Parses SILC protocol style version string.
 460  *
 461  ***/
 462 bool silc_parse_version_string(const char *version,
 463                                SilcUInt32 *protocol_version,
 464                                char **protocol_version_string,
 465                                SilcUInt32 *software_version,
 466                                char **software_version_string,
 467                                char **vendor_version);
 468
 469 /****f* silcutil/SilcUtilAPI/silc_version_to_num
 470  *
 471  * SYNOPSIS
 472  *
 473  *    SilcUInt32 silc_version_to_num(const char *version);
 474  *
 475  * DESCRIPTION
 476  *
 477  *    Converts version string x.x into number representation.
 478  *
 479  ***/
 480 SilcUInt32 silc_version_to_num(const char *version);
 481
 482 /****f* silcutil/SilcUtilAPI/silc_get_input
 483  *
 484  * SYNOPSIS
 485  *
 486  *    char *silc_get_input(const char *prompt, bool echo_off);
 487  *
 488  * DESCRIPTION
 489  *
 490  *    Displays input prompt on command line and takes input data from user.
 491  *
 492  ***/
 493 char *silc_get_input(const char *prompt, bool echo_off);
 494
 495 /* System dependant prototypes */
 496
 497 /****f* silcutil/SilcUtilAPI/silc_gettimeofday
 498  *
 499  * SYNOPSIS
 500  *
 501  *    int silc_gettimeofday(struct timeval *p);
 502  *
 503  * DESCRIPTION
 504  *
 505  *    Return current time to struct timeval.  This function is system
 506  *    dependant.  Returns 0 on success and -1 on error.
 507  *
 508  ***/
 509 int silc_gettimeofday(struct timeval *p);
 510
 511 /****f* silcutil/SilcUtilAPI/silc_compare_timeval
 512  *
 513  * SYNOPSIS
 514  *
 515  *    bool silc_compare_timeval(struct timeval *smaller,
 516  *                              struct timeval *bigger)
 517  *
 518  * DESCRIPTION
 519  *
 520  *    Compare two timeval structures and return TRUE if the first
 521  *    time value is smaller than the second time value.
 522  *
 523  ***/
 524 bool silc_compare_timeval(struct timeval *smaller,
 525                           struct timeval *bigger);
 526
 527 /****f* silcutil/SilcUtilAPI/silc_string_regexify
 528  *
 529  * SYNOPSIS
 530  *
 531  *    char *silc_string_regexify(const char *string);
 532  *
 533  * DESCRIPTION
 534  *
 535  *    Inspects the `string' for wildcards and returns regex string that can
 536  *    be used by the GNU regex library. A comma (`,') in the `string' means
 537  *    that the string is list.
 538  *
 539  *    This function is system dependant.
 540  *
 541  ***/
 542 char *silc_string_regexify(const char *string);
 543
 544 /****f* silcutil/SilcUtilAPI/silc_string_regex_match
 545  *
 546  * SYNOPSIS
 547  *
 548  *    int silc_string_regex_match(const char *regex, const char *string);
 549  *
 550  * DESCRIPTION
 551  *
 552  *    Matches the two strings and returns TRUE if the strings match.
 553  *
 554  *    This function is system dependant.
 555  *
 556  ***/
 557 int silc_string_regex_match(const char *regex, const char *string);
 558
 559 /****f* silcutil/SilcUtilAPI/silc_string_match
 560  *
 561  * SYNOPSIS
 562  *
 563  *    int silc_string_match(const char *string1, const char *string2);
 564  *
 565  * DESCRIPTION
 566  *
 567  *    Do regex match to the two strings `string1' and `string2'. If the
 568  *    `string2' matches the `string1' this returns TRUE.
 569  *
 570  *    This function is system dependant.
 571  *
 572  ***/
 573 int silc_string_match(const char *string1, const char *string2);
 574
 575 /****f* silcutil/SilcUtilAPI/silc_get_username
 576  *
 577  * SYNOPSIS
 578  *
 579  *    char *silc_get_username();
 580  *
 581  * DESCRIPTION
 582  *
 583  *    Returns the username of the user. If the global variable LOGNAME
 584  *    does not exists we will get the name from the passwd file.  The
 585  *    caller must free the returned name.
 586  *
 587  *    This function is system dependant.
 588  *
 589  ***/
 590 char *silc_get_username();
 591
 592 /****f* silcutil/SilcUtilAPI/silc_get_real_name
 593  *
 594  * SYNOPSIS
 595  *
 596  *    char *silc_get_real_name();
 597  *
 598  * DESCRIPTION
 599  *
 600  *    Returns the real name of ther user from the passwd file.  The
 601  *    caller must free the returned name.
 602  *
 603  *    This function is system dependant.
 604  *
 605  ***/
 606 char *silc_get_real_name();
 607
 608 /****f* silcutil/SilcUtilAPI/silc_get_mode_list
 609  *
 610  * SYNOPSIS
 611  *
 612  *    bool silc_get_mode_list(SilcBuffer mode_list, SilcUInt32 mode_list_count,
 613  *                            SilcUInt32 **list);
 614  *
 615  * DESCRIPTION
 616  *
 617  *    Returns modes from list of 32 bit MSB first order values that are
 618  *    encoded one after the other in the `mode_list' into the `list'
 619  *    array.  The caller must free the returned list.  Return FALSE if
 620  *    there is error parsing the list.
 621  *
 622  ***/
 623 bool silc_get_mode_list(SilcBuffer mode_list, SilcUInt32 mode_list_count,
 624                         SilcUInt32 **list);
 625
 626 /****f* silcutil/SilcUtilAPI/silc_get_status_message
 627  *
 628  * SYNOPSIS
 629  *
 630  *    char *silc_get_status_message(SilcStatus status)
 631  *
 632  * DESCRIPTION
 633  *
 634  *    Returns status message string
 635  *
 636  ***/
 637 const char *silc_get_status_message(unsigned char status);
 638
 639 /****f* silcutil/SilcUtilAPI/silc_get_packet_name
 640  *
 641  * SYNOPSIS
 642  *
 643  *    char *silc_get_packet_name(SilcPacketType type);
 644  *
 645  * DESCRIPTION
 646  *
 647  *    Returns the name corresponding packet type `type'.
 648  *
 649  ***/
 650 const char *silc_get_packet_name(unsigned char type);
 651
 652 /****f* silcutil/SilcUtilAPI/silc_get_command_name
 653  *
 654  * SYNOPSIS
 655  *
 656  *    char *silc_get_command_name(SilcCommand command);
 657  *
 658  * DESCRIPTION
 659  *
 660  *    Returns the name corresponding SILC command `command'.
 661  *
 662  ***/
 663 const char *silc_get_command_name(unsigned char command);
 664
 665 #endif  /* !SILCUTIL_H */