lib/silcclient/silcclient.h

   1 /*
   2
   3   silcclient.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2000 - 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* silcclient/Client Library Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * This interface defines the SILC Client Library API for the application.
  25  * The Client Library is a full features SILC client without a user interface.
  26  * A simple interface called SILC Client Operations (SilcClientOperations)
  27  * is provided for applications to implmeent the necessary functions to use
  28  * the client library.  The silcclient.h header file includes client library
  29  * API, such as command handling and message sending.  The silcclient_entry.h
  30  * header file includes entry handling, such as channel and user entry
  31  * handling.
  32  *
  33  * Practically all functions in the Client Library API accepts SilcClient
  34  * and SilcClientConnection as their first two argument.  The first argument
  35  * is the actual SilcClient context and the second is the SilcClientConnection
  36  * context of the connection in question.  Application may create and handle
  37  * multiple connections in one SilcClient.  Connections can be created to
  38  * servers and other clients.
  39  *
  40  * The Client Library support multiple threads and is threads safe is used
  41  * correctly.  Messages can be sent from multiple threads without any
  42  * locking.  Messages however are always received only in one thread unless
  43  * message waiting (see silc_client_private_message_wait as an example) is
  44  * used.  The threads can be turned on and off by giving a parameter to the
  45  * SilcClient.  When turned on, each new connection to remote host is always
  46  * executed in an own thread.  All tasks related to that connection are then
  47  * executed in that thread.  This means that client operation callbacks for
  48  * that connections may be called from threads and application will need to
  49  * employ concurrency control if the callbacks need to access shared data
  50  * in the application.  Messages are also received in that thread.
  51  *
  52  * All entries (SilcClientEntry, SilcChannelEntry and SilcServerEntry) are
  53  * reference counted.  If application wishes to save an entry pointer it must
  54  * always first acquire a reference.  The reference must be released once the
  55  * entry is not needed anymore.  If application wants to read any data from
  56  * the entry structure it must first lock the entry.  This protects access to
  57  * the entries in multithreaded environment.  If threads are not used, locking
  58  * the entries is not needed.  They however still must be referenced even
  59  * when threads are not used.
  60  *
  61  ***/
  62
  63 #ifndef SILCCLIENT_H
  64 #define SILCCLIENT_H
  65
  66 #ifdef __cplusplus
  67 extern "C" {
  68 #endif
  69
  70 #include "client.h"
  71 #include "silcclient_entry.h"
  72
  73 /* General definitions */
  74
  75 /****d* silcclient/SilcClientAPI/SilcClientConnectionStatus
  76  *
  77  * NAME
  78  *
  79  *    typedef enum { ... } SilcClientConnectionStatus
  80  *
  81  * DESCRIPTION
  82  *
  83  *    This type is returned to the `connect' client operation to indicate
  84  *    the status of the created connection.  It can indicate if it was
  85  *    successful or whether an error occurred.
  86  *
  87  * SOURCE
  88  */
  89 typedef enum {
  90   SILC_CLIENT_CONN_SUCCESS,            /* Successfully connected */
  91   SILC_CLIENT_CONN_SUCCESS_RESUME,     /* Successfully connected and
  92                                           resumed old detached session */
  93   SILC_CLIENT_CONN_DISCONNECTED,       /* Remote host disconnected */
  94   SILC_CLIENT_CONN_ERROR,              /* Error occurred during connecting */
  95   SILC_CLIENT_CONN_ERROR_KE,           /* Key Exchange failed */
  96   SILC_CLIENT_CONN_ERROR_AUTH,         /* Authentication failed */
  97   SILC_CLIENT_CONN_ERROR_RESUME,       /* Resuming failed */
  98   SILC_CLIENT_CONN_ERROR_TIMEOUT,      /* Timeout during connecting */
  99 } SilcClientConnectionStatus;
 100 /***/
 101
 102 /****f* silcclient/SilcClientAPI/SilcClientRunning
 103  *
 104  * SYNOPSIS
 105  *
 106  *    typedef void (*SilcClientRunning)(SilcClient client, void *context);
 107  *
 108  * DESCRIPTION
 109  *
 110  *    The callback given as argument to silc_client_init function.  Once
 111  *    this is called the client library is running and application may
 112  *    start using the Client library API.
 113  *
 114  ***/
 115 typedef void (*SilcClientRunning)(SilcClient client, void *context);
 116
 117 /****f* silcclient/SilcClientAPI/SilcClientStopped
 118  *
 119  * SYNOPSIS
 120  *
 121  *    typedef void (*SilcClientStopped)(SilcClient client, void *context);
 122  *
 123  * DESCRIPTION
 124  *
 125  *    The callback given as argument to silc_client_stop.  Once this is
 126  *    called the client library has stopped and can be freed by calling
 127  *    silc_client_free.  Note that this won't be called if there are
 128  *    active connections in the client.  Connections must first be closed
 129  *    by calling silc_client_close_connection or by sending QUIT command to
 130  *    the server connection.
 131  *
 132  ***/
 133 typedef void (*SilcClientStopped)(SilcClient client, void *context);
 134
 135 /****f* silcclient/SilcClientAPI/SilcClientConnectCallback
 136  *
 137  * SYNOPSIS
 138  *
 139  *    void (*SilcClientConnectCallback)(SilcClient client,
 140  *                                      SilcClientConnection conn,
 141  *                                      SilcClientConnectionStatus status,
 142  *                                      SilcStatus error,
 143  *                                      const char *message,
 144  *                                      void *context);
 145  *
 146  * DESCRIPTION
 147  *
 148  *    Connect callbak given as argument to silc_client_connect_to_server,
 149  *    silc_client_connect_to_client and silc_client_key_exchange functions.
 150  *    It is called to indicate the status of the connection, indicated
 151  *    by the `status'.  It is called after the connection has been
 152  *    established to the remote host and when connection is disconnected
 153  *    by the remote host.  The `context' is the context given as argument
 154  *    to the connecting function.  If the `status' is an error the `error'
 155  *    may indicate more detailed error.  If `error' is SILC_STATUS_OK no
 156  *    detailed error message is available.
 157  *
 158  *    When the `status' is SILC_CLIENT_CONN_DISCONNECTED the `error' will
 159  *    indicate the reason for disconnection.  If the `message' is non-NULL
 160  *    it delivers error or disconnection message.
 161  *
 162  ***/
 163 typedef void (*SilcClientConnectCallback)(SilcClient client,
 164                                           SilcClientConnection conn,
 165                                           SilcClientConnectionStatus status,
 166                                           SilcStatus error,
 167                                           const char *message,
 168                                           void *context);
 169
 170 /****s* silcclient/SilcClientAPI/SilcClient
 171  *
 172  * NAME
 173  *
 174  *    typedef struct SilcClientStruct { ... } *SilcClient
 175  *
 176  * DESCRIPTION
 177  *
 178  *    This is the actual SILC Client structure which represents one
 179  *    SILC Client.  It is allocated with the silc_client_alloc function
 180  *    and given as argument to all SILC Client Library functions.  It
 181  *    is initialized with silc_client_init function, and freed with
 182  *    silc_client_free function.
 183  *
 184  *    This context represents the client.  Each connection to remote server
 185  *    is represented by SilcClientConnection context.
 186  *
 187  * SOURCE
 188  */
 189 struct SilcClientStruct {
 190   char *username;               /* Username */
 191   char *hostname;               /* hostname */
 192   char *realname;               /* Real name */
 193   SilcSchedule schedule;        /* Client scheduler */
 194   SilcRng rng;                  /* Random number generator */
 195   void *application;            /* Application specific context, set with
 196                                    silc_client_alloc. */
 197
 198   /* Internal data for client library.  Application cannot access this. */
 199   SilcClientInternal internal;
 200 };
 201 /***/
 202
 203 /****s* silcclient/SilcClientAPI/SilcClientConnection
 204  *
 205  * NAME
 206  *
 207  *    typedef struct SilcClientConnectionStruct { ... }
 208  *                      *SilcClientConnection
 209  *
 210  * DESCRIPTION
 211  *
 212  *    This structure represents a connection.  It is allocated and freed by
 213  *    the library.  It is returned to application in SilcClientConnectCallback.
 214  *    It includes all the important data for the session such as local
 215  *    client entry (which includes current nickname), local and remote IDs,
 216  *    and other information.  All strings in the structure are UTF-8 encoded.
 217  *
 218  * SOURCE
 219  */
 220 struct SilcClientConnectionStruct {
 221   SilcClientEntry local_entry;         /* Our own Client Entry */
 222   SilcClientID *local_id;              /* Our current Client ID */
 223
 224   char *remote_host;                   /* Remote host name */
 225   int remote_port;                     /* Remote port */
 226   SilcID remote_id;                    /* Remote ID */
 227
 228   SilcChannelEntry current_channel;    /* Current joined channel */
 229   SilcPublicKey public_key;            /* Public key used in this connection */
 230   SilcPrivateKey private_key;          /* Private key */
 231   SilcPacketStream stream;             /* Connection to remote host */
 232   SilcConnectionType type;             /* Connection type */
 233   SilcClientConnectCallback callback;  /* Connection callback */
 234   void *callback_context;              /* Connection context */
 235   SilcClient client;                   /* Pointer back to SilcClient */
 236
 237   /* Application specific data.  Application may set here whatever it wants. */
 238   void *context;
 239
 240   /* Internal data for client library.  Application cannot access this. */
 241   SilcClientConnectionInternal internal;
 242 };
 243 /***/
 244
 245 /****s* silcclient/SilcClientAPI/SilcChannelUser
 246  *
 247  * NAME
 248  *
 249  *    typedef struct SilcChannelUserStruct { ... } *SilcChannelUser
 250  *
 251  * DESCRIPTION
 252  *
 253  *    This structure represents a client that has joined to a channel.
 254  *    It shows the client and the channel and the client's mode (channel
 255  *    user mode) on the channel.
 256  *
 257  * SOURCE
 258  */
 259 struct SilcChannelUserStruct {
 260   SilcClientEntry client;                    /* Client joined on channel */
 261   SilcUInt32 mode;                           /* mode, ChannelUserModes */
 262   SilcChannelEntry channel;                  /* The channel user has joined */
 263
 264   /* Application specific data.  Application may set here whatever it wants. */
 265   void *context;
 266 };
 267 /***/
 268
 269 /****s* silcclient/SilcClientAPI/SilcClientStats
 270  *
 271  * NAME
 272  *
 273  *    typedef struct { ... } SilcClientStats;
 274  *
 275  * DESCRIPTION
 276  *
 277  *    This structure holds SILC network statistics returned by the
 278  *    SILC_COMMAND_STATS command reply to the application.
 279  *
 280  * SOURCE
 281  */
 282 typedef struct {
 283   SilcUInt32 starttime;         /* SILC server start time */
 284   SilcUInt32 uptime;            /* SILC server uptime*/
 285   SilcUInt32 my_clients;        /* Number of clients in the server */
 286   SilcUInt32 my_channels;       /* Number of channel in the server */
 287   SilcUInt32 my_server_ops;     /* Number of server operators in the server */
 288   SilcUInt32 my_router_ops;     /* Number of router operators in the router */
 289   SilcUInt32 cell_clients;      /* Number of clients in the cell */
 290   SilcUInt32 cell_channels;     /* Number of channels in the cell */
 291   SilcUInt32 cell_servers;      /* Number of server in the cell */
 292   SilcUInt32 clients;           /* All clients in SILC network */
 293   SilcUInt32 channels;          /* All channels in SILC network */
 294   SilcUInt32 servers;           /* All servers in SILC network */
 295   SilcUInt32 routers;           /* All routers in SILC network */
 296   SilcUInt32 server_ops;        /* All server operators in SILC network */
 297   SilcUInt32 router_ops;        /* All router operators in SILC network */
 298 } SilcClientStats;
 299 /***/
 300
 301 /****d* silcclient/SilcClientAPI/SilcKeyAgreementStatus
 302  *
 303  * NAME
 304  *
 305  *    typedef enum { ... } SilcKeyAgreementStatus;
 306  *
 307  * DESCRIPTION
 308  *
 309  *    Key agreement status types indicating the status of the key
 310  *    agreement protocol.  These types are returned to the application
 311  *    in the SilcKeyAgreementCallback callback function.
 312  *
 313  * SOURCE
 314  */
 315 typedef enum {
 316   SILC_KEY_AGREEMENT_OK,               /* Everything is Ok */
 317   SILC_KEY_AGREEMENT_ERROR,            /* Unknown error occurred */
 318   SILC_KEY_AGREEMENT_FAILURE,          /* The protocol failed */
 319   SILC_KEY_AGREEMENT_TIMEOUT,          /* The protocol timeout */
 320   SILC_KEY_AGREEMENT_ABORTED,          /* The protocol aborted */
 321   SILC_KEY_AGREEMENT_ALREADY_STARTED,  /* Already started */
 322   SILC_KEY_AGREEMENT_SELF_DENIED,      /* Negotiationg with itself denied */
 323   SILC_KEY_AGREEMENT_NO_MEMORY,        /* System out of memory */
 324 } SilcKeyAgreementStatus;
 325 /***/
 326
 327 /****f* silcclient/SilcClientAPI/SilcKeyAgreementCallback
 328  *
 329  * SYNOPSIS
 330  *
 331  *    typedef void (*SilcKeyAgreementCallback)(SilcClient client,
 332  *                                             SilcClientConnection conn,
 333  *                                             SilcClientEntry client_entry,
 334  *                                             SilcKeyAgreementStatus status,
 335  *                                             SilcSKEKeyMaterial *key,
 336  *                                             void *context);
 337  *
 338  * DESCRIPTION
 339  *
 340  *    Key agreement callback that is called after the key agreement protocol
 341  *    has been performed. This is called also if error occurred during the
 342  *    key agreement protocol. The `key' is the allocated key material and
 343  *    the caller is responsible of freeing it. The `key' is NULL if error
 344  *    has occurred. The application can freely use the `key' to whatever
 345  *    purpose it needs. See lib/silcske/silcske.h for the definition of
 346  *    the SilcSKEKeyMaterial structure.
 347  *
 348  ***/
 349 typedef void (*SilcKeyAgreementCallback)(SilcClient client,
 350                                          SilcClientConnection conn,
 351                                          SilcClientEntry client_entry,
 352                                          SilcKeyAgreementStatus status,
 353                                          SilcSKEKeyMaterial key,
 354                                          void *context);
 355
 356 /****s* silcclient/SilcClientAPI/SilcPrivateMessageKeys
 357  *
 358  * NAME
 359  *
 360  *    typedef struct { ... } SilcPrivateMessageKeys;
 361  *
 362  * DESCRIPTION
 363  *
 364  *    Structure to hold the list of private message keys. The list of these
 365  *    structures is returned by the silc_client_list_private_message_keys
 366  *    function.
 367  *
 368  * SOURCE
 369  */
 370 typedef struct {
 371   SilcClientEntry client_entry;       /* The remote client entry */
 372   char *cipher;                       /* The cipher name */
 373   unsigned char *key;                 /* The original key, If the appliation
 374                                          provided it. This is NULL if
 375                                          the SKE key material was used. */
 376   SilcUInt32 key_len;                 /* The key length */
 377 } *SilcPrivateMessageKeys;
 378 /***/
 379
 380 /****s* silcclient/SilcClientAPI/SilcChannelPrivateKey
 381  *
 382  * NAME
 383  *
 384  *    typedef struct SilcChannelPrivateKeyStruct { ... }
 385  *                      *SilcChannelPrivateKey;
 386  *
 387  * DESCRIPTION
 388  *
 389  *    Structure to hold one channel private key. The array of this structure
 390  *    is returned by silc_client_list_channel_private_keys function.
 391  *
 392  * SOURCE
 393  */
 394 struct SilcChannelPrivateKeyStruct {
 395   char *name;                         /* Application given name */
 396   SilcCipher cipher;                  /* The cipher and key */
 397   SilcHmac hmac;                      /* The HMAC and hmac key */
 398 };
 399 /***/
 400
 401 /****f* silcclient/SilcClientAPI/SilcAskPassphrase
 402  *
 403  * SYNOPSIS
 404  *
 405  *    typedef void (*SilcAskPassphrase)(unsigned char *passphrase,
 406  *                                      SilcUInt32 passphrase_len,
 407  *                                      void *context);
 408  *
 409  * DESCRIPTION
 410  *
 411  *    Ask passphrase callback. This is called by the application when the
 412  *    library calls `ask_passphrase' client operation.  The callback delivers
 413  *    the passphrase to the library.  The passphrases in SILC protocol
 414  *    MUST be in UTF-8 encoding, therefore the `passphrase' SHOULD be UTF-8
 415  *    encoded, and if it is not then library will attempt to encode it.
 416  *
 417  ***/
 418 typedef void (*SilcAskPassphrase)(unsigned char *passphrase,
 419                                   SilcUInt32 passphrase_len,
 420                                   void *context);
 421
 422 /****f* silcclient/SilcClientAPI/SilcVerifyPublicKey
 423  *
 424  * SYNOPSIS
 425  *
 426  *    typedef void (*SilcVerifyPublicKey)(SilcBool success, void *context);
 427  *
 428  * DESCRIPTION
 429  *
 430  *    Public key (or certificate) verification callback. This is called
 431  *    by the application to indicate that the public key verification was
 432  *    either success or failure.
 433  *
 434  ***/
 435 typedef void (*SilcVerifyPublicKey)(SilcBool success, void *context);
 436
 437 /****f* silcclient/SilcClientAPI/SilcGetAuthMeth
 438  *
 439  * SYNOPSIS
 440  *
 441  *    typedef void (*SilcGetAuthMeth)(SilcBool success,
 442  *                                    SilcAuthMethod auth_meth,
 443  *                                    void *auth, SilcUInt32 auth_len,
 444  *                                    void *context);
 445  *
 446  * DESCRIPTION
 447  *
 448  *    Authentication data resolving callback. This is called by the
 449  *    application to return the resolved authentication data. The client
 450  *    library has called the get_auth_method client operation and given
 451  *    this function pointer as argument. The `auth_meth' is the selected
 452  *    authentication method. The `auth_data' and the `auth_data_len'
 453  *    are the resolved authentication data. The `context' is the libary's
 454  *    context sent to the get_auth_method client operation.
 455  *
 456  *    If the `auth_method' is SILC_AUTH_PASSWORD then `auth' and `auth_len'
 457  *    is the passphrase and its length.  If it is SILC_AUTH_PUBLIC_KEY the
 458  *    `auth' must be NULL.  The library will use the private key given as
 459  *    argument to silc_client_connect_to_server, silc_client_connect_to_client
 460  *    or silc_client_key_exchange.  If it is SILC_AUTH_NONE, both `auth' and
 461  *    `auth_len' are ignored.
 462  *
 463  ***/
 464 typedef void (*SilcGetAuthMeth)(SilcAuthMethod auth_meth,
 465                                 void *auth, SilcUInt32 auth_len,
 466                                 void *context);
 467
 468 /****d* silcclient/SilcClientAPI/SilcClientMessageType
 469  *
 470  * NAME
 471  *
 472  *    typedef enum { ... } SilcClientMessageType;
 473  *
 474  * DESCRIPTION
 475  *
 476  *    Different message types for `say' client operation.  The application
 477  *    may filter the message sent by the library according this type.
 478  *
 479  * SOURCE
 480  */
 481 typedef enum {
 482   SILC_CLIENT_MESSAGE_INFO,            /* Informational */
 483   SILC_CLIENT_MESSAGE_WARNING,         /* Warning */
 484   SILC_CLIENT_MESSAGE_ERROR,           /* Error */
 485   SILC_CLIENT_MESSAGE_AUDIT,           /* Auditable */
 486 } SilcClientMessageType;
 487 /***/
 488
 489 /****s* silcclient/SilcClientAPI/SilcClientOperations
 490  *
 491  * NAME
 492  *
 493  *    typedef struct { ... } SilcClientOperations;
 494  *
 495  * DESCRIPTION
 496  *
 497  *    SILC Client Operations. These must be implemented by the application.
 498  *    The Client library may call any of these routines at any time.  The
 499  *    routines are used to deliver certain information to the application
 500  *    or from the application to the client library.
 501  *
 502  * SOURCE
 503  */
 504 typedef struct {
 505   /* Message sent to the application by library. `conn' associates the
 506      message to a specific connection.  `conn', however, may be NULL.
 507      The `type' indicates the type of the message sent by the library.
 508      The application can for example filter the message according the
 509      type.  The variable argument list is arguments to the formatted
 510      message that `msg' may be. */
 511   void (*say)(SilcClient client, SilcClientConnection conn,
 512               SilcClientMessageType type, char *msg, ...);
 513
 514   /* Message for a channel. The `sender' is the sender of the message
 515      The `channel' is the channel. The `message' is the message.  Note
 516      that `message' maybe NULL.  The `flags' indicates message flags
 517      and it is used to determine how the message can be interpreted
 518      (like it may tell the message is multimedia message). */
 519   void (*channel_message)(SilcClient client, SilcClientConnection conn,
 520                           SilcClientEntry sender, SilcChannelEntry channel,
 521                           SilcMessagePayload payload,
 522                           SilcChannelPrivateKey key, SilcMessageFlags flags,
 523                           const unsigned char *message,
 524                           SilcUInt32 message_len);
 525
 526   /* Private message to the client. The `sender' is the sender of the
 527      message. The message is `message'and maybe NULL.  The `flags'
 528      indicates message flags  and it is used to determine how the message
 529      can be interpreted (like it may tell the message is multimedia
 530      message). */
 531   void (*private_message)(SilcClient client, SilcClientConnection conn,
 532                           SilcClientEntry sender, SilcMessagePayload payload,
 533                           SilcMessageFlags flags, const unsigned char *message,
 534                           SilcUInt32 message_len);
 535
 536   /* Notify message to the client. The notify arguments are sent in the
 537      same order as servers sends them. The arguments are same as received
 538      from the server except for ID's.  If ID is received application receives
 539      the corresponding entry to the ID. For example, if Client ID is received
 540      application receives SilcClientEntry.  Also, if the notify type is
 541      for channel the channel entry is sent to application (even if server
 542      does not send it because client library gets the channel entry from
 543      the Channel ID in the packet's header). */
 544   void (*notify)(SilcClient client, SilcClientConnection conn,
 545                  SilcNotifyType type, ...);
 546
 547   /* Command handler. This function is called always after application has
 548      called a command.  It will be called to indicate that the command
 549      was processed.  It will also be called if error occurs while processing
 550      the command.  The `success' indicates whether the command was sent
 551      or if error occurred.  The `status' indicates the actual error.
 552      The `argc' and `argv' are the command line arguments sent to the
 553      command by application.  Note that, this is not reply to the command
 554      from server, this is merely and indication to application that the
 555      command was processed. */
 556   void (*command)(SilcClient client, SilcClientConnection conn,
 557                   SilcBool success, SilcCommand command, SilcStatus status,
 558                   SilcUInt32 argc, unsigned char **argv);
 559
 560   /* Command reply handler. This function is called always in the command reply
 561      function. If error occurs it will be called as well. Normal scenario
 562      is that it will be called after the received command data has been parsed
 563      and processed. The function is used to pass the received command data to
 564      the application.
 565
 566      `conn' is the associated client connection. `cmd_payload' is the command
 567      payload data received from server and it can be ignored. It is provided
 568      if the application would like to re-parse the received command data,
 569      however, it must be noted that the data is parsed already by the library
 570      thus the payload can be ignored. `success' is FALSE if error occurred.
 571      In this case arguments are not sent to the application. The `status' is
 572      the command reply status server returned. The `command' is the command
 573      reply being processed. The function has variable argument list and each
 574      command defines the number and type of arguments it passes to the
 575      application (on error they are not sent).
 576
 577      The arguments are sent in the same order as servers sends them.  The
 578      arguments are same as received from the server except for ID's.  If
 579      ID is received application receives the corresponding entry to the
 580      ID. For example, if Client ID is receives application receives
 581      SilcClientEntry. */
 582   void (*command_reply)(SilcClient client, SilcClientConnection conn,
 583                         SilcCommand command, SilcStatus status,
 584                         SilcStatus error, va_list ap);
 585
 586   /* Find authentication method and authentication data by hostname and
 587      port. The hostname may be IP address as well. The `auth_method' is
 588      the authentication method the remote connection requires.  It is
 589      however possible that remote accepts also some other authentication
 590      method.  Application should use the method that may have been
 591      configured for this connection.  If none has been configured it should
 592      use the required `auth_method'.  If the `auth_method' is
 593      SILC_AUTH_NONE, server does not require any authentication or the
 594      required authentication method is not known.  The `completion'
 595      callback must be called to deliver the chosen authentication method
 596      and data. The `conn' may be NULL. */
 597   void (*get_auth_method)(SilcClient client, SilcClientConnection conn,
 598                           char *hostname, SilcUInt16 port,
 599                           SilcAuthMethod auth_method,
 600                           SilcGetAuthMeth completion, void *context);
 601
 602   /* Verifies received public key. The `conn_type' indicates which entity
 603      (server or client) has sent the public key. If user decides to trust
 604      the key the application may save the key as trusted public key for
 605      later use. The `completion' must be called after the public key has
 606      been verified. */
 607   void (*verify_public_key)(SilcClient client, SilcClientConnection conn,
 608                             SilcConnectionType conn_type,
 609                             SilcPublicKey public_key,
 610                             SilcVerifyPublicKey completion, void *context);
 611
 612   /* Ask (interact, that is) a passphrase from user. The passphrase is
 613      returned to the library by calling the `completion' callback with
 614      the `context'. The returned passphrase SHOULD be in UTF-8 encoded,
 615      if not then the library will attempt to encode. */
 616   void (*ask_passphrase)(SilcClient client, SilcClientConnection conn,
 617                          SilcAskPassphrase completion, void *context);
 618
 619   /* Called to indicate that incoming key agreement request has been
 620      received.  If the application wants to perform key agreement it may
 621      call silc_client_perform_key_agreement to initiate key agreementn or
 622      silc_client_send_key_agreement to provide connection point to the
 623      remote client in case the `hostname' is NULL.  If key agreement is
 624      not desired this request can be ignored.  The `protocol' is either
 625      value 0 for TCP or value 1 for UDP. */
 626   void (*key_agreement)(SilcClient client, SilcClientConnection conn,
 627                         SilcClientEntry client_entry,
 628                         const char *hostname, SilcUInt16 protocol,
 629                         SilcUInt16 port);
 630
 631   /* Notifies application that file transfer protocol session is being
 632      requested by the remote client indicated by the `client_entry' from
 633      the `hostname' and `port'. The `session_id' is the file transfer
 634      session and it can be used to either accept or reject the file
 635      transfer request, by calling the silc_client_file_receive or
 636      silc_client_file_close, respectively. */
 637   void (*ftp)(SilcClient client, SilcClientConnection conn,
 638               SilcClientEntry client_entry, SilcUInt32 session_id,
 639               const char *hostname, SilcUInt16 port);
 640 } SilcClientOperations;
 641 /***/
 642
 643 /****s* silcclient/SilcClientAPI/SilcClientParams
 644  *
 645  * NAME
 646  *
 647  *    typedef struct { ... } SilcClientParams;
 648  *
 649  * DESCRIPTION
 650  *
 651  *    Client parameters. This can be filled with proper values and
 652  *    given as argument to the silc_client_alloc function. The structure
 653  *    hold various parameters which affects the function of the client.
 654  *
 655  * SOURCE
 656  */
 657 typedef struct {
 658   /* If this boolean is set to TRUE then the client library will use
 659      threads.  Any of the callback functions in the SilcClientOperations
 660      and other callbacks may be called at any time in a thread.  The
 661      application may need to employ appropriate concurrency control
 662      in the callbacks to protect application specific data. */
 663   SilcBool threads;
 664
 665   /* Nickname format string. This can be used to order the client library
 666      to save the nicknames in the library in a certain format. Since
 667      nicknames are not unique in SILC it is possible to have multiple same
 668      nicknames. Using this format string it is possible to order the library
 669      to separate the multiple same nicknames from each other. If this is
 670      empty then default format is used which is the default nickname
 671      without anything else. The string MUST be NULL terminated.
 672
 673      Following format types are available:
 674
 675      %n  nickname      - the real nickname returned by the server (mandatory)
 676      %h  hostname      - the stripped hostname of the client
 677      %H  full hostname - the full hostname of the client
 678      %s  server name   - the server name the client is connected
 679      %S  full server   - the full server name the client is connected
 680      %a  number        - ascending number in case there are several
 681                          same nicknames (fe. nick@host and nick@host2)
 682
 683      Example format strings: "%n@%h%a"   (fe. nick@host, nick@host2)
 684                              "%a!%n@%s"  (fe. nick@server, 2!nick@server)
 685                              "%n@%H"     (fe. nick@host.domain.com)
 686
 687      Note that there must always be some separator characters around '%n'
 688      format.  It is not possible to put format characters before or after
 689      '%n' without separators (such ash '@').  Also note that the separator
 690      character should be a character that cannot be part of normal nickname.
 691   */
 692   char nickname_format[32];
 693
 694   /* If this is set to TRUE then the `nickname_format' is employed to all
 695      saved nicknames even if there are no multiple same nicknames in the
 696      cache. By default this is FALSE, which means that the `nickname_format'
 697      is employed only if the library will receive a nickname that is
 698      already saved in the cache. It is recommended to leave this to FALSE
 699      value. */
 700   SilcBool nickname_force_format;
 701
 702   /* If this is set to TRUE, the silcclient library will not register and
 703      deregister the cipher, pkcs, hash and hmac algorithms. The application
 704      itself will need to handle that. */
 705   SilcBool dont_register_crypto_library;
 706
 707 } SilcClientParams;
 708 /***/
 709
 710
 711 /* Initialization functions (client.c) */
 712
 713 /****f* silcclient/SilcClientAPI/silc_client_alloc
 714  *
 715  * SYNOPSIS
 716  *
 717  *    SilcClient silc_client_alloc(SilcClientOperations *ops,
 718  *                                 SilcClientParams *params,
 719  *                                 void *application,
 720  *                                 const char *silc_version);
 721  *
 722  * DESCRIPTION
 723  *
 724  *    Allocates new client object. This has to be done before client may
 725  *    work. After calling this one must call silc_client_init to initialize
 726  *    the client. The `application' is application specific user data pointer
 727  *    and caller must free it. The `silc_version' is the application version
 728  *    that will be used to compare against remote host's (usually a server)
 729  *    version string.  The `application' context is accessible by the
 730  *    application by client->application, client being SilcClient.
 731  *
 732  ***/
 733 SilcClient silc_client_alloc(SilcClientOperations *ops,
 734                              SilcClientParams *params,
 735                              void *application,
 736                              const char *version_string);
 737
 738 /****f* silcclient/SilcClientAPI/silc_client_free
 739  *
 740  * SYNOPSIS
 741  *
 742  *    void silc_client_free(SilcClient client);
 743  *
 744  * DESCRIPTION
 745  *
 746  *    Frees client object and its internals.  The execution of the client
 747  *    should be stopped with silc_client_stop function before calling
 748  *    this function.
 749  *
 750  ***/
 751 void silc_client_free(SilcClient client);
 752
 753 /****f* silcclient/SilcClientAPI/silc_client_init
 754  *
 755  * SYNOPSIS
 756  *
 757  *    SilcBool silc_client_init(SilcClient client, const char *username,
 758  *                              const char *hostname, const char *realname,
 759  *                              SilcClientRunning running, void *context);
 760  *
 761  * DESCRIPTION
 762  *
 763  *    Initializes the client. This makes all the necessary steps to make
 764  *    the client ready to be run. One must call silc_client_run to run the
 765  *    client. Returns FALSE if error occurred, TRUE otherwise.
 766  *
 767  *    The `username' and `hostname' strings must be given and they must be
 768  *    UTF-8 encoded.  The `username' is the client's username in the
 769  *    operating system, `hostname' is the client's host name and the
 770  *    `realname' is the user's real name.
 771  *
 772  *    The `running' callback is called after the client is running after
 773  *    silc_client_run or silc_client_run_one has been called.  Application
 774  *    may start using the Client library API after that.  Setting the
 775  *    callback is optional, but recommended.
 776  *
 777  ***/
 778 SilcBool silc_client_init(SilcClient client, const char *username,
 779                           const char *hostname, const char *realname,
 780                           SilcClientRunning running, void *context);
 781
 782 /****f* silcclient/SilcClientAPI/silc_client_run
 783  *
 784  * SYNOPSIS
 785  *
 786  *    void silc_client_run(SilcClient client);
 787  *
 788  * DESCRIPTION
 789  *
 790  *    Runs the client.  This starts the scheduler from the utility library.
 791  *    When this functions returns the execution of the application is over.
 792  *    The client must be initialized before calling this.
 793  *
 794  ***/
 795 void silc_client_run(SilcClient client);
 796
 797 /****f* silcclient/SilcClientAPI/silc_client_run_one
 798  *
 799  * SYNOPSIS
 800  *
 801  *    void silc_client_run_one(SilcClient client);
 802  *
 803  * DESCRIPTION
 804  *
 805  *    Runs the client and returns immeadiately. This function is used when
 806  *    the SILC Client object indicated by the `client' is run under some
 807  *    other scheduler, or event loop or main loop.  On GUI applications,
 808  *    for example this may be desired to used to run the client under the
 809  *    GUI application's main loop.  Typically the GUI application would
 810  *    register an idle task that calls this function multiple times in
 811  *    a second to quickly process the SILC specific data.
 812  *
 813  ***/
 814 void silc_client_run_one(SilcClient client);
 815
 816 /****f* silcclient/SilcClientAPI/silc_client_stop
 817  *
 818  * SYNOPSIS
 819  *
 820  *    void silc_client_stop(SilcClient client, SilcClientStopped stopped,
 821  *                          void *context);
 822  *
 823  * DESCRIPTION
 824  *
 825  *    Stops the client. This is called to stop the client and thus to stop
 826  *    the program.  The client context must be freed with the silc_client_free
 827  *    function.  All connections that exist in this client must be closed
 828  *    before calling this function.  Connections can be closed by calling
 829  *    silc_client_close_connection.
 830  *
 831  *    The `stopped' will be called once the client and all connections have
 832  *    finished.  The client may be freed after that.  Note that the `stopped'
 833  *    won't be called before all connections have finished.  Setting the
 834  *    callback is optional.
 835  *
 836  ***/
 837 void silc_client_stop(SilcClient client, SilcClientStopped stopped,
 838                       void *context);
 839
 840 /* Connecting functions */
 841
 842 /****s* silcclient/SilcClientAPI/SilcClientConnectionParams
 843  *
 844  * NAME
 845  *
 846  *    typedef struct { ... } SilcClientConnectionParams;
 847  *
 848  * DESCRIPTION
 849  *
 850  *    Client connection parameters.  This can be filled by the application
 851  *    and given as argument to silc_client_connect_to_server,
 852  *    silc_client_connect_to_client, silc_client_key_exchange or
 853  *    silc_client_send_key_agreement.
 854  *
 855  * SOURCE
 856  */
 857 typedef struct {
 858   /* If this is provided the user's nickname in the network will be the
 859      string given here.  If it is given, it must be UTF-8 encoded.  If this
 860      string is not given, the user's username by default is used as nickname.
 861      The nickname may later be changed by using NICK command.  The maximum
 862      length for the nickname string is 128 bytes. */
 863   char *nickname;
 864
 865   /* If this key repository pointer is non-NULL then public key received in
 866      the key exchange protocol will be verified from this repository.  If
 867      this is not provided then the `verify_public_key' client operation will
 868      be called back to application.  If the boolean `verify_notfound' is set
 869      to TRUE then the `verify_public_key' client operation will be called
 870      in case the public key is not found in `repository'.  Only public keys
 871      added with at least SILC_SKR_USAGE_KEY_AGREEMENT in the repository will
 872      be checked, other keys will be ignored. */
 873   SilcSKR repository;
 874   SilcBool verify_notfound;
 875
 876   /* Authentication data.  Application may set here the authentication data
 877      and authentication method to be used in connecting.  If `auth_set'
 878      boolean is TRUE then authentication data is provided by application.
 879      If the authentication method is public key authentication then the key
 880      pair given as argument when connecting will be used and `auth' field
 881      is NULL.  If it is passphrase authentication, it can be provided in
 882      `auth' and `auth_len' fields.  If `auth_set' is FALSE
 883      the `get_auth_method' client operation will be called to get the
 884      authentication method and data from application. */
 885   SilcBool auth_set;
 886   SilcAuthMethod auth_method;
 887   void *auth;
 888   SilcUInt32 auth_len;
 889
 890   /* If this boolean is set to TRUE then the connection will use UDP instead
 891      of TCP.  If UDP is set then also the next `local_ip' and `local_port'
 892      must be set. */
 893   SilcBool udp;
 894
 895   /* The `local_ip' specifies the local IP address used with the connection.
 896      It must be non-NULL if `udp' boolean is TRUE.  If the `local_port' is
 897      non-zero it will be used as local port with UDP connection.  The remote
 898      host will also send packets to the specified address and port.  If the
 899      `bind_ip' is non-NULL a listener is bound to that address instead of
 900      `local_ip'. */
 901   char *local_ip;
 902   char *bind_ip;
 903   int local_port;
 904
 905   /* If this boolean is set to TRUE then the key exchange is done with
 906      perfect forward secrecy. */
 907   SilcBool pfs;
 908
 909   /* If this boolean is set to TRUE then connection authentication protocol
 910      is not performed during connecting.  Only key exchange protocol is
 911      performed.  This usually must be set to TRUE when connecting to another
 912      client, but must be FALSE with server connections. */
 913   SilcBool no_authentication;
 914
 915   /* The SILC session detachment data that was returned in the `command_reply'
 916      client operation for SILC_COMMAND_DETACH command.  If this is provided
 917      here the client library will attempt to resume the session in the network.
 918      After the connection is created and the session has been resumed the
 919      client will receive SILC_COMMAND_NICK command_reply for the client's
 920      nickname in the network and SILC_COMMAND_JOIN command reply for all the
 921      channels that the client has joined in the network.  It may also receive
 922      SILC_COMMAND_UMODE command reply to set user's mode on the network. */
 923   unsigned char *detach_data;
 924   SilcUInt32 detach_data_len;
 925
 926   /* Connection timeout.  If non-zero, the connection will timeout unless
 927      the SILC connection is completed in the specified amount of time. */
 928   SilcUInt32 timeout_secs;
 929
 930   /* Rekey timeout in seconds.  The client will perform rekey in this
 931      time interval.  If set to zero, the default value will be used
 932      (3600 seconds, 1 hour). */
 933   SilcUInt32 rekey_secs;
 934
 935   /* If this is set to TRUE then the client will ignore all incoming
 936      Requested Attributes queries and does not reply anything back.  This
 937      usually leads into situation where server does not anymore send
 938      the queries after seeing that client does not reply anything back.
 939      If your application does not support Requested Attributes or you do
 940      not want to use them set this to TRUE.  See SilcAttribute and
 941      silc_client_attribute_add for more information on attributes. */
 942   SilcBool ignore_requested_attributes;
 943
 944 } SilcClientConnectionParams;
 945 /***/
 946
 947 /****f* silcclient/SilcClientAPI/silc_client_connect_to_server
 948  *
 949  * SYNOPSIS
 950  *
 951  *    SilcAsyncOperation
 952  *    silc_client_connect_to_server(SilcClient client,
 953  *                                  SilcClientConnectionParams *params,
 954  *                                  SilcPublicKey public_key,
 955  *                                  SilcPrivateKey private_key,
 956  *                                  char *remote_host, int port,
 957  *                                  SilcClientConnectCallback callback,
 958  *                                  void *context);
 959  *
 960  * DESCRIPTION
 961  *
 962  *    Connects to remote server `remote_host' at port `port'.  This function
 963  *    can be used to create connection to remote SILC server and start
 964  *    SILC session in the SILC network.  The `params' may be provided
 965  *    to provide various connection parameters.  The `public_key' and the
 966  *    `private_key' is your identity used in this connection.  When
 967  *    authentication method is based on digital signatures, this key pair
 968  *    will be used.  The `callback' with `context' will be called after the
 969  *    connection has been created.  It will also be called later when remote
 970  *    host disconnects.
 971  *
 972  *    If application wishes to create the network connection itself, use
 973  *    the silc_client_key_exchange after creating the connection to start
 974  *    key exchange and authentication with the server.
 975  *
 976  *    Returns SilcAsyncOperation which can be used to cancel the connecting,
 977  *    or NULL on error.  Note that the returned pointer becomes invalid
 978  *    after the `callback' is called.
 979  *
 980  ***/
 981 SilcAsyncOperation
 982 silc_client_connect_to_server(SilcClient client,
 983                               SilcClientConnectionParams *params,
 984                               SilcPublicKey public_key,
 985                               SilcPrivateKey private_key,
 986                               char *remote_host, int port,
 987                               SilcClientConnectCallback callback,
 988                               void *context);
 989
 990 /****f* silcclient/SilcClientAPI/silc_client_connect_to_client
 991  *
 992  * SYNOPSIS
 993  *
 994  *    SilcAsyncOperation
 995  *    silc_client_connect_to_client(SilcClient client,
 996  *                                  SilcClientConnectionParams *params,
 997  *                                  SilcPublicKey public_key,
 998  *                                  SilcPrivateKey private_key,
 999  *                                  char *remote_host, int port,
1000  *                                  SilcClientConnectCallback callback,
1001  *                                  void *context);
1002  *
1003  * DESCRIPTION
1004  *
1005  *    Connects to remote client `remote_host' at port `port'.  This function
1006  *    can be used to create peer-to-peer connection to another SILC client,
1007  *    for example, for direct conferencing, or file transfer or for other
1008  *    purposes.  The `params' may be provided to provide various connection
1009  *    parameters.  The `public_key' and the `private_key' is your identity
1010  *    used in this connection.  The `callback' with `context' will be called
1011  *    after the connection has been created.  It will also be called later
1012  *    when remote host disconnects.
1013  *
1014  *    If application wishes to create the network connection itself, use
1015  *    the silc_client_key_exchange after creating the connection to start
1016  *    key exchange with the client.
1017  *
1018  *    Returns SilcAsyncOperation which can be used to cancel the connecting,
1019  *    or NULL on error.  Note that the returned pointer becomes invalid
1020  *    after the `callback' is called.
1021  *
1022  ***/
1023 SilcAsyncOperation
1024 silc_client_connect_to_client(SilcClient client,
1025                               SilcClientConnectionParams *params,
1026                               SilcPublicKey public_key,
1027                               SilcPrivateKey private_key,
1028                               char *remote_host, int port,
1029                               SilcClientConnectCallback callback,
1030                               void *context);
1031
1032 /****f* silcclient/SilcClientAPI/silc_client_key_exchange
1033  *
1034  * SYNOPSIS
1035  *
1036  *    SilcAsyncOperation
1037  *    silc_client_key_exchange(SilcClient client,
1038  *                             SilcClientConnectionParams *params,
1039  *                             SilcPublicKey public_key,
1040  *                             SilcPrivateKey private_key,
1041  *                             SilcStream stream,
1042  *                             SilcConnectionType conn_type,
1043  *                             SilcClientConnectCallback callback,
1044  *                             void *context);
1045  *
1046  * DESCRIPTION
1047  *
1048  *    Starts key exchange protocol and authentication protocol in the
1049  *    connection indicated by `stream'.  This function can be be used to
1050  *    start SILC session with remote host (usually server) when the caller
1051  *    has itself created the connection, instead of calling the function
1052  *    silc_client_connect_to_server or silc_client_connect_to_client.  If
1053  *    one of those functions was used this function must not be called as
1054  *    in that case the key exchange is performed automatically.
1055  *
1056  *    Use this function only if you have created the connection by yourself.
1057  *    After creating the connection the socket must be wrapped into a
1058  *    socket stream.  See silcsocketstream.h for more information.  Note that
1059  *    the `stream' must have valid remote IP address (and optionally also
1060  *    hostname) and port set.
1061  *
1062  *    The `params' may be provided to provide various connection parameters.
1063  *    The `public_key' and the `private_key' is your identity used in this
1064  *    session.  The `callback' with `context' will be called after the session
1065  *    has been set up.  It will also be called later when remote host
1066  *    disconnects.  The `conn_type' is the type of session this is going to
1067  *    be.
1068  *
1069  *    Returns SilcAsyncOperation which can be used to cancel the connecting,
1070  *    or NULL on error.  Note that the returned pointer becomes invalid
1071  *    after the `callback' is called.
1072  *
1073  * EXAMPLE
1074  *
1075  *    int sock;
1076  *
1077  *    // Create remote connection stream.  Resolve hostname and IP also.
1078  *    sock = create_connection(remote_host, port);
1079  *    silc_socket_tcp_stream_create(sock, TRUE, FALSE, schedule,
1080  *                                  stream_create_cb, app);
1081  *
1082  *    // Stream callback delivers our new SilcStream context
1083  *    void stream_create_cb(SilcSocketStreamStatus status, SilcStream stream,
1084  *                          void *context)
1085  *    {
1086  *      ...
1087  *      if (status != SILC_SOCKET_OK)
1088  *        error(status);
1089  *
1090  *      // Start key exchange
1091  *      silc_client_key_exchange(client, NULL, public_key, private_key,
1092  *                               stream, SILC_CONN_SERVER, connection_cb, app);
1093  *      ...
1094  *    }
1095  *
1096  ***/
1097 SilcAsyncOperation
1098 silc_client_key_exchange(SilcClient client,
1099                          SilcClientConnectionParams *params,
1100                          SilcPublicKey public_key,
1101                          SilcPrivateKey private_key,
1102                          SilcStream stream,
1103                          SilcConnectionType conn_type,
1104                          SilcClientConnectCallback callback,
1105                          void *context);
1106
1107 /****f* silcclient/SilcClientAPI/silc_client_close_connection
1108  *
1109  * SYNOPSIS
1110  *
1111  *    void silc_client_close_connection(SilcClient client,
1112  *                                      SilcClientConnection conn);
1113  *
1114  * DESCRIPTION
1115  *
1116  *    Closes the remote connection `conn'.  The `conn' will become invalid
1117  *    after this call.  Usually this function is called only when explicitly
1118  *    closing connection for example in case of error, or when the remote
1119  *    connection was created by the application or when the remote is client
1120  *    connection.  Server connections are usually closed by sending QUIT
1121  *    command to the server.  However, this call may also be used.
1122  *
1123  ***/
1124 void silc_client_close_connection(SilcClient client,
1125                                   SilcClientConnection conn);
1126
1127 /* Message sending functions */
1128
1129 /****f* silcclient/SilcClientAPI/silc_client_send_channel_message
1130  *
1131  * SYNOPSIS
1132  *
1133  *    SilcBool silc_client_send_channel_message(SilcClient client,
1134  *                                              SilcClientConnection conn,
1135  *                                              SilcChannelEntry channel,
1136  *                                              SilcChannelPrivateKey key,
1137  *                                              SilcMessageFlags flags,
1138  *                                              SilcHash hash,
1139  *                                              unsigned char *data,
1140  *                                              SilcUInt32 data_len);
1141  *
1142  * DESCRIPTION
1143  *
1144  *    Sends packet to the `channel'. Packet to channel is always encrypted
1145  *    differently from "normal" packets. SILC header of the packet is
1146  *    encrypted with the next receiver's key and the rest of the packet is
1147  *    encrypted with the channel specific key. Padding and HMAC is computed
1148  *    with the next receiver's key. The `data' is the channel message.
1149  *
1150  *    If `key' is provided then that private key is used to encrypt the
1151  *    channel message.  If it is not provided, private keys has not been
1152  *    set at all, the normal channel key is used automatically.  If private
1153  *    keys are set then the first key (the key that was added first as
1154  *    private key) is used.
1155  *
1156  *    If the `flags' includes SILC_MESSAGE_FLAG_SIGNED the message will be
1157  *    digitally signed with the SILC key pair.  In this case the `hash'
1158  *    pointer must be provided as well.
1159  *
1160  *    Returns TRUE if the message was sent, and FALSE if error occurred or
1161  *    the sending is not allowed due to channel modes (like sending is
1162  *    blocked).  This function is thread safe and private messages can be
1163  *    sent from multiple threads.
1164  *
1165  ***/
1166 SilcBool silc_client_send_channel_message(SilcClient client,
1167                                           SilcClientConnection conn,
1168                                           SilcChannelEntry channel,
1169                                           SilcChannelPrivateKey key,
1170                                           SilcMessageFlags flags,
1171                                           SilcHash hash,
1172                                           unsigned char *data,
1173                                           SilcUInt32 data_len);
1174
1175 /****f* silcclient/SilcClientAPI/silc_client_send_private_message
1176  *
1177  * SYNOPSIS
1178  *
1179  *    SilcBool silc_client_send_private_message(SilcClient client,
1180  *                                              SilcClientConnection conn,
1181  *                                              SilcClientEntry client_entry,
1182  *                                              SilcMessageFlags flags,
1183  *                                              SilcHash hash,
1184  *                                              unsigned char *data,
1185  *                                              SilcUInt32 data_len);
1186  *
1187  * DESCRIPTION
1188  *
1189  *    Sends private message to remote client. If private message key has
1190  *    not been set with this client then the message will be encrypted using
1191  *    normal session keys.  If the `flags' includes SILC_MESSAGE_FLAG_SIGNED
1192  *    the message will be digitally signed with the SILC key pair.  In this
1193  *    case the caller must also provide the `hash' pointer.
1194  *
1195  *    Returns TRUE if the message was sent, and FALSE if error occurred.
1196  *    This function is thread safe and private messages can be sent from
1197  *    multiple threads.
1198  *
1199  ***/
1200 SilcBool silc_client_send_private_message(SilcClient client,
1201                                           SilcClientConnection conn,
1202                                           SilcClientEntry client_entry,
1203                                           SilcMessageFlags flags,
1204                                           SilcHash hash,
1205                                           unsigned char *data,
1206                                           SilcUInt32 data_len);
1207
1208 /****f* silcclient/SilcClientAPI/silc_client_private_message_wait_init
1209  *
1210  * SYNOPSIS
1211  *
1212  *    SilcBool
1213  *    silc_client_private_message_wait_init(SilcClient client,
1214  *                                          SilcClientConnection conn);
1215  *
1216  * DESCRIPTION
1217  *
1218  *    Initializes private message waiting functionality for the connection
1219  *    indicated by `conn'.  Once this is called private message from remote
1220  *    connection indicated by `conn' for any client entry beloning to that
1221  *    connection may be waited for, for example in an thread.  The function
1222  *    silc_client_private_message_wait is used to block the current thread
1223  *    until a private message is received from a specified client entry.
1224  *    Return FALSE on error.
1225  *
1226  ***/
1227 SilcBool silc_client_private_message_wait_init(SilcClient client,
1228                                                SilcClientConnection conn);
1229
1230 /****f* silcclient/SilcClientAPI/silc_client_private_message_wait_uninit
1231  *
1232  * SYNOPSIS
1233  *
1234  *    void
1235  *    silc_client_private_message_wait_uninit(SilcClient client,
1236  *                                            SilcClientConnection conn);
1237  *
1238  * DESCRIPTION
1239  *
1240  *    Unintializes private message waiting for connection indicated by
1241  *    `conn'.  After this call private message cannot be waited anymore.
1242  *    This call may be called from any thread.  This call will signal all
1243  *    private message waiting threads to stop waiting.
1244  *
1245  ***/
1246 void silc_client_private_message_wait_uninit(SilcClient client,
1247                                              SilcClientConnection conn);
1248
1249 /****f* silcclient/SilcClientAPI/silc_client_private_message_wait
1250  *
1251  * SYNOPSIS
1252  *
1253  *    SilcBool
1254  *    silc_client_private_message_wait(SilcClient client,
1255  *                                     SilcClientConnection conn,
1256  *                                     SilcClientEntry client_entry,
1257  *                                     SilcMessagePayload *payload);
1258  *
1259  * DESCRIPTION
1260  *
1261  *    Blocks current thread or process until a private message has been
1262  *    received from the remote client indicated by `client_entry'.  Before
1263  *    private messages can be waited the silc_client_private_message_wait_init
1264  *    must be called.  This function can be used from a thread to wait for
1265  *    private message from the specified client.  Multiple threads can be
1266  *    created to wait messages from multiple clients.  Any other private
1267  *    message received from the connection indicated by `conn' will be
1268  *    forwarded to the normal `private_message' client operation.  The
1269  *    private messages from `client_entry' will not be delivered to the
1270  *    `private_message' client operation.
1271  *
1272  *    Returns TRUE and the received private message into `payload'.  The caller
1273  *    must free the returned SilcMessagePayload.  If this function returns
1274  *    FALSE the private messages cannot be waited anymore.  This happens
1275  *    when some other thread calls silc_client_private_message_wait_uninit.
1276  *    This returns FALSE also if silc_client_private_message_wait_init has
1277  *    not been called.
1278  *
1279  ***/
1280 SilcBool silc_client_private_message_wait(SilcClient client,
1281                                           SilcClientConnection conn,
1282                                           SilcClientEntry client_entry,
1283                                           SilcMessagePayload *payload);
1284
1285 /****f* silcclient/SilcClientAPI/silc_client_on_channel
1286  *
1287  * SYNOPSIS
1288  *
1289  *    SilcChannelUser silc_client_on_channel(SilcChannelEntry channel,
1290  *                                           SilcClientEntry client_entry);
1291  *
1292  * DESCRIPTION
1293  *
1294  *    Returns the SilcChannelUser entry if the `client_entry' is joined on the
1295  *    channel indicated by the `channel'. NULL if client is not joined on
1296  *    the channel.
1297  *
1298  ***/
1299 SilcChannelUser silc_client_on_channel(SilcChannelEntry channel,
1300                                        SilcClientEntry client_entry);
1301
1302
1303 /* Command management */
1304
1305 /****f* silcclient/SilcClientAPI/silc_client_command_call
1306  *
1307  * SYNOPSIS
1308  *
1309  *    SilcUInt16 silc_client_command_call(SilcClient client,
1310  *                                        SilcClientConnection conn,
1311  *                                        const char *command_line, ...);
1312  *
1313  * DESCRIPTION
1314  *
1315  *    Calls and executes the command indicated by the `command_name'.
1316  *    The `command_line' is a string which includes the command's name and
1317  *    its arguments separated with whitespaces (' ').  If `command_line'
1318  *    is non-NULL then all variable arguments are ignored by default.
1319  *
1320  *    If `command_line' is NULL, then the variable arguments define the
1321  *    command's name and its arguments.  The first variable argument must
1322  *    be the command name.  The variable argument list must be terminated
1323  *    with NULL.
1324  *
1325  *    Returns FALSE if the command is not known and TRUE after command.
1326  *    execution.  The "command" client operation is called when the
1327  *    command is executed to indicate whether the command executed
1328  *    successfully or not.
1329  *
1330  *    The "command_reply" client operation will be called when reply is
1331  *    received from the server to the command.  Application may also use
1332  *    the silc_client_command_pending to attach to the command reply.
1333  *    The command identifier for silc_client_command_pending function after
1334  *    this function call is conn->cmd_ident, which application may use.
1335  *
1336  * EXAMPLE
1337  *
1338  *    silc_client_command_call(client, conn, NULL, "PING", "silc.silcnet.org",
1339  *                             NULL);
1340  *    silc_client_command_call(client, conn, "PING silc.silcnet.org");
1341  *
1342  * NOTES
1343  *
1344  *    This command executes the commands implemented inside the client
1345  *    library.  These commands are designed for command line applications,
1346  *    but GUI application may call them too if needed.  Alternatively
1347  *    application may override the library and use silc_client_command_send
1348  *    function instead.
1349  *
1350  ***/
1351 SilcUInt16 silc_client_command_call(SilcClient client,
1352                                     SilcClientConnection conn,
1353                                     const char *command_line, ...);
1354
1355 /****f* silcclient/SilcClientAPI/SilcClientCommandReply
1356  *
1357  * SYNOPSIS
1358  *
1359  *    typedef SilcBool (*SilcClientCommandReply)(SilcClient client,
1360  *                                               SilcClientConnection conn,
1361  *                                               SilcCommand command,
1362  *                                               SilcStatus status,
1363  *                                               SilcStatus error,
1364  *                                               void *context,
1365  *                                               va_list ap);
1366  *
1367  * DESCRIPTION
1368  *
1369  *    The command reply callback function given as argument to functions
1370  *    silc_client_command_send and silc_client_command_pending.  This is
1371  *    called to deliver the command replies to the caller.  Each command
1372  *    reply received from the server to the `command' will be delivered
1373  *    separately to the caller by calling this callback.  The `status' will
1374  *    indicate whether there is only one reply or multiple replies.  The
1375  *    `error' will indicate if an error occurred.  The `ap' will include
1376  *    command reply arguments.  They are the same arguments as for
1377  *    `command_reply' client operation in SilcClientOperations.
1378  *
1379  *    If `status' is SILC_STATUS_OK only one reply was received and error
1380  *    did not occur.  If it is SILC_STATUS_LIST_START, SILC_STATUS_LIST_ITEM
1381  *    or SILC_STATUS_LIST_END, there are will be two or more replies.  The
1382  *    first reply is SILC_STATUS_LIST_START and last one SILC_STATUS_LIST_END.
1383  *
1384  *    If FALSE is returned in this function this callback will not be called
1385  *    again for `command' even if there are more comand replies.  By returning
1386  *    FALSE the caller my stop the command reply handling when needed.
1387  *
1388  ***/
1389 typedef SilcBool (*SilcClientCommandReply)(SilcClient client,
1390                                            SilcClientConnection conn,
1391                                            SilcCommand command,
1392                                            SilcStatus status,
1393                                            SilcStatus error,
1394                                            void *context,
1395                                            va_list ap);
1396
1397 /****f* silcclient/SilcClientAPI/silc_client_command_send
1398  *
1399  * SYNOPSIS
1400  *
1401  *    SilcUInt16 silc_client_command_send(SilcClient client,
1402  *                                        SilcClientConnection conn,
1403  *                                        SilcCommand command,
1404  *                                        SilcClientCommandReply reply,
1405  *                                        void *reply_context,
1406  *                                        SilcUInt32 argc, ...);
1407  *
1408  * DESCRIPTION
1409  *
1410  *    Generic function to send any command.  The arguments must be given
1411  *    already encoded into correct format and in correct order. If application
1412  *    wants to perform the commands by itself, it can do so and send the data
1413  *    directly to the server using this function.  If application is using
1414  *    the silc_client_command_call, this function is usually not used.
1415  *    Programmer should get familiar with the SILC protocol commands
1416  *    specification when using this function, as the arguments needs to
1417  *    be encoded as specified in the protocol.
1418  *
1419  *    The variable arguments are a set of { type, data, data_length },
1420  *    and the `argc' is the number of these sets.
1421  *
1422  *    The `reply' callback must be provided, and it is called when the
1423  *    command reply is received from the server.  Note that, when using this
1424  *    function the default `command_reply' client operation will not be
1425  *    called, when reply is received.
1426  *
1427  *    Returns command identifier for this sent command.  It can be used
1428  *    to additionally attach to the command reply using the function
1429  *    silc_client_command_pending, if needed.  Returns 0 on error,
1430  *
1431  * EXAMPLE
1432  *
1433  *    silc_client_command_send(client, conn, SILC_COMMAND_WHOIS,
1434  *                             my_whois_command_reply, cmd_ctx,
1435  *                             1, 1, nickname, strlen(nickname));
1436  *
1437  ***/
1438 SilcUInt16 silc_client_command_send(SilcClient client,
1439                                     SilcClientConnection conn,
1440                                     SilcCommand command,
1441                                     SilcClientCommandReply reply,
1442                                     void *reply_context,
1443                                     SilcUInt32 argc, ...);
1444
1445 /****f* silcclient/SilcClientAPI/silc_client_command_pending
1446  *
1447  * SYNOPSIS
1448  *
1449  *    void silc_client_command_pending(SilcClientConnection conn,
1450  *                                     SilcCommand reply_cmd,
1451  *                                     SilcUInt16 cmd-ident,
1452  *                                     SilcCommandCb callback,
1453  *                                     void *context);
1454  *
1455  * DESCRIPTION
1456  *
1457  *    This function can be used to add pending command callback to be
1458  *    called when an command reply is received to an earlier sent command.
1459  *    The `reply_cmd' is the command that must be received in order for
1460  *    the pending command callback indicated by `callback' to be called.
1461  *    The `callback' will deliver the `context' and
1462  *    SilcClientCommandReplyContext which includes the internals of the
1463  *    command reply.
1464  *
1465  *    The `cmd_ident' is a command identifier which was set for the earlier
1466  *    sent command.  The command reply will include the same identifier
1467  *    and pending command callback will be called when the reply is
1468  *    received with the same command identifier.  It is possible to
1469  *    add multiple pending command callbacks for same command and for
1470  *    same identifier.
1471  *
1472  *    Application may use this function to add its own command reply
1473  *    handlers if it wishes not to use the standard `command_reply'
1474  *    client operation.  However, note that the pending command callback
1475  *    does not deliver parsed command reply, but application must parse
1476  *    it itself.
1477  *
1478  *    Note also that the application is notified about the received command
1479  *    reply through the `command_reply' client operation before calling
1480  *    the `callback` pending command callback.  That is the normal
1481  *    command reply handling, and is called regardless whether pending
1482  *    command callbacks are used or not.
1483  *
1484  *    Commands that application calls with silc_client_command_call
1485  *    will use a command identifier from conn->cmd_ident variable.  After
1486  *    calling the silc_client_command_call, the conn->cmd_ident includes
1487  *    the command identifier that was used for the command sending.
1488  *
1489  * EXAMPLE
1490  *
1491  *    silc_client_command_call(client, conn, "PING silc.silcnet.org");
1492  *    silc_client_command_pending(conn, SILC_COMMAND_PING, conn->cmd_ident,
1493  *                                my_ping_handler, my_ping_context);
1494  *
1495  ***/
1496 SilcBool silc_client_command_pending(SilcClientConnection conn,
1497                                      SilcCommand command,
1498                                      SilcUInt16 cmd_ident,
1499                                      SilcClientCommandReply reply,
1500                                      void *context);
1501
1502
1503 /* Private Message key management */
1504
1505 /****f* silcclient/SilcClientAPI/silc_client_add_private_message_key
1506  *
1507  * SYNOPSIS
1508  *
1509  *    SilcBool
1510  *    silc_client_add_private_message_key(SilcClient client,
1511  *                                        SilcClientConnection conn,
1512  *                                        SilcClientEntry client_entry,
1513  *                                        const char *cipher,
1514  *                                        const char *hmac,
1515  *                                        unsigned char *key,
1516  *                                        SilcUInt32 key_len);
1517  *
1518  * DESCRIPTION
1519  *
1520  *    Adds a static private message key to the client library.  The key
1521  *    will be used to encrypt all private message between the client and
1522  *    the remote client indicated by the `client_entry'.  The `key' can
1523  *    be for example a pre-shared-key, passphrase or similar shared secret
1524  *    string.  The `cipher' and `hmac' MAY be provided but SHOULD be NULL
1525  *    to assure that the requirements of the SILC protocol are met. The
1526  *    API, however, allows to allocate any cipher and HMAC.
1527  *
1528  *    If the private message key is added to client without first receiving
1529  *    a request for it from the remote `client_entry' this function will
1530  *    send the request to `client_entry'.  Note that, the actual key is
1531  *    not sent to the network.
1532  *
1533  *    It is not necessary to set key for normal private message usage. If the
1534  *    key is not set then the private messages are encrypted using normal
1535  *    session keys.  Setting the private key, however, increases the security.
1536  *
1537  *    Returns FALSE if the key is already set for the `client_entry', TRUE
1538  *    otherwise.
1539  *
1540  ***/
1541 SilcBool silc_client_add_private_message_key(SilcClient client,
1542                                              SilcClientConnection conn,
1543                                              SilcClientEntry client_entry,
1544                                              const char *cipher,
1545                                              const char *hmac,
1546                                              unsigned char *key,
1547                                              SilcUInt32 key_len);
1548
1549 /****f* silcclient/SilcClientAPI/silc_client_add_private_message_key_ske
1550  *
1551  * SYNOPSIS
1552  *
1553  *    SilcBool
1554  *    silc_client_add_private_message_key_ske(SilcClient client,
1555  *                                            SilcClientConnection conn,
1556  *                                            SilcClientEntry client_entry,
1557  *                                            const char *cipher,
1558  *                                            const char *hmac,
1559  *                                            SilcSKEKeyMaterial key);
1560  *
1561  * DESCRIPTION
1562  *
1563  *    Same as silc_client_add_private_message_key but takes the key material
1564  *    from the SKE key material structure.  This structure is received if
1565  *    the application uses the silc_client_send_key_agreement to negotiate
1566  *    the key material.  The `cipher' and `hmac' SHOULD be provided as it is
1567  *    negotiated also in the SKE protocol.
1568  *
1569  ***/
1570 SilcBool silc_client_add_private_message_key_ske(SilcClient client,
1571                                                  SilcClientConnection conn,
1572                                                  SilcClientEntry client_entry,
1573                                                  const char *cipher,
1574                                                  const char *hmac,
1575                                                  SilcSKEKeyMaterial key);
1576
1577 /****f* silcclient/SilcClientAPI/silc_client_del_private_message_key
1578  *
1579  * SYNOPSIS
1580  *
1581  *    SilcBool silc_client_del_private_message_key(SilcClient client,
1582  *                                             SilcClientConnection conn,
1583  *                                             SilcClientEntry client_entry);
1584  *
1585  * DESCRIPTION
1586  *
1587  *    Removes the private message from the library. The key won't be used
1588  *    after this to protect the private messages with the remote `client_entry'
1589  *    client. Returns FALSE on error, TRUE otherwise.
1590  *
1591  ***/
1592 SilcBool silc_client_del_private_message_key(SilcClient client,
1593                                              SilcClientConnection conn,
1594                                              SilcClientEntry client_entry);
1595
1596 /****f* silcclient/SilcClientAPI/silc_client_list_private_message_keys
1597  *
1598  * SYNOPSIS
1599  *
1600  *    SilcPrivateMessageKeys
1601  *    silc_client_list_private_message_keys(SilcClient client,
1602  *                                          SilcClientConnection conn,
1603  *                                          SilcUInt32 *key_count);
1604  *
1605  * DESCRIPTION
1606  *
1607  *    Returns array of set private message keys associated to the connection
1608  *    `conn'. Returns allocated SilcPrivateMessageKeys array and the array
1609  *    count to the `key_count' argument. The array must be freed by the caller
1610  *    by calling the silc_client_free_private_message_keys function. Note:
1611  *    the keys returned in the array is in raw format. It might not be desired
1612  *    to show the keys as is. The application might choose not to show the keys
1613  *    at all or to show the fingerprints of the keys.
1614  *
1615  ***/
1616 SilcPrivateMessageKeys
1617 silc_client_list_private_message_keys(SilcClient client,
1618                                       SilcClientConnection conn,
1619                                       SilcUInt32 *key_count);
1620
1621 /****f* silcclient/SilcClientAPI/silc_client_free_private_message_keys
1622  *
1623  * SYNOPSIS
1624  *
1625  *    void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys,
1626  *                                               SilcUInt32 key_count);
1627  *
1628  * DESCRIPTION
1629  *
1630  *    Frees the SilcPrivateMessageKeys array returned by the function
1631  *    silc_client_list_private_message_keys.
1632  *
1633  ***/
1634 void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys,
1635                                            SilcUInt32 key_count);
1636
1637
1638 /* Channel private key management */
1639
1640 /****f* silcclient/SilcClientAPI/silc_client_add_channel_private_key
1641  *
1642  * SYNOPSIS
1643  *
1644  *    SilcBool silc_client_add_channel_private_key(SilcClient client,
1645  *                                             SilcClientConnection conn,
1646  *                                             SilcChannelEntry channel,
1647  *                                             const char *name,
1648  *                                             char *cipher,
1649  *                                             char *hmac,
1650  *                                             unsigned char *key,
1651  *                                             SilcUInt32 key_len,
1652  *                                             SilcChannelPrivateKey *ret_key);
1653  *
1654  * DESCRIPTION
1655  *
1656  *    Adds private key for channel. When channel has private key then the
1657  *    messages are encrypted using that key. All clients on the channel
1658  *    must also know the key in order to decrypt the messages. However,
1659  *    it is possible to have several private keys per one channel. In this
1660  *    case only some of the clients on the channel may know the one key
1661  *    and only some the other key.  The `name' can be application given
1662  *    name for the key.  This returns the created key to the 'ret_key'
1663  *    pointer if it is non-NULL;
1664  *
1665  *    If `cipher' and/or `hmac' is NULL then default values will be used
1666  *    (aes-256-cbc for cipher and hmac-sha1-96 for hmac).
1667  *
1668  *    The private key for channel is optional. If it is not set then the
1669  *    channel messages are encrypted using the channel key generated by the
1670  *    server. However, setting the private key (or keys) for the channel
1671  *    significantly adds security. If more than one key is set the library
1672  *    will automatically try all keys at the message decryption phase. Note:
1673  *    setting many keys slows down the decryption phase as all keys has to
1674  *    be tried in order to find the correct decryption key. However, setting
1675  *    a few keys does not have big impact to the decryption performace.
1676  *
1677  * NOTES
1678  *
1679  *    NOTE: This is entirely local setting. The key set using this function
1680  *    is not sent to the network at any phase.
1681  *
1682  *    NOTE: If the key material was originated by the SKE protocol (using
1683  *    silc_client_send_key_agreement) then the `key' MUST be the
1684  *    key->send_enc_key as this is dictated by the SILC protocol. However,
1685  *    currently it is not expected that the SKE key material would be used
1686  *    as channel private key. However, this API allows it.
1687  *
1688  ***/
1689 SilcBool silc_client_add_channel_private_key(SilcClient client,
1690                                              SilcClientConnection conn,
1691                                              SilcChannelEntry channel,
1692                                              const char *name,
1693                                              char *cipher,
1694                                              char *hmac,
1695                                              unsigned char *key,
1696                                              SilcUInt32 key_len,
1697                                              SilcChannelPrivateKey *ret_key);
1698
1699 /****f* silcclient/SilcClientAPI/silc_client_del_channel_private_keys
1700  *
1701  * SYNOPSIS
1702  *
1703  *    SilcBool silc_client_del_channel_private_keys(SilcClient client,
1704  *                                              SilcClientConnection conn,
1705  *                                              SilcChannelEntry channel);
1706  *
1707  * DESCRIPTION
1708  *
1709  *    Removes all private keys from the `channel'. The old channel key is used
1710  *    after calling this to protect the channel messages. Returns FALSE on
1711  *    on error, TRUE otherwise.
1712  *
1713  ***/
1714 SilcBool silc_client_del_channel_private_keys(SilcClient client,
1715                                               SilcClientConnection conn,
1716                                               SilcChannelEntry channel);
1717
1718 /****f* silcclient/SilcClientAPI/silc_client_del_channel_private_key
1719  *
1720  * SYNOPSIS
1721  *
1722  *    SilcBool silc_client_del_channel_private_key(SilcClient client,
1723  *                                            SilcClientConnection conn,
1724  *                                            SilcChannelEntry channel,
1725  *                                            SilcChannelPrivateKey key);
1726  *
1727  * DESCRIPTION
1728  *
1729  *    Removes and frees private key `key' from the channel `channel'.
1730  *    The `key' is retrieved by calling the function
1731  *    silc_client_list_channel_private_keys. The key is not used after
1732  *    this. If the key was last private key then the old channel key is
1733  *    used hereafter to protect the channel messages. This returns FALSE
1734  *    on error, TRUE otherwise.
1735  *
1736  ***/
1737 SilcBool silc_client_del_channel_private_key(SilcClient client,
1738                                              SilcClientConnection conn,
1739                                              SilcChannelEntry channel,
1740                                              SilcChannelPrivateKey key);
1741
1742 /****f* silcclient/SilcClientAPI/silc_client_list_channel_private_keys
1743  *
1744  * SYNOPSIS
1745  *
1746  *    SilcDList
1747  *    silc_client_list_channel_private_keys(SilcClient client,
1748  *                                          SilcClientConnection conn,
1749  *                                          SilcChannelEntry channel);
1750  *
1751  * DESCRIPTION
1752  *
1753  *    Returns list of private keys associated to the `channel'.  The caller
1754  *    must free the returned list with silc_dlist_uninit.  The pointers in
1755  *    the list may be used to delete the specific key by giving the pointer
1756  *    as argument to the function silc_client_del_channel_private_key.  Each
1757  *    entry in the list is SilcChannelPrivateKey.
1758  *
1759  ***/
1760 SilcDList silc_client_list_channel_private_keys(SilcClient client,
1761                                                 SilcClientConnection conn,
1762                                                 SilcChannelEntry channel);
1763
1764 /****f* silcclient/SilcClientAPI/silc_client_current_channel_private_key
1765  *
1766  * SYNOPSIS
1767  *
1768  *    void silc_client_current_channel_private_key(SilcClient client,
1769  *                                                 SilcClientConnection conn,
1770  *                                                 SilcChannelEntry channel,
1771  *                                                 SilcChannelPrivateKey key);
1772  *
1773  * DESCRIPTION
1774  *
1775  *    Sets the `key' to be used as current channel private key on the
1776  *    `channel'.  Packet sent after calling this function will be secured
1777  *    with `key'.
1778  *
1779  ***/
1780 void silc_client_current_channel_private_key(SilcClient client,
1781                                              SilcClientConnection conn,
1782                                              SilcChannelEntry channel,
1783                                              SilcChannelPrivateKey key);
1784
1785
1786 /* Key Agreement routines */
1787
1788 /****f* silcclient/SilcClientAPI/silc_client_send_key_agreement
1789  *
1790  * SYNOPSIS
1791  *
1792  *    void silc_client_send_key_agreement(SilcClient client,
1793  *                                        SilcClientConnection conn,
1794  *                                        SilcClientEntry client_entry,
1795  *                                        SilcClientConnectionParams *params,
1796  *                                        SilcPublicKey public_key,
1797  *                                        SilcPrivateKey private_key,
1798  *                                        SilcKeyAgreementCallback completion,
1799  *                                        void *context);
1800  *
1801  * DESCRIPTION
1802  *
1803  *    Sends key agreement request to the remote client indicated by the
1804  *    `client_entry'.
1805  *
1806  *    If `params' is non-NULL and it has the `local_ip' and `local_port' set
1807  *    the caller will provide the connection endpoint for the key agreement
1808  *    connection.  The `bind_ip' can be used to bind to that IP instead of
1809  *    `local_ip'.  If the `udp' is set to TRUE the connection will be UDP
1810  *    instead of TCP.  Caller may also set the `repository', `verify_notfound'
1811  *    and `timeout_secs' fields in `params'.  Other fields are ignored.
1812  *    If `params' is NULL, then the `client_entry' is expected to provide
1813  *    the connection endpoint for us.  It is recommended the `timeout_secs'
1814  *    is specified in case the remote client does not reply anything to
1815  *    the request.
1816  *
1817  *    The `public_key' and `private_key' is our identity in the key agreement.
1818  *
1819  *    In case we do not provide the connection endpoint, we will receive
1820  *    the `key_agreement' client operation when the remote send its own
1821  *    key agreement request packet.  We may then there start the key
1822  *    agreement with silc_client_perform_key_agreement.  If we provided the
1823  *    the connection endpoint, the client operation will not be called.
1824  *
1825  *    There can be only one active key agreement for `client_entry'.  Old
1826  *    key agreement may be aborted by calling silc_client_abort_key_agreement.
1827  *
1828  * EXAMPLE
1829  *
1830  *    // Send key agreement request (we don't provide connection endpoint)
1831  *    silc_client_send_key_agreement(client, conn, remote_client,
1832  *                                   NULL, public_key, private_key,
1833  *                                   my_keyagr_completion, my_context);
1834  *
1835  *    // Another example where we provide connection endpoint (TCP).
1836  *    SilcClientConnectionParams params;
1837  *    memset(&params, 0, sizeof(params));
1838  *    params.local_ip = local_ip;
1839  *    params.local_port = local_port;
1840  *    params.timeout_secs = 60;
1841  *    silc_client_send_key_agreement(client, conn, remote_client,
1842  *                                   &params, public_key, private_key,
1843  *                                   my_keyagr_completion, my_context);
1844  *
1845  ***/
1846 void silc_client_send_key_agreement(SilcClient client,
1847                                     SilcClientConnection conn,
1848                                     SilcClientEntry client_entry,
1849                                     SilcClientConnectionParams *params,
1850                                     SilcPublicKey public_key,
1851                                     SilcPrivateKey private_key,
1852                                     SilcKeyAgreementCallback completion,
1853                                     void *context);
1854
1855 /****f* silcclient/SilcClientAPI/silc_client_perform_key_agreement
1856  *
1857  * SYNOPSIS
1858  *
1859  *    void
1860  *    silc_client_perform_key_agreement(SilcClient client,
1861  *                                      SilcClientConnection conn,
1862  *                                      SilcClientEntry client_entry,
1863  *                                      SilcClientConnectionParams *params,
1864  *                                      SilcPublicKey public_key,
1865  *                                      SilcPrivateKey private_key,
1866  *                                      char *hostname, int port,
1867  *                                      SilcKeyAgreementCallback completion,
1868  *                                      void *context);
1869  *
1870  * DESCRIPTION
1871  *
1872  *    Performs the key agreement protocol.  Application may use this to
1873  *    initiate the key agreement protocol.  Usually this is called after
1874  *    receiving the `key_agreement' client operation.
1875  *
1876  *    The `hostname' is the remote hostname (or IP address) and the `port'
1877  *    is the remote port.  The `completion' callback with the `context' will
1878  *    be called after the key agreement protocol.
1879  *
1880  *    The `params' is connection parameters and it may be used to define
1881  *    the key agreement connection related parameters.  It may be NULL.
1882  *
1883  ***/
1884 void silc_client_perform_key_agreement(SilcClient client,
1885                                        SilcClientConnection conn,
1886                                        SilcClientEntry client_entry,
1887                                        SilcClientConnectionParams *params,
1888                                        SilcPublicKey public_key,
1889                                        SilcPrivateKey private_key,
1890                                        char *hostname, int port,
1891                                        SilcKeyAgreementCallback completion,
1892                                        void *context);
1893
1894 /****f* silcclient/SilcClientAPI/silc_client_perform_key_agreement_stream
1895  *
1896  * SYNOPSIS
1897  *
1898  *    void
1899  *    silc_client_perform_key_agreement_stream(
1900  *                                      SilcClient client,
1901  *                                      SilcClientConnection conn,
1902  *                                      SilcClientEntry client_entry,
1903  *                                      SilcClientConnectionParams *params,
1904  *                                      SilcPublicKey public_key,
1905  *                                      SilcPrivateKey private_key,
1906  *                                      SilcStream stream,
1907  *                                      SilcKeyAgreementCallback completion,
1908  *                                      void *context);
1909  *
1910  * DESCRIPTION
1911  *
1912  *    Same as silc_client_perform_key_agreement but the caller has created
1913  *    the connection.  The `stream' is the created connection.
1914  *
1915  ***/
1916 void
1917 silc_client_perform_key_agreement_stream(SilcClient client,
1918                                          SilcClientConnection conn,
1919                                          SilcClientEntry client_entry,
1920                                          SilcClientConnectionParams *params,
1921                                          SilcPublicKey public_key,
1922                                          SilcPrivateKey private_key,
1923                                          SilcStream stream,
1924                                          SilcKeyAgreementCallback completion,
1925                                          void *context);
1926
1927 /****f* silcclient/SilcClientAPI/silc_client_abort_key_agreement
1928  *
1929  * SYNOPSIS
1930  *
1931  *    void silc_client_abort_key_agreement(SilcClient client,
1932  *                                         SilcClientConnection conn,
1933  *                                         SilcClientEntry client_entry);
1934  *
1935  * DESCRIPTION
1936  *
1937  *    This function can be called to unbind the hostname and the port for
1938  *    the key agreement protocol. However, this function has effect only
1939  *    before the key agreement protocol has been performed. After it has
1940  *    been performed the library will automatically unbind the port. The
1941  *    `client_entry' is the client to which we sent the key agreement
1942  *    request.  The key agreement completion callback will be called
1943  *    with SILC_KEY_AGREEMENT_ABORTED status.
1944  *
1945  ***/
1946 void silc_client_abort_key_agreement(SilcClient client,
1947                                      SilcClientConnection conn,
1948                                      SilcClientEntry client_entry);
1949
1950
1951 /* Misc functions */
1952
1953 /****f* silcclient/SilcClientAPI/silc_client_set_away_message
1954  *
1955  * SYNOPSIS
1956  *
1957  *    SilcBool silc_client_set_away_message(SilcClient client,
1958  *                                          SilcClientConnection conn,
1959  *                                          char *message);
1960  *
1961  * DESCRIPTION
1962  *
1963  *    Sets away `message'.  The away message may be set when the client's
1964  *    mode is changed to SILC_UMODE_GONE and the client whishes to reply
1965  *    to anyone who sends private message.  The `message' will be sent
1966  *    automatically back to the the client who send private message.  If
1967  *    away message is already set this replaces the old message with the
1968  *    new one.  If `message' is NULL the old away message is removed.
1969  *    The sender may freely free the memory of the `message'.  Returns
1970  *    FALSE on error.
1971  *
1972  ***/
1973 SilcBool silc_client_set_away_message(SilcClient client,
1974                                       SilcClientConnection conn,
1975                                       char *message);
1976
1977 /****d* silcclient/SilcClientAPI/SilcClientMonitorStatus
1978  *
1979  * NAME
1980  *
1981  *    typedef enum { ... } SilcClientMonitorStatus;
1982  *
1983  * DESCRIPTION
1984  *
1985  *    File transmission session status types.  These will indicate
1986  *    the status of the file transmission session.
1987  *
1988  * SOURCE
1989  */
1990 typedef enum {
1991   SILC_CLIENT_FILE_MONITOR_KEY_AGREEMENT,    /* In key agreemenet phase */
1992   SILC_CLIENT_FILE_MONITOR_SEND,             /* Sending file */
1993   SILC_CLIENT_FILE_MONITOR_RECEIVE,          /* Receiving file */
1994   SILC_CLIENT_FILE_MONITOR_GET,
1995   SILC_CLIENT_FILE_MONITOR_PUT,
1996   SILC_CLIENT_FILE_MONITOR_CLOSED,           /* Session closed */
1997   SILC_CLIENT_FILE_MONITOR_ERROR,            /* Error during session */
1998 } SilcClientMonitorStatus;
1999 /***/
2000
2001 /****d* silcclient/SilcClientAPI/SilcClientFileError
2002  *
2003  * NAME
2004  *
2005  *    typedef enum { ... } SilcClientFileError;
2006  *
2007  * DESCRIPTION
2008  *
2009  *    File transmission error types.  These types are returned by
2010  *    some of the file transmission functions, and by the monitor
2011  *    callback to indicate error.
2012  *
2013  * SOURCE
2014  */
2015 typedef enum {
2016   SILC_CLIENT_FILE_OK,
2017   SILC_CLIENT_FILE_ERROR,
2018   SILC_CLIENT_FILE_UNKNOWN_SESSION,
2019   SILC_CLIENT_FILE_ALREADY_STARTED,
2020   SILC_CLIENT_FILE_NO_SUCH_FILE,
2021   SILC_CLIENT_FILE_PERMISSION_DENIED,
2022   SILC_CLIENT_FILE_KEY_AGREEMENT_FAILED,
2023 } SilcClientFileError;
2024 /***/
2025
2026 /****f* silcclient/SilcClientAPI/SilcClientFileMonitor
2027  *
2028  * SYNOPSIS
2029  *
2030  *    typedef void (*SilcClientFileMonitor)(SilcClient client,
2031  *                                          SilcClientConnection conn,
2032  *                                          SilcClientMonitorStatus status,
2033  *                                          SilcClientFileError error,
2034  *                                          SilcUInt64 offset,
2035  *                                          SilcUInt64 filesize,
2036  *                                          SilcClientEntry client_entry,
2037  *                                          SilcUInt32 session_id,
2038  *                                          const char *filepath,
2039  *                                          void *context);
2040  *
2041  * DESCRIPTION
2042  *
2043  *    Monitor callback that is called during the file transmission to
2044  *    monitor the transmission process.  The `status' indicates the current
2045  *    monitoring process.  The `error' will indicate the error type
2046  *    if `status' is SILC_CLIENT_FILE_MONITOR_ERROR.  The `offset' is the
2047  *    currently transmitted amount of total `filesize'.  The `client_entry'
2048  *    indicates the remote client, and the transmission session ID is the
2049  *    `session_id'.  The filename being transmitted is indicated by the
2050  *    `filepath'.
2051  *
2052  ***/
2053 typedef void (*SilcClientFileMonitor)(SilcClient client,
2054                                       SilcClientConnection conn,
2055                                       SilcClientMonitorStatus status,
2056                                       SilcClientFileError error,
2057                                       SilcUInt64 offset,
2058                                       SilcUInt64 filesize,
2059                                       SilcClientEntry client_entry,
2060                                       SilcUInt32 session_id,
2061                                       const char *filepath,
2062                                       void *context);
2063
2064 /****f* silcclient/SilcClientAPI/SilcClientFileName
2065  *
2066  * SYNOPSIS
2067  *
2068  *    typedef void (*SilcClientFileName)(const char *filepath,
2069  *                                       void *context);
2070  *
2071  * DESCRIPTION
2072  *
2073  *    Completion callback for the SilcClientFileAskName callback function.
2074  *    Application calls this to deliver the filepath and filename where
2075  *    the downloaded file is to be saved.
2076  *
2077  ***/
2078 typedef void (*SilcClientFileName)(const char *filepath,
2079                                    void *context);
2080
2081 /****f* silcclient/SilcClientAPI/SilcClientFileAskName
2082  *
2083  * SYNOPSIS
2084  *
2085  *    typedef void (*SilcClientFileAskName)(SilcClient client,
2086  *                                          SilcClientConnection conn,
2087  *                                          SilcUInt32 session_id,
2088  *                                          const char *remote_filename,
2089  *                                          SilcClientFileName completion,
2090  *                                          void *completion_context,
2091  *                                          void *context);
2092  *
2093  * DESCRIPTION
2094  *
2095  *    File name asking callback, that is called if it is given to the
2096  *    silc_client_file_receive and the path given to that as argument was
2097  *    NULL.  The library calls this to ask the filename and filepath to
2098  *    where the file is to be saved.  The 'remote_filename' is the file
2099  *    that is being downloaded.  Application must call the 'completion'
2100  *    with 'completion_context' to continue with the file downloading.
2101  *    It is not mandatory to provide this to the silc_client_file_receive.
2102  *
2103  ***/
2104 typedef void (*SilcClientFileAskName)(SilcClient client,
2105                                       SilcClientConnection conn,
2106                                       SilcUInt32 session_id,
2107                                       const char *remote_filename,
2108                                       SilcClientFileName completion,
2109                                       void *completion_context,
2110                                       void *context);
2111
2112 /****f* silcclient/SilcClientAPI/silc_client_file_send
2113  *
2114  * SYNOPSIS
2115  *
2116  *    SilcClientFileError
2117  *    silc_client_file_send(SilcClient client,
2118  *                          SilcClientConnection conn,
2119  *                          SilcClientFileMonitor monitor,
2120  *                          void *monitor_context,
2121  *                          const char *local_ip,
2122  *                          SilcUInt32 local_port,
2123  *                          SilcBool do_not_bind,
2124  *                          SilcClientEntry client_entry,
2125  *                          const char *filepath);
2126  *                          SilcUInt32 *session_id);
2127  *
2128  * DESCRIPTION
2129  *
2130  *    Sends a file indicated by the `filepath' to the remote client
2131  *    indicated by the `client_entry'.  This will negotiate a secret key
2132  *    with the remote client before actually starting the transmission of
2133  *    the file.  The `monitor' callback will be called to monitor the
2134  *    transmission of the file.
2135  *
2136  *    This returns a file session ID for the file transmission to the
2137  *    `session_id' pointer.  It can be used to close the session (and
2138  *    abort the file transmission) by calling the silc_client_file_close
2139  *    function.  The session ID is also returned in the `monitor' callback.
2140  *
2141  *    If the `local_ip' is provided then this will try to bind the
2142  *    listener for key exchange protocol to that IP.  If `local_port' is
2143  *    non-zero that port is used.  If `local_ip' is NULL then this will
2144  *    automatically attempt to bind it to local IP address of the machine.
2145  *    If `do_not_bind' is TRUE then the `local_ip' and `local_port' are
2146  *    ignored and it is expected that the receiver will provide the
2147  *    point of contact.  This is usefull if the sender is behind NAT.
2148  *
2149  *    If error will occur during the file transfer process the error
2150  *    status will be returned in the monitor callback.  In this case
2151  *    the application must call silc_client_file_close to close the
2152  *    session.
2153  *
2154  ***/
2155 SilcClientFileError
2156 silc_client_file_send(SilcClient client,
2157                       SilcClientEntry client_entry,
2158                       SilcClientConnectionParams *params,
2159                       SilcPublicKey public_key,
2160                       SilcPrivateKey private_key,
2161                       SilcClientFileMonitor monitor,
2162                       void *monitor_context,
2163                       const char *filepath,
2164                       SilcUInt32 *session_id);
2165
2166 /****f* silcclient/SilcClientAPI/silc_client_file_receive
2167  *
2168  * SYNOPSIS
2169  *
2170  *    SilcClientFileError
2171  *    silc_client_file_receive(SilcClient client,
2172  *                             SilcClientConnection conn,
2173  *                             SilcClientFileMonitor monitor,
2174  *                             void *monitor_context,
2175  *                             const char *path,
2176  *                             SilcUInt32 session_id,
2177  *                             SilcClientFileAskName ask_name,
2178  *                             void *ask_name_context);
2179  *
2180  * DESCRIPTION
2181  *
2182  *    Receives a file from a client indicated by the `client_entry'.  The
2183  *    `session_id' indicates the file transmission session and it has been
2184  *    received in the `ftp' client operation function.  This will actually
2185  *    perform the key agreement protocol with the remote client before
2186  *    actually starting the file transmission.  The `monitor' callback
2187  *    will be called to monitor the transmission.  If `path' is non-NULL
2188  *    the file will be saved into that directory.  If NULL the file is
2189  *    saved in the current working directory, unless the 'ask_name'
2190  *    callback is non-NULL.  In this case the callback is called to ask
2191  *    the path and filename from application.
2192  *
2193  *    If error will occur during the file transfer process the error
2194  *    status will be returned in the monitor callback.  In this case
2195  *    the application must call silc_client_file_close to close the
2196  *    session.
2197  *
2198  ***/
2199 SilcClientFileError
2200 silc_client_file_receive(SilcClient client,
2201                          SilcClientConnection conn,
2202                          SilcClientFileMonitor monitor,
2203                          void *monitor_context,
2204                          const char *path,
2205                          SilcUInt32 session_id,
2206                          SilcClientFileAskName ask_name,
2207                          void *ask_name_context);
2208
2209 /****f* silcclient/SilcClientAPI/silc_client_file_close
2210  *
2211  * SYNOPSIS
2212  *
2213  *    SilcClientFileError silc_client_file_close(SilcClient client,
2214  *                                               SilcClientConnection conn,
2215  *                                               SilcUInt32 session_id);
2216  *
2217  * DESCRIPTION
2218  *
2219  *    Closes file transmission session indicated by the `session_id'.
2220  *    If file transmission is being conducted it will be aborted
2221  *    automatically. This function is also used to close the session
2222  *    after successful file transmission. This function can be used
2223  *    also to reject incoming file transmission request.  If the
2224  *    session was already started and the monitor callback was set
2225  *    the monitor callback will be called with the monitor status
2226  *    SILC_CLIENT_FILE_MONITOR_CLOSED.
2227  *
2228  ***/
2229 SilcClientFileError silc_client_file_close(SilcClient client,
2230                                            SilcClientConnection conn,
2231                                            SilcUInt32 session_id);
2232
2233 /****f* silcclient/SilcClientAPI/silc_client_attribute_add
2234  *
2235  * SYNOPSIS
2236  *
2237  *    SilcAttributePayload
2238  *    silc_client_attribute_add(SilcClient client,
2239  *                              SilcClientConnection conn,
2240  *                              SilcAttribute attribute,
2241  *                              void *object,
2242  *                              SilcUInt32 object_size);
2243  *
2244  * DESCRIPTION
2245  *
2246  *    Add new Requsted Attribute for WHOIS command to the client library.
2247  *    The `attribute' object indicated by `object' is added and allocated
2248  *    SilcAttributePayload is returned.  The `object' must be of correct
2249  *    type and of correct size.  See the SilcAttribute for object types
2250  *    for different attributes.  You may also get all added attributes
2251  *    from the client with silc_client_attributes_get function.
2252  *
2253  *    Requested Attributes are different personal information about the
2254  *    user, status information and other information which other users
2255  *    may query with WHOIS command.  Application may set these so that
2256  *    if someone sends WHOIS query these attributes will be replied back
2257  *    to the sender.  The library always puts the public key to the
2258  *    Requested Attributes, but if application wishes to add additional
2259  *    public keys (or certificates) it can be done with this interface.
2260  *    Library also always computes digital signature of the attributes
2261  *    automatically, so application does not need to do that.
2262  *
2263  ***/
2264 SilcAttributePayload silc_client_attribute_add(SilcClient client,
2265                                                SilcClientConnection conn,
2266                                                SilcAttribute attribute,
2267                                                void *object,
2268                                                SilcUInt32 object_size);
2269
2270 /****f* silcclient/SilcClientAPI/silc_client_attribute_del
2271  *
2272  * SYNOPSIS
2273  *
2274  *    SilcBool silc_client_attribute_del(SilcClient client,
2275  *                                   SilcClientConnection conn,
2276  *                                   SilcAttribute attribute,
2277  *                                   SilcAttributePayload attr);
2278  *
2279  * DESCRIPTION
2280  *
2281  *    Delete a Requested Attribute from the client.  If the `attribute'
2282  *    is non-zero then all attributes of that type are deleted and the
2283  *    `attr' is ignored.  If `attr' is non-NULL then that specific
2284  *    attribute is deleted and `attribute' is ignored.
2285  *
2286  *    You may get all added attributes with the function
2287  *    silc_client_attributes_get and to get the SilcAttributePayload.
2288  *    This function Returns TRUE if the attribute was found and deleted.
2289  *
2290  ***/
2291 SilcBool silc_client_attribute_del(SilcClient client,
2292                                    SilcClientConnection conn,
2293                                    SilcAttribute attribute,
2294                                    SilcAttributePayload attr);
2295
2296 /****f* silcclient/SilcClientAPI/silc_client_attributes_get
2297  *
2298  * SYNOPSIS
2299  *
2300  *    const SilcHashTable
2301  *    silc_client_attributes_get(SilcClient client,
2302  *                               SilcClientConnection conn);
2303  *
2304  * DESCRIPTION
2305  *
2306  *    Returns pointer to the SilcHashTable which includes all the added
2307  *    Requested Attributes.  The caller must not free the hash table.
2308  *    The caller may use SilcHashTableList and silc_hash_table_list to
2309  *    traverse the table.  Each entry in the hash table is one added
2310  *    SilcAttributePayload.  It is possible to delete a attribute
2311  *    payload while traversing the table.
2312  *
2313  ***/
2314 SilcHashTable silc_client_attributes_get(SilcClient client,
2315                                          SilcClientConnection conn);
2316
2317 /****f* silcclient/SilcClientAPI/silc_client_attributes_request
2318  *
2319  * SYNOPSIS
2320  *
2321  *    SilcBuffer silc_client_attributes_request(SilcAttribute attribute, ...);
2322  *
2323  * DESCRIPTION
2324  *
2325  *    Constructs a Requested Attributes buffer. If the `attribute' is zero (0)
2326  *    then all attributes are requested.  Alternatively, `attribute' and
2327  *    all variable arguments can each be requested attribute.  In this case
2328  *    the last must be set to zero (0) to complete the variable list of
2329  *    requested attributes.  See SilcAttribute for all attributes.
2330  *    You can give the returned buffer as argument to for example
2331  *    silc_client_get_client_by_id_resolve function.
2332  *
2333  * EXAMPLE
2334  *
2335  *    Request all attributes
2336  *    buffer = silc_client_attributes_request(0);
2337  *
2338  *    Request only the following attributes
2339  *    buffer = silc_client_attributes_request(SILC_ATTRIBUTE_USER_INFO,
2340  *                                            SILC_ATTRIBUTE_SERVICE,
2341  *                                            SILC_ATTRIBUTE_MOOD, 0);
2342  *
2343  ***/
2344 SilcBuffer silc_client_attributes_request(SilcAttribute attribute, ...);
2345
2346 /****f* silcclient/SilcClientAPI/silc_client_nickname_format
2347  *
2348  * SYNOPSIS
2349  *
2350  *    SilcClientEntry
2351  *    silc_client_nickname_format(SilcClient client,
2352  *                                SilcClientConnection conn,
2353  *                                SilcClientEntry client_entry,
2354  *                                SilcBool priority);
2355  *
2356  * DESCRIPTION
2357  *
2358  *    Formats the nickname of `client_entry' according to the nickname
2359  *    formatting rules set in SilcClientParams.  If the `priority' is TRUE
2360  *    then the `client_entry' will always get the unformatted nickname.
2361  *    If FALSE and there are more than one same nicknames in the client
2362  *    the nickname will be formatted.
2363  *
2364  *    This returns NULL on error.  Otherwise, the client entry that was
2365  *    formatted is returned.  If `priority' is FALSE this always returns
2366  *    the `client_entry'.  If it is TRUE, this may return the client entry
2367  *    that was formatted after giving the `client_entry' the unformatted
2368  *    nickname.
2369  *
2370  *    Usually application does not need to call this function, as the library
2371  *    automatically formats nicknames.  However, if application wants to
2372  *    for example force the `client_entry' to always have the unformatted
2373  *    nickname it may call this function to do so.
2374  *
2375  ***/
2376 SilcClientEntry silc_client_nickname_format(SilcClient client,
2377                                             SilcClientConnection conn,
2378                                             SilcClientEntry client_entry,
2379                                             SilcBool priority);
2380
2381 #ifdef __cplusplus
2382 }
2383 #endif
2384
2385 #endif /* SILCCLIENT_H */