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 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_string_compare
 246  *
 247  * SYNOPSIS
 248  *
 249  *    SilcBool silc_hash_string_compare(void *key1, void *key2,
 250  *                                  void *user_context);
 251  *
 252  * DESCRIPTION
 253  *
 254  *    Compares two strings. It may be used as SilcHashTable comparison
 255  *    function.
 256  *
 257  ***/
 258 SilcBool silc_hash_string_compare(void *key1, void *key2, void *user_context);
 259
 260 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare
 261  *
 262  * SYNOPSIS
 263  *
 264  *    SilcBool silc_hash_id_compare(void *key1, void *key2,
 265  *                                  void *user_context);
 266  *
 267  * DESCRIPTION
 268  *
 269  *    Compares two ID's. May be used as SilcHashTable comparison function.
 270  *    The Client ID's compares only the hash of the Client ID not any other
 271  *    part of the Client ID. Other ID's are fully compared.
 272  *
 273  ***/
 274 SilcBool silc_hash_id_compare(void *key1, void *key2, void *user_context);
 275
 276 /****f* silcutil/SilcUtilAPI/silc_hash_id_compare_full
 277  *
 278  * SYNOPSIS
 279  *
 280  *    SilcBool silc_hash_id_compare_full(void *key1, void *key2,
 281  *                                       void *user_context)
 282  *
 283  * DESCRIPTION
 284  *
 285  *    Compares two ID's. May be used as SilcHashTable comparison function.
 286  *    To compare full ID's instead of only partial, like the
 287  *    silc_hash_id_compare does, use this function.
 288  *
 289  ***/
 290 SilcBool silc_hash_id_compare_full(void *key1, void *key2, void *user_context);
 291
 292 /****f* silcutil/SilcUtilAPI/silc_hash_client_id_compare
 293  *
 294  * SYNOPSIS
 295  *
 296  *    SilcBool silc_hash_client_id_compare(void *key1, void *key2,
 297  *                                         void *user_context);
 298  *
 299  * DESCRIPTION
 300  *
 301  *    Compare two Client ID's entirely and not just the hash from the ID.
 302  *
 303  ***/
 304 SilcBool silc_hash_client_id_compare(void *key1, void *key2,
 305                                      void *user_context);
 306
 307 /****f* silcutil/SilcUtilAPI/silc_hash_data_compare
 308  *
 309  * SYNOPSIS
 310  *
 311  *    SilcBool silc_hash_data_compare(void *key1, void *key2,
 312  *                                    void *user_context);
 313  *
 314  * DESCRIPTION
 315  *
 316  *    Compares binary data. May be used as SilcHashTable comparison function.
 317  *
 318  ***/
 319 SilcBool silc_hash_data_compare(void *key1, void *key2, void *user_context);
 320
 321 /****f* silcutil/SilcUtilAPI/silc_hash_utf8_compare
 322  *
 323  * SYNOPSIS
 324  *
 325  *    SilcBool silc_hash_utf8_compare(void *key1, void *key2,
 326  *                                    void *user_context);
 327  *
 328  * DESCRIPTION
 329  *
 330  *    Compares UTF-8 strings.  Casefolded and NULL terminated strings are
 331  *    expected.  May be used as SilcHashTable comparison function.
 332  *
 333  ***/
 334 SilcBool silc_hash_utf8_compare(void *key1, void *key2, void *user_context);
 335
 336 /****f* silcutil/SilcUtilAPI/silc_fingerprint
 337  *
 338  * SYNOPSIS
 339  *
 340  *    char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 341  *
 342  * DESCRIPTION
 343  *
 344  *    Return a textual representation of the fingerprint in *data, the
 345  *    caller must free the returned string.
 346  *
 347  ***/
 348 char *silc_fingerprint(const unsigned char *data, SilcUInt32 data_len);
 349
 350 /****f* silcutil/SilcUtilAPI/silc_string_is_ascii
 351  *
 352  * SYNOPSIS
 353  *
 354  *    SilcBool silc_string_is_ascii(const unsigned char *data,
 355  *                              SilcUInt32 data_len);
 356  *
 357  * DESCRIPTION
 358  *
 359  *    Return TRUE if the `data' is ASCII string.
 360  *
 361  ***/
 362 SilcBool silc_string_is_ascii(const unsigned char *data, SilcUInt32 data_len);
 363
 364 /****f* silcutil/SilcUtilAPI/silc_get_input
 365  *
 366  * SYNOPSIS
 367  *
 368  *    char *silc_get_input(const char *prompt, SilcBool echo_off);
 369  *
 370  * DESCRIPTION
 371  *
 372  *    Displays input prompt on command line and takes input data from user.
 373  *
 374  ***/
 375 char *silc_get_input(const char *prompt, SilcBool echo_off);
 376
 377 /* System dependant prototypes */
 378
 379 /****f* silcutil/SilcUtilAPI/silc_get_username
 380  *
 381  * SYNOPSIS
 382  *
 383  *    char *silc_get_username();
 384  *
 385  * DESCRIPTION
 386  *
 387  *    Returns the username of the user. If the global variable LOGNAME
 388  *    does not exists we will get the name from the passwd file.  The
 389  *    caller must free the returned name.
 390  *
 391  *    This function is system dependant.
 392  *
 393  ***/
 394 char *silc_get_username();
 395
 396 /****f* silcutil/SilcUtilAPI/silc_get_real_name
 397  *
 398  * SYNOPSIS
 399  *
 400  *    char *silc_get_real_name();
 401  *
 402  * DESCRIPTION
 403  *
 404  *    Returns the real name of ther user from the passwd file.  The
 405  *    caller must free the returned name.
 406  *
 407  *    This function is system dependant.
 408  *
 409  ***/
 410 char *silc_get_real_name();
 411
 412 /****f* silcutil/SilcUtilAPI/silc_va_copy
 413  *
 414  * SYNOPSIS
 415  *
 416  *    void silc_va_copy(va_list dest, va_list src);
 417  *
 418  * DESCRIPTION
 419  *
 420  *    Copies variable argument list.  This must be called in case the
 421  *    variable argument list must be evaluated multiple times.  For each
 422  *    evaluation the list must be copied and va_end must be called for
 423  *    each copied list.
 424  *
 425  ***/
 426 #if defined(HAVE_VA_COPY)
 427 #define silc_va_copy(dest, src) va_copy(dest, src);
 428 #elif defined(HAVE___VA_COPY)
 429 #define silc_va_copy(dest, src) __va_copy(dest, src);
 430 #elif defined(SILC_VA_COPY_ARRAY)
 431 #define silc_va_copy(dest, src) memmove(dest, src, sizeof(va_list));
 432 #else
 433 #define silc_va_copy(dest, src) dest = src;
 434 #endif
 435
 436 #endif  /* !SILCUTIL_H */