lib/silcutil/silcutil.h

   1 /*
   2
   3   silcutil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2006 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_to_upper
  63  *
  64  * SYNOPSIS
  65  *
  66  *    SilcBool silc_to_upper(const char *string, char *dest,
  67  *                           SilcUInt32 dest_size);
  68  *
  69  * DESCRIPTION
  70  *
  71  *    Converts string to capital characters.
  72  *
  73  ***/
  74 SilcBool silc_to_upper(const char *string, char *dest, SilcUInt32 dest_size);
  75
  76 /****f* silcutil/SilcUtilAPI/silc_to_lower
  77  *
  78  * SYNOPSIS
  79  *
  80  *    SilcBool silc_to_lower(const char *string, char *dest,
  81  *                           SilcUInt32 dest_size);
  82  *
  83  * DESCRIPTION
  84  *
  85  *    Converts string to capital characters.
  86  *
  87  ***/
  88 SilcBool silc_to_lower(const char *string, char *dest, SilcUInt32 dest_size);
  89
  90 /****f* silcutil/SilcUtilAPI/silc_parse_userfqdn
  91  *
  92  * SYNOPSIS
  93  *
  94  *    int silc_parse_userfqdn(const char *string,
  95  *                            char *user, SilcUInt32 user_size,
  96  *                            char *fqdn, SilcUInt32 fqdn_size);
  97  *
  98  * DESCRIPTION
  99  *
 100  *    Parse userfqdn string which is in user@fqdn format.  Returns 0 on
 101  *    error, 1 if `user' was filled and 2 if both `user' and `fqdn'
 102  *    was filled.
 103  *
 104  ***/
 105 int silc_parse_userfqdn(const char *string,
 106                         char *user, SilcUInt32 user_size,
 107                         char *fqdn, SilcUInt32 fqdn_size);
 108
 109 /****f* silcutil/SilcUtilAPI/silc_parse_command_line
 110  *
 111  * SYNOPSIS
 112  *
 113  *    void silc_parse_command_line(unsigned char *buffer,
 114  *                                 unsigned char ***parsed,
 115  *                                 SilcUInt32 **parsed_lens,
 116  *                                 SilcUInt32 **parsed_types,
 117  *                                 SilcUInt32 *parsed_num,
 118  *                                 SilcUInt32 max_args);
 119  *
 120  * DESCRIPTION
 121  *
 122  *    Parses command line. At most `max_args' is taken. Rest of the line
 123  *    will be allocated as the last argument if there are more than `max_args'
 124  *    arguments in the line. Note that the command name is counted as one
 125  *    argument and is saved.
 126  *
 127  ***/
 128 void silc_parse_command_line(unsigned char *buffer,
 129                              unsigned char ***parsed,
 130                              SilcUInt32 **parsed_lens,
 131                              SilcUInt32 **parsed_types,
 132                              SilcUInt32 *parsed_num,
 133                              SilcUInt32 max_args);
 134
 135 /****f* silcutil/SilcUtilAPI/silc_format
 136  *
 137  * SYNOPSIS
 138  *
 139  *    char *silc_format(char *fmt, ...);
 140  *
 141  * DESCRIPTION
 142  *
 143  *    Formats arguments to a string and returns it after allocating memory
 144  *    for it. It must be remembered to free it later.
 145  *
 146  ***/
 147 char *silc_format(char *fmt, ...);
 148
 149 /****f* silcutil/SilcUtilAPI/silc_hash_string
 150  *
 151  * SYNOPSIS
 152  *
 153  *    SilcUInt32 silc_hash_string(void *key, void *user_context);
 154  *
 155  * DESCRIPTION
 156  *
 157  *    Basic has function to hash strings. May be used with the SilcHashTable.
 158  *    Note that this lowers the characters of the string (with tolower()) so
 159  *    this is used usually with nicknames, channel and server names to provide
 160  *    case insensitive keys.
 161  *
 162  ***/
 163 SilcUInt32 silc_hash_string(void *key, void *user_context);
 164
 165 /****f* silcutil/SilcUtilAPI/silc_hash_utf8_string
 166  *
 167  * SYNOPSIS
 168  *
 169  *    SilcUInt32 silc_hash_utf8_string(void *key, void *user_context);
 170  *
 171  * DESCRIPTION
 172  *
 173  *    Basic has function to hash UTF-8 strings. May be used with the
 174  *    SilcHashTable.  Used with identifier strings.  The key is
 175  *    expected to be casefolded.
 176  *
 177  ***/
 178 SilcUInt32 silc_hash_utf8_string(void *key, void *user_context);
 179
 180 /****f* silcutil/SilcUtilAPI/silc_hash_uint
 181  *
 182  * SYNOPSIS
 183  *
 184  *    SilcUInt32 silc_hash_uint(void *key, void *user_context);
 185  *
 186  * DESCRIPTION
 187  *
 188  *    Basic hash function to hash integers. May be used with the SilcHashTable.
 189  *
 190  ***/
 191 SilcUInt32 silc_hash_uint(void *key, void *user_context);
 192
 193 /****f* silcutil/SilcUtilAPI/silc_hash_ptr
 194  *
 195  * SYNOPSIS
 196  *
 197  *    SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 198  *
 199  * DESCRIPTION
 200  *
 201  *    Basic hash funtion to hash pointers. May be used with the SilcHashTable.
 202  *
 203  ***/
 204 SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 205
 206 /****f* silcutil/SilcUtilAPI/silc_hash_id
 207  *
 208  * SYNOPSIS
 209  *
 210  *    SilcUInt32 silc_hash_id(void *key, void *user_context);
 211  *
 212  * DESCRIPTION
 213  *
 214  *    Hash a ID. The `user_context' is the ID type.
 215  *
 216  ***/
 217 SilcUInt32 silc_hash_id(void *key, void *user_context);
 218
 219 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_hash
 220  *
 221  * SYNOPSIS
 222  *
 223  *    SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context)
 224  *
 225  * DESCRIPTION
 226  *
 227  *    Hash Client ID's hash.
 228  *
 229  ***/
 230 SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context);
 231
 232 /****f* silcutil/SilcUtilAPI/silc_hash_data
 233  *
 234  * SYNOPSIS
 235  *
 236  *    SilcUInt32 silc_hash_data(void *key, void *user_context);
 237  *
 238  * DESCRIPTION
 239  *
 240  *    Hash binary data. The `user_context' is the data length.
 241  *
 242  ***/
 243 SilcUInt32 silc_hash_data(void *key, void *user_context);
 244
 245 /****f* silcutil/SilcUtilAPI/silc_hash_public_key
 246  *
 247  * SYNOPSIS
 248  *
 249  *    SilcUInt32 silc_hash_public_key(void *key, void *user_context);
 250  *
 251  * DESCRIPTION
 252  *
 253  *    Hash public key of any type.
 254  *
 255  ***/
 256 SilcUInt32 silc_hash_public_key(void *key, void *user_context);
 257
 258 /****f* silcutil/SilcUtilAPI/silc_hash_string_compare
 259  *
 260  * SYNOPSIS
 261  *
 262  *    SilcBool silc_hash_string_compare(void *key1, void *key2,
 263  *                                  void *user_context);
 264  *
 265  * DESCRIPTION
 266  *
 267  *    Compares two strings. It may be used as SilcHashTable comparison
 268  *    function.
 269  *
 270  ***/
 271 SilcBool silc_hash_string_compare(void *key1, void *key2, void *user_context);
 272
 273 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare
 274  *
 275  * SYNOPSIS
 276  *
 277  *    SilcBool silc_hash_id_compare(void *key1, void *key2,
 278  *                                  void *user_context);
 279  *
 280  * DESCRIPTION
 281  *
 282  *    Compares two ID's. May be used as SilcHashTable comparison function.
 283  *    The Client ID's compares only the hash of the Client ID not any other
 284  *    part of the Client ID. Other ID's are fully compared.
 285  *
 286  ***/
 287 SilcBool silc_hash_id_compare(void *key1, void *key2, void *user_context);
 288
 289 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare_full
 290  *
 291  * SYNOPSIS
 292  *
 293  *    SilcBool silc_hash_id_compare_full(void *key1, void *key2,
 294  *                                       void *user_context)
 295  *
 296  * DESCRIPTION
 297  *
 298  *    Compares two ID's. May be used as SilcHashTable comparison function.
 299  *    To compare full ID's instead of only partial, like the
 300  *    silc_hash_id_compare does, use this function.
 301  *
 302  ***/
 303 SilcBool silc_hash_id_compare_full(void *key1, void *key2, void *user_context);
 304
 305 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_compare
 306  *
 307  * SYNOPSIS
 308  *
 309  *    SilcBool silc_hash_client_id_compare(void *key1, void *key2,
 310  *                                         void *user_context);
 311  *
 312  * DESCRIPTION
 313  *
 314  *    Compare two Client ID's entirely and not just the hash from the ID.
 315  *
 316  ***/
 317 SilcBool silc_hash_client_id_compare(void *key1, void *key2,
 318                                      void *user_context);
 319
 320 /****f* silcutil/SilcUtilAPI/silc_hash_data_compare
 321  *
 322  * SYNOPSIS
 323  *
 324  *    SilcBool silc_hash_data_compare(void *key1, void *key2,
 325  *                                    void *user_context);
 326  *
 327  * DESCRIPTION
 328  *
 329  *    Compares binary data. May be used as SilcHashTable comparison function.
 330  *
 331  ***/
 332 SilcBool silc_hash_data_compare(void *key1, void *key2, void *user_context);
 333
 334 /****f* silcutil/SilcUtilAPI/silc_hash_utf8_compare
 335  *
 336  * SYNOPSIS
 337  *
 338  *    SilcBool silc_hash_utf8_compare(void *key1, void *key2,
 339  *                                    void *user_context);
 340  *
 341  * DESCRIPTION
 342  *
 343  *    Compares UTF-8 strings.  Casefolded and NULL terminated strings are
 344  *    expected.  May be used as SilcHashTable comparison function.
 345  *
 346  ***/
 347 SilcBool silc_hash_utf8_compare(void *key1, void *key2, void *user_context);
 348
 349 /****f* silcutil/SilcUtilAPI/silc_hash_public_key_compare
 350  *
 351  * SYNOPSIS
 352  *
 353  *    SilcBool silc_hash_public_key_compare(void *key1, void *key2,
 354  *                                          void *user_context);
 355  *
 356  * DESCRIPTION
 357  *
 358  *    Compares two SILC Public keys. It may be used as SilcHashTable
 359  *    comparison function.
 360  *
 361  ***/
 362 SilcBool silc_hash_public_key_compare(void *key1, void *key2,
 363                                       void *user_context);
 364
 365 /****f* silcutil/SilcUtilAPI/silc_fingerprint
 366  *
 367  * SYNOPSIS
 368  *
 369  *    char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 370  *
 371  * DESCRIPTION
 372  *
 373  *    Return a textual representation of the fingerprint in *data, the
 374  *    caller must free the returned string.
 375  *
 376  ***/
 377 char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 378
 379 /****f* silcutil/SilcUtilAPI/silc_string_is_ascii
 380  *
 381  * SYNOPSIS
 382  *
 383  *    SilcBool silc_string_is_ascii(const unsigned char *data,
 384  *                              SilcUInt32 data_len);
 385  *
 386  * DESCRIPTION
 387  *
 388  *    Return TRUE if the `data' is ASCII string.
 389  *
 390  ***/
 391 SilcBool silc_string_is_ascii(const unsigned char *data, SilcUInt32 data_len);
 392
 393 /****f* silcutil/SilcUtilAPI/silc_get_input
 394  *
 395  * SYNOPSIS
 396  *
 397  *    char *silc_get_input(const char *prompt, SilcBool echo_off);
 398  *
 399  * DESCRIPTION
 400  *
 401  *    Displays input prompt on command line and takes input data from user.
 402  *
 403  ***/
 404 char *silc_get_input(const char *prompt, SilcBool echo_off);
 405
 406 /* System dependant prototypes */
 407
 408 /****f* silcutil/SilcUtilAPI/silc_get_username
 409  *
 410  * SYNOPSIS
 411  *
 412  *    char *silc_get_username();
 413  *
 414  * DESCRIPTION
 415  *
 416  *    Returns the username of the user. If the global variable LOGNAME
 417  *    does not exists we will get the name from the passwd file.  The
 418  *    caller must free the returned name.
 419  *
 420  *    This function is system dependant.
 421  *
 422  ***/
 423 char *silc_get_username();
 424
 425 /****f* silcutil/SilcUtilAPI/silc_get_real_name
 426  *
 427  * SYNOPSIS
 428  *
 429  *    char *silc_get_real_name();
 430  *
 431  * DESCRIPTION
 432  *
 433  *    Returns the real name of ther user from the passwd file.  The
 434  *    caller must free the returned name.
 435  *
 436  *    This function is system dependant.
 437  *
 438  ***/
 439 char *silc_get_real_name();
 440
 441 /****f* silcutil/SilcUtilAPI/silc_va_copy
 442  *
 443  * SYNOPSIS
 444  *
 445  *    void silc_va_copy(va_list dest, va_list src);
 446  *
 447  * DESCRIPTION
 448  *
 449  *    Copies variable argument list.  This must be called in case the
 450  *    variable argument list must be evaluated multiple times.  For each
 451  *    evaluation the list must be copied and va_end must be called for
 452  *    each copied list.
 453  *
 454  ***/
 455 #if defined(HAVE_VA_COPY)
 456 #define silc_va_copy(dest, src) va_copy(dest, src);
 457 #elif defined(HAVE___VA_COPY)
 458 #define silc_va_copy(dest, src) __va_copy(dest, src);
 459 #elif defined(SILC_VA_COPY_ARRAY)
 460 #define silc_va_copy(dest, src) memmove(dest, src, sizeof(va_list));
 461 #else
 462 #define silc_va_copy(dest, src) dest = src;
 463 #endif
 464
 465 #endif  /* !SILCUTIL_H */