lib/silcutil/silcutil.h

   1 /*
   2
   3   silcutil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2002 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, void *user_context);
 338  *
 339  * DESCRIPTION
 340  *
 341  *    Compares two SILC Public keys. It may be used as SilcHashTable
 342  *    comparison function.
 343  *
 344  ***/
 345 bool silc_hash_public_key_compare(void *key1, void *key2, void *user_context);
 346
 347 /****f* silcutil/SilcUtilAPI/silc_client_chmode
 348  *
 349  * SYNOPSIS
 350  *
 351  *    char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
 352  *                             const char *hmac);
 353  *
 354  * DESCRIPTION
 355  *
 356  *    Parses mode mask and returns the mode as string.
 357  *
 358  ***/
 359 char *silc_client_chmode(SilcUInt32 mode, const char *cipher,
 360                          const char *hmac);
 361
 362 /****f* silcutil/SilcUtilAPI/silc_client_chumode
 363  *
 364  * SYNOPSIS
 365  *
 366  *    char *silc_client_chumode(SilcUInt32 mode);
 367  *
 368  * DESCRIPTION
 369  *
 370  *    Parses channel user mode mask and returns te mode as string.
 371  *
 372  ***/
 373 char *silc_client_chumode(SilcUInt32 mode);
 374
 375 /****f* silcutil/SilcUtilAPI/silc_client_chumode_char
 376  *
 377  * SYNOPSIS
 378  *
 379  *    char *silc_client_chumode_char(SilcUInt32 mode);
 380  *
 381  * DESCRIPTION
 382  *
 383  *    Parses channel user mode and returns it as special mode character.
 384  *
 385  ***/
 386 char *silc_client_chumode_char(SilcUInt32 mode);
 387
 388 /****f* silcutil/SilcUtilAPI/silc_fingerprint
 389  *
 390  * SYNOPSIS
 391  *
 392  *    char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 393  *
 394  * DESCRIPTION
 395  *
 396  *    Return a textual representation of the fingerprint in *data, the
 397  *    caller must free the returned string.
 398  *
 399  ***/
 400 char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 401
 402 /****f* silcutil/SilcUtilAPI/silc_string_is_ascii
 403  *
 404  * SYNOPSIS
 405  *
 406  *    bool silc_string_is_ascii(const unsigned char *data,
 407  *                              SilcUInt32 data_len);
 408  *
 409  * DESCRIPTION
 410  *
 411  *    Return TRUE if the `data' is ASCII string.
 412  *
 413  ***/
 414 bool silc_string_is_ascii(const unsigned char *data, SilcUInt32 data_len);
 415
 416 /****f* silcutil/SilcUtilAPI/silc_parse_version_string
 417  *
 418  * SYNOPSIS
 419  *
 420  *    bool silc_parse_version_string(const char *version,
 421  *                                   SilcUInt32 *protocol_version,
 422  *                                   char **protocol_version_string,
 423  *                                   SilcUInt32 *software_version,
 424  *                                   char **software_version_string,
 425  *                                   char **vendor_version);
 426  *
 427  * DESCRIPTION
 428  *
 429  *    Parses SILC protocol style version string.
 430  *
 431  ***/
 432 bool silc_parse_version_string(const char *version,
 433                                SilcUInt32 *protocol_version,
 434                                char **protocol_version_string,
 435                                SilcUInt32 *software_version,
 436                                char **software_version_string,
 437                                char **vendor_version);
 438
 439 /****f* silcutil/SilcUtilAPI/silc_version_to_num
 440  *
 441  * SYNOPSIS
 442  *
 443  *    SilcUInt32 silc_version_to_num(const char *version);
 444  *
 445  * DESCRIPTION
 446  *
 447  *    Converts version string x.x into number representation.
 448  *
 449  ***/
 450 SilcUInt32 silc_version_to_num(const char *version);
 451
 452 /****f* silcutil/SilcUtilAPI/silc_get_input
 453  *
 454  * SYNOPSIS
 455  *
 456  *    char *silc_get_input(const char *prompt, bool echo_off);
 457  *
 458  * DESCRIPTION
 459  *
 460  *    Displays input prompt on command line and takes input data from user.
 461  *
 462  ***/
 463 char *silc_get_input(const char *prompt, bool echo_off);
 464
 465 /* System dependant prototypes */
 466
 467 /****f* silcutil/SilcUtilAPI/silc_gettimeofday
 468  *
 469  * SYNOPSIS
 470  *
 471  *    int silc_gettimeofday(struct timeval *p);
 472  *
 473  * DESCRIPTION
 474  *
 475  *    Return current time to struct timeval.  This function is system
 476  *    dependant.  Returns 0 on success and -1 on error.
 477  *
 478  ***/
 479 int silc_gettimeofday(struct timeval *p);
 480
 481 /****f* silcutil/SilcUtilAPI/silc_compare_timeval
 482  *
 483  * SYNOPSIS
 484  *
 485  *    bool silc_compare_timeval(struct timeval *smaller,
 486  *                              struct timeval *bigger)
 487  *
 488  * DESCRIPTION
 489  *
 490  *    Compare two timeval structures and return TRUE if the first
 491  *    time value is smaller than the second time value.
 492  *
 493  ***/
 494 bool silc_compare_timeval(struct timeval *smaller,
 495                           struct timeval *bigger);
 496
 497 /****f* silcutil/SilcUtilAPI/silc_string_regexify
 498  *
 499  * SYNOPSIS
 500  *
 501  *    char *silc_string_regexify(const char *string);
 502  *
 503  * DESCRIPTION
 504  *
 505  *    Inspects the `string' for wildcards and returns regex string that can
 506  *    be used by the GNU regex library. A comma (`,') in the `string' means
 507  *    that the string is list.
 508  *
 509  *    This function is system dependant.
 510  *
 511  ***/
 512 char *silc_string_regexify(const char *string);
 513
 514 /****f* silcutil/SilcUtilAPI/silc_string_regex_match
 515  *
 516  * SYNOPSIS
 517  *
 518  *    int silc_string_regex_match(const char *regex, const char *string);
 519  *
 520  * DESCRIPTION
 521  *
 522  *    Matches the two strings and returns TRUE if the strings match.
 523  *
 524  *    This function is system dependant.
 525  *
 526  ***/
 527 int silc_string_regex_match(const char *regex, const char *string);
 528
 529 /****f* silcutil/SilcUtilAPI/silc_string_match
 530  *
 531  * SYNOPSIS
 532  *
 533  *    int silc_string_match(const char *string1, const char *string2);
 534  *
 535  * DESCRIPTION
 536  *
 537  *    Do regex match to the two strings `string1' and `string2'. If the
 538  *    `string2' matches the `string1' this returns TRUE.
 539  *
 540  *    This function is system dependant.
 541  *
 542  ***/
 543 int silc_string_match(const char *string1, const char *string2);
 544
 545 /****f* silcutil/SilcUtilAPI/silc_get_username
 546  *
 547  * SYNOPSIS
 548  *
 549  *    char *silc_get_username();
 550  *
 551  * DESCRIPTION
 552  *
 553  *    Returns the username of the user. If the global variable LOGNAME
 554  *    does not exists we will get the name from the passwd file.  The
 555  *    caller must free the returned name.
 556  *
 557  *    This function is system dependant.
 558  *
 559  ***/
 560 char *silc_get_username();
 561
 562 /****f* silcutil/SilcUtilAPI/silc_get_real_name
 563  *
 564  * SYNOPSIS
 565  *
 566  *    char *silc_get_real_name();
 567  *
 568  * DESCRIPTION
 569  *
 570  *    Returns the real name of ther user from the passwd file.  The
 571  *    caller must free the returned name.
 572  *
 573  *    This function is system dependant.
 574  *
 575  ***/
 576 char *silc_get_real_name();
 577
 578 /****f* silcutil/SilcUtilAPI/silc_get_mode_list
 579  *
 580  * SYNOPSIS
 581  *
 582  *    bool silc_get_mode_list(SilcBuffer mode_list, SilcUInt32 mode_list_count,
 583  *                            SilcUInt32 **list);
 584  *
 585  * DESCRIPTION
 586  *
 587  *    Returns modes from list of 32 bit MSB first order values that are
 588  *    encoded one after the other in the `mode_list' into the `list'
 589  *    array.  The caller must free the returned list.  Return FALSE if
 590  *    there is error parsing the list.
 591  *
 592  ***/
 593 bool silc_get_mode_list(SilcBuffer mode_list, SilcUInt32 mode_list_count,
 594                         SilcUInt32 **list);
 595
 596 /****f* silcutil/SilcUtilAPI/silc_get_status_message
 597  *
 598  * SYNOPSIS
 599  *
 600  *    char *silc_get_status_message(SilcStatus status)
 601  *
 602  * DESCRIPTION
 603  *
 604  *    Returns status message string
 605  *
 606  ***/
 607 const char *silc_get_status_message(unsigned char status);
 608
 609 /****f* silcutil/SilcUtilAPI/silc_get_packet_name
 610  *
 611  * SYNOPSIS
 612  *
 613  *    char *silc_get_packet_name(SilcPacketType type);
 614  *
 615  * DESCRIPTION
 616  *
 617  *    Returns the name corresponding packet type `type'.
 618  *
 619  ***/
 620 const char *silc_get_packet_name(unsigned char type);
 621
 622 /****f* silcutil/SilcUtilAPI/silc_get_command_name
 623  *
 624  * SYNOPSIS
 625  *
 626  *    char *silc_get_command_name(SilcCommand command);
 627  *
 628  * DESCRIPTION
 629  *
 630  *    Returns the name corresponding SILC command `command'.
 631  *
 632  ***/
 633 const char *silc_get_command_name(unsigned char command);
 634
 635 #endif  /* !SILCUTIL_H */