lib/silcclient/silcclient.h

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