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  *    Creates fingerprint from data, usually used with SHA1 digests.
 397  *
 398  ***/
 399 char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 400
 401 /****f* silcutil/SilcUtilAPI/silc_string_is_ascii
 402  *
 403  * SYNOPSIS
 404  *
 405  *    bool silc_string_is_ascii(const unsigned char *data,
 406  *                              SilcUInt32 data_len);
 407  *
 408  * DESCRIPTION
 409  *
 410  *    Return TRUE if the `data' is ASCII string.
 411  *
 412  ***/
 413 bool silc_string_is_ascii(const unsigned char *data, SilcUInt32 data_len);
 414
 415 /****f* silcutil/SilcUtilAPI/silc_parse_version_string
 416  *
 417  * SYNOPSIS
 418  *
 419  *    bool silc_parse_version_string(const char *version,
 420  *                                   SilcUInt32 *protocol_version,
 421  *                                   char **protocol_version_string,
 422  *                                   SilcUInt32 *software_version,
 423  *                                   char **software_version_string,
 424  *                                   char **vendor_version);
 425  *
 426  * DESCRIPTION
 427  *
 428  *    Parses SILC protocol style version string.
 429  *
 430  ***/
 431 bool silc_parse_version_string(const char *version,
 432                                SilcUInt32 *protocol_version,
 433                                char **protocol_version_string,
 434                                SilcUInt32 *software_version,
 435                                char **software_version_string,
 436                                char **vendor_version);
 437
 438 /****f* silcutil/SilcUtilAPI/silc_version_to_num
 439  *
 440  * SYNOPSIS
 441  *
 442  *    SilcUInt32 silc_version_to_num(const char *version);
 443  *
 444  * DESCRIPTION
 445  *
 446  *    Converts version string x.x into number representation.
 447  *
 448  ***/
 449 SilcUInt32 silc_version_to_num(const char *version);
 450
 451 /****f* silcutil/SilcUtilAPI/silc_get_input
 452  *
 453  * SYNOPSIS
 454  *
 455  *    char *silc_get_input(const char *prompt, bool echo_off);
 456  *
 457  * DESCRIPTION
 458  *
 459  *    Displays input prompt on command line and takes input data from user.
 460  *
 461  ***/
 462 char *silc_get_input(const char *prompt, bool echo_off);
 463
 464 /* System dependant prototypes */
 465
 466 /****f* silcutil/SilcUtilAPI/silc_gettimeofday
 467  *
 468  * SYNOPSIS
 469  *
 470  *    int silc_gettimeofday(struct timeval *p);
 471  *
 472  * DESCRIPTION
 473  *
 474  *    Return current time to struct timeval.  This function is system
 475  *    dependant.  Returns 0 on success and -1 on error.
 476  *
 477  ***/
 478 int silc_gettimeofday(struct timeval *p);
 479
 480 /****f* silcutil/SilcUtilAPI/silc_compare_timeval
 481  *
 482  * SYNOPSIS
 483  *
 484  *    bool silc_compare_timeval(struct timeval *smaller,
 485  *                              struct timeval *bigger)
 486  *
 487  * DESCRIPTION
 488  *
 489  *    Compare two timeval structures and return TRUE if the first
 490  *    time value is smaller than the second time value.
 491  *
 492  ***/
 493 bool silc_compare_timeval(struct timeval *smaller,
 494                           struct timeval *bigger);
 495
 496 /****f* silcutil/SilcUtilAPI/silc_string_regexify
 497  *
 498  * SYNOPSIS
 499  *
 500  *    char *silc_string_regexify(const char *string);
 501  *
 502  * DESCRIPTION
 503  *
 504  *    Inspects the `string' for wildcards and returns regex string that can
 505  *    be used by the GNU regex library. A comma (`,') in the `string' means
 506  *    that the string is list.
 507  *
 508  *    This function is system dependant.
 509  *
 510  ***/
 511 char *silc_string_regexify(const char *string);
 512
 513 /****f* silcutil/SilcUtilAPI/silc_string_regex_match
 514  *
 515  * SYNOPSIS
 516  *
 517  *    int silc_string_regex_match(const char *regex, const char *string);
 518  *
 519  * DESCRIPTION
 520  *
 521  *    Matches the two strings and returns TRUE if the strings match.
 522  *
 523  *    This function is system dependant.
 524  *
 525  ***/
 526 int silc_string_regex_match(const char *regex, const char *string);
 527
 528 /****f* silcutil/SilcUtilAPI/silc_string_match
 529  *
 530  * SYNOPSIS
 531  *
 532  *    int silc_string_match(const char *string1, const char *string2);
 533  *
 534  * DESCRIPTION
 535  *
 536  *    Do regex match to the two strings `string1' and `string2'. If the
 537  *    `string2' matches the `string1' this returns TRUE.
 538  *
 539  *    This function is system dependant.
 540  *
 541  ***/
 542 int silc_string_match(const char *string1, const char *string2);
 543
 544 /****f* silcutil/SilcUtilAPI/silc_get_username
 545  *
 546  * SYNOPSIS
 547  *
 548  *    char *silc_get_username();
 549  *
 550  * DESCRIPTION
 551  *
 552  *    Returns the username of the user. If the global variable LOGNAME
 553  *    does not exists we will get the name from the passwd file.  The
 554  *    caller must free the returned name.
 555  *
 556  *    This function is system dependant.
 557  *
 558  ***/
 559 char *silc_get_username();
 560
 561 /****f* silcutil/SilcUtilAPI/silc_get_real_name
 562  *
 563  * SYNOPSIS
 564  *
 565  *    char *silc_get_real_name();
 566  *
 567  * DESCRIPTION
 568  *
 569  *    Returns the real name of ther user from the passwd file.  The
 570  *    caller must free the returned name.
 571  *
 572  *    This function is system dependant.
 573  *
 574  ***/
 575 char *silc_get_real_name();
 576
 577 /****f* silcutil/SilcUtilAPI/silc_get_mode_list
 578  *
 579  * SYNOPSIS
 580  *
 581  *    bool silc_get_mode_list(SilcBuffer mode_list, SilcUInt32 mode_list_count,
 582  *                            SilcUInt32 **list);
 583  *
 584  * DESCRIPTION
 585  *
 586  *    Returns modes from list of 32 bit MSB first order values that are
 587  *    encoded one after the other in the `mode_list' into the `list'
 588  *    array.  The caller must free the returned list.  Return FALSE if
 589  *    there is error parsing the list.
 590  *
 591  ***/
 592 bool silc_get_mode_list(SilcBuffer mode_list, SilcUInt32 mode_list_count,
 593                         SilcUInt32 **list);
 594
 595 /****f* silcutil/SilcUtilAPI/silc_get_status_message
 596  *
 597  * SYNOPSIS
 598  *
 599  *    char *silc_get_status_message(SilcStatus status)
 600  *
 601  * DESCRIPTION
 602  *
 603  *    Returns status message string
 604  *
 605  ***/
 606 const char *silc_get_status_message(unsigned char status);
 607
 608 /****f* silcutil/SilcUtilAPI/silc_get_packet_name
 609  *
 610  * SYNOPSIS
 611  *
 612  *    char *silc_get_packet_name(SilcPacketType type);
 613  *
 614  * DESCRIPTION
 615  *
 616  *    Returns the name corresponding packet type `type'.
 617  *
 618  ***/
 619 const char *silc_get_packet_name(unsigned char type);
 620
 621 /****f* silcutil/SilcUtilAPI/silc_get_command_name
 622  *
 623  * SYNOPSIS
 624  *
 625  *    char *silc_get_command_name(SilcCommand command);
 626  *
 627  * DESCRIPTION
 628  *
 629  *    Returns the name corresponding SILC command `command'.
 630  *
 631  ***/
 632 const char *silc_get_command_name(unsigned char command);
 633
 634 #endif  /* !SILCUTIL_H */