lib/silcutil/silcutil.h

   1 /*
   2
   3   silcutil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2007 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 can be used to provide case-insensitive hashing.
 160  *
 161  ***/
 162 SilcUInt32 silc_hash_string(void *key, void *user_context);
 163
 164 /****f* silcutil/SilcUtilAPI/silc_hash_utf8_string
 165  *
 166  * SYNOPSIS
 167  *
 168  *    SilcUInt32 silc_hash_utf8_string(void *key, void *user_context);
 169  *
 170  * DESCRIPTION
 171  *
 172  *    Basic has function to hash UTF-8 strings. May be used with the
 173  *    SilcHashTable.  Used with identifier strings.  The key is
 174  *    expected to be casefolded.
 175  *
 176  ***/
 177 SilcUInt32 silc_hash_utf8_string(void *key, void *user_context);
 178
 179 /****f* silcutil/SilcUtilAPI/silc_hash_uint
 180  *
 181  * SYNOPSIS
 182  *
 183  *    SilcUInt32 silc_hash_uint(void *key, void *user_context);
 184  *
 185  * DESCRIPTION
 186  *
 187  *    Basic hash function to hash integers. May be used with the SilcHashTable.
 188  *
 189  ***/
 190 SilcUInt32 silc_hash_uint(void *key, void *user_context);
 191
 192 /****f* silcutil/SilcUtilAPI/silc_hash_ptr
 193  *
 194  * SYNOPSIS
 195  *
 196  *    SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 197  *
 198  * DESCRIPTION
 199  *
 200  *    Basic hash funtion to hash pointers. May be used with the SilcHashTable.
 201  *
 202  ***/
 203 SilcUInt32 silc_hash_ptr(void *key, void *user_context);
 204
 205 /****f* silcutil/SilcUtilAPI/silc_hash_id
 206  *
 207  * SYNOPSIS
 208  *
 209  *    SilcUInt32 silc_hash_id(void *key, void *user_context);
 210  *
 211  * DESCRIPTION
 212  *
 213  *    Hash a ID. The `user_context' is the ID type.
 214  *
 215  ***/
 216 SilcUInt32 silc_hash_id(void *key, void *user_context);
 217
 218 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_hash
 219  *
 220  * SYNOPSIS
 221  *
 222  *    SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context)
 223  *
 224  * DESCRIPTION
 225  *
 226  *    Hash Client ID's hash.
 227  *
 228  ***/
 229 SilcUInt32 silc_hash_client_id_hash(void *key, void *user_context);
 230
 231 /****f* silcutil/SilcUtilAPI/silc_hash_data
 232  *
 233  * SYNOPSIS
 234  *
 235  *    SilcUInt32 silc_hash_data(void *key, void *user_context);
 236  *
 237  * DESCRIPTION
 238  *
 239  *    Hash binary data. The `user_context' is the data length.
 240  *
 241  ***/
 242 SilcUInt32 silc_hash_data(void *key, void *user_context);
 243
 244 /****f* silcutil/SilcUtilAPI/silc_hash_string_compare
 245  *
 246  * SYNOPSIS
 247  *
 248  *    SilcBool silc_hash_string_compare(void *key1, void *key2,
 249  *                                  void *user_context);
 250  *
 251  * DESCRIPTION
 252  *
 253  *    Compares two strings. This ignores the case while comparing.  It may
 254  *    be used as SilcHashTable comparison function.
 255  *
 256  ***/
 257 SilcBool silc_hash_string_compare(void *key1, void *key2, void *user_context);
 258
 259 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare
 260  *
 261  * SYNOPSIS
 262  *
 263  *    SilcBool silc_hash_id_compare(void *key1, void *key2,
 264  *                                  void *user_context);
 265  *
 266  * DESCRIPTION
 267  *
 268  *    Compares two ID's. May be used as SilcHashTable comparison function.
 269  *    The Client ID's compares only the hash of the Client ID not any other
 270  *    part of the Client ID. Other ID's are fully compared.
 271  *
 272  ***/
 273 SilcBool silc_hash_id_compare(void *key1, void *key2, void *user_context);
 274
 275 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare_full
 276  *
 277  * SYNOPSIS
 278  *
 279  *    SilcBool silc_hash_id_compare_full(void *key1, void *key2,
 280  *                                       void *user_context)
 281  *
 282  * DESCRIPTION
 283  *
 284  *    Compares two ID's. May be used as SilcHashTable comparison function.
 285  *    To compare full ID's instead of only partial, like the
 286  *    silc_hash_id_compare does, use this function.
 287  *
 288  ***/
 289 SilcBool silc_hash_id_compare_full(void *key1, void *key2, void *user_context);
 290
 291 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_compare
 292  *
 293  * SYNOPSIS
 294  *
 295  *    SilcBool silc_hash_client_id_compare(void *key1, void *key2,
 296  *                                         void *user_context);
 297  *
 298  * DESCRIPTION
 299  *
 300  *    Compare two Client ID's entirely and not just the hash from the ID.
 301  *
 302  ***/
 303 SilcBool silc_hash_client_id_compare(void *key1, void *key2,
 304                                      void *user_context);
 305
 306 /****f* silcutil/SilcUtilAPI/silc_hash_data_compare
 307  *
 308  * SYNOPSIS
 309  *
 310  *    SilcBool silc_hash_data_compare(void *key1, void *key2,
 311  *                                    void *user_context);
 312  *
 313  * DESCRIPTION
 314  *
 315  *    Compares binary data. May be used as SilcHashTable comparison function.
 316  *
 317  ***/
 318 SilcBool silc_hash_data_compare(void *key1, void *key2, void *user_context);
 319
 320 /****f* silcutil/SilcUtilAPI/silc_hash_utf8_compare
 321  *
 322  * SYNOPSIS
 323  *
 324  *    SilcBool silc_hash_utf8_compare(void *key1, void *key2,
 325  *                                    void *user_context);
 326  *
 327  * DESCRIPTION
 328  *
 329  *    Compares UTF-8 strings.  Casefolded and NULL terminated strings are
 330  *    expected.  May be used as SilcHashTable comparison function.
 331  *
 332  ***/
 333 SilcBool silc_hash_utf8_compare(void *key1, void *key2, void *user_context);
 334
 335 /****f* silcutil/SilcUtilAPI/silc_fingerprint
 336  *
 337  * SYNOPSIS
 338  *
 339  *    char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 340  *
 341  * DESCRIPTION
 342  *
 343  *    Return a textual representation of the fingerprint in *data, the
 344  *    caller must free the returned string.
 345  *
 346  ***/
 347 char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 348
 349 /****f* silcutil/SilcUtilAPI/silc_string_is_ascii
 350  *
 351  * SYNOPSIS
 352  *
 353  *    SilcBool silc_string_is_ascii(const unsigned char *data,
 354  *                              SilcUInt32 data_len);
 355  *
 356  * DESCRIPTION
 357  *
 358  *    Return TRUE if the `data' is ASCII string.
 359  *
 360  ***/
 361 SilcBool silc_string_is_ascii(const unsigned char *data, SilcUInt32 data_len);
 362
 363 /****f* silcutil/SilcUtilAPI/silc_get_input
 364  *
 365  * SYNOPSIS
 366  *
 367  *    char *silc_get_input(const char *prompt, SilcBool echo_off);
 368  *
 369  * DESCRIPTION
 370  *
 371  *    Displays input prompt on command line and takes input data from user.
 372  *
 373  ***/
 374 char *silc_get_input(const char *prompt, SilcBool echo_off);
 375
 376 /* System dependant prototypes */
 377
 378 /****f* silcutil/SilcUtilAPI/silc_get_username
 379  *
 380  * SYNOPSIS
 381  *
 382  *    char *silc_get_username();
 383  *
 384  * DESCRIPTION
 385  *
 386  *    Returns the username of the user. If the global variable LOGNAME
 387  *    does not exists we will get the name from the passwd file.  The
 388  *    caller must free the returned name.
 389  *
 390  *    This function is system dependant.
 391  *
 392  ***/
 393 char *silc_get_username();
 394
 395 /****f* silcutil/SilcUtilAPI/silc_get_real_name
 396  *
 397  * SYNOPSIS
 398  *
 399  *    char *silc_get_real_name();
 400  *
 401  * DESCRIPTION
 402  *
 403  *    Returns the real name of ther user from the passwd file.  The
 404  *    caller must free the returned name.
 405  *
 406  *    This function is system dependant.
 407  *
 408  ***/
 409 char *silc_get_real_name();
 410
 411 /****f* silcutil/SilcUtilAPI/silc_va_copy
 412  *
 413  * SYNOPSIS
 414  *
 415  *    void silc_va_copy(va_list dest, va_list src);
 416  *
 417  * DESCRIPTION
 418  *
 419  *    Copies variable argument list.  This must be called in case the
 420  *    variable argument list must be evaluated multiple times.  For each
 421  *    evaluation the list must be copied and va_end must be called for
 422  *    each copied list.
 423  *
 424  ***/
 425 #if defined(HAVE_VA_COPY)
 426 #define silc_va_copy(dest, src) va_copy(dest, src);
 427 #elif defined(HAVE___VA_COPY)
 428 #define silc_va_copy(dest, src) __va_copy(dest, src);
 429 #elif defined(SILC_VA_COPY_ARRAY)
 430 #define silc_va_copy(dest, src) memmove(dest, src, sizeof(va_list));
 431 #else
 432 #define silc_va_copy(dest, src) dest = src;
 433 #endif
 434
 435 /****f* silcutil/SilcUtilAPI/silc_hexdump
 436  *
 437  * SYNOPSIS
 438  *
 439  *    void silc_hexdump(const unsigned char *data, SilcUInt32 data_len,
 440  *                      FILE *output);
 441  *
 442  * DESCRIPTION
 443  *
 444  *    Dumps the `data' of length of `data_len' bytes as HEX.  The `output'
 445  *    file specifies the destination.
 446  *
 447  ***/
 448 void silc_hexdump(const unsigned char *data, SilcUInt32 data_len,
 449                   FILE *output);
 450
 451 /****f* silcutil/SilcUtilAPI/silc_hex2data
 452  *
 453  * SYNOPSIS
 454  *
 455  *    SilcBool silc_hex2data(const char *hex, unsigned char *data,
 456  *                           SilcUInt32 data_size, SilcUInt32 *ret_data_len);
 457  *
 458  * DESCRIPTION
 459  *
 460  *    Converts HEX character string to binary data.  Each HEX numbers must
 461  *    have two characters in the `hex' string.
 462  *
 463  ***/
 464 SilcBool silc_hex2data(const char *hex, unsigned char *data,
 465                        SilcUInt32 data_size, SilcUInt32 *ret_data_len);
 466
 467 /****f* silcutil/SilcUtilAPI/silc_data2hex
 468  *
 469  * SYNOPSIS
 470  *
 471  *    SilcBool silc_data2hex(const unsigned char *data, SilcUInt32 data_len,
 472  *                           char *hex, SilcUInt32 hex_size);
 473  *
 474  * DESCRIPTION
 475  *
 476  *    Converts binary data to HEX string.  This NULL terminates the `hex'
 477  *    buffer automatically.
 478  *
 479  ***/
 480 SilcBool silc_data2hex(const unsigned char *data, SilcUInt32 data_len,
 481                        char *hex, SilcUInt32 hex_size);
 482
 483 #endif  /* !SILCUTIL_H */