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