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