Changed the version string variables to #defines.
[silc.git] / lib / silcclient / silcclient.h
index b0ef27efcd4c026dc1025dc1796935481b9d14e2..8b9ad8f6c2151cb4c1c8175f4f5c1122a52c2a86 100644 (file)
@@ -92,6 +92,8 @@ typedef enum {
   SILC_KEY_AGREEMENT_FAILURE,         /* The protocol failed */
   SILC_KEY_AGREEMENT_TIMEOUT,         /* The protocol timeout */
   SILC_KEY_AGREEMENT_ABORTED,         /* The protocol aborted */
+  SILC_KEY_AGREEMENT_ALREADY_STARTED,  /* Already started */
+  SILC_KEY_AGREEMENT_SELF_DENIED,      /* Negotiationg with itself denied */
 } SilcKeyAgreementStatus;
 /***/
 
@@ -295,14 +297,16 @@ typedef struct {
   /* Message sent to the application by library. `conn' associates the
      message to a specific connection.  `conn', however, may be NULL. 
      The `type' indicates the type of the message sent by the library.
-     The applicationi can for example filter the message according the
+     The application can for example filter the message according the
      type. */
   void (*say)(SilcClient client, SilcClientConnection conn, 
              SilcClientMessageType type, char *msg, ...);
 
   /* Message for a channel. The `sender' is the sender of the message 
-     The `channel' is the channel. The `msg' is the message.  Note that
-     `msg' maybe NULL. */
+     The `channel' is the channel. The `message' is the message.  Note 
+     that `message' maybe NULL.  The `flags' indicates message flags 
+     and it is used to determine how the message can be interpreted
+     (like it may tell the message is multimedia message). */
   void (*channel_message)(SilcClient client, SilcClientConnection conn, 
                          SilcClientEntry sender, SilcChannelEntry channel, 
                          SilcMessageFlags flags,
@@ -310,7 +314,10 @@ typedef struct {
                          SilcUInt32 message_len);
 
   /* Private message to the client. The `sender' is the sender of the
-     message. */
+     message. The message is `message'and maybe NULL.  The `flags' 
+     indicates message flags  and it is used to determine how the message 
+     can be interpreted (like it may tell the message is multimedia 
+     message). */
   void (*private_message)(SilcClient client, SilcClientConnection conn,
                          SilcClientEntry sender, SilcMessageFlags flags,
                          const unsigned char *message,
@@ -371,11 +378,15 @@ typedef struct {
      The `status' indicated whether the connection were successful.  If it
      is error value the application must always call the function
      silc_client_close_connection. */
-  void (*connect)(SilcClient client, SilcClientConnection conn,
-                 SilcClientConnectionStatus status);
+  void (*connected)(SilcClient client, SilcClientConnection conn,
+                   SilcClientConnectionStatus status);
 
-  /* Called to indicate that connection was disconnected to the server. */
-  void (*disconnect)(SilcClient client, SilcClientConnection conn);
+  /* Called to indicate that connection was disconnected to the server.
+     The `status' may tell the reason of the disconnection, and if the
+     `message' is non-NULL it may include the disconnection message
+     received from server. */
+  void (*disconnected)(SilcClient client, SilcClientConnection conn,
+                      SilcStatus status, const char *message);
 
   /* Find authentication method and authentication data by hostname and
      port. The hostname may be IP address as well. When the authentication
@@ -388,8 +399,9 @@ typedef struct {
 
   /* Verifies received public key. The `conn_type' indicates which entity
      (server, client etc.) has sent the public key. If user decides to trust
-     the key may be saved as trusted public key for later use. The 
-     `completion' must be called after the public key has been verified. */
+     the application may save the key as trusted public key for later 
+     use. The `completion' must be called after the public key has been 
+     verified. */
   void (*verify_public_key)(SilcClient client, SilcClientConnection conn,
                            SilcSocketType conn_type, unsigned char *pk, 
                            SilcUInt32 pk_len, SilcSKEPKType pk_type,
@@ -419,10 +431,10 @@ typedef struct {
      desired (application may start it later by calling the function
      silc_client_perform_key_agreement). If TRUE is returned also the
      `completion' and `context' arguments must be set by the application. */
-  int (*key_agreement)(SilcClient client, SilcClientConnection conn,
-                      SilcClientEntry client_entry, const char *hostname,
-                      SilcUInt16 port, SilcKeyAgreementCallback *completion,
-                      void **context);
+  bool (*key_agreement)(SilcClient client, SilcClientConnection conn,
+                       SilcClientEntry client_entry, const char *hostname,
+                       SilcUInt16 port, SilcKeyAgreementCallback *completion,
+                       void **context);
 
   /* Notifies application that file transfer protocol session is being
      requested by the remote client indicated by the `client_entry' from
@@ -555,6 +567,15 @@ typedef struct {
      nickname string whenever it needs the true nickname. */
   SilcNicknameFormatParse nickname_parse;
 
+  /* If this is set to TRUE then the client will ignore all incoming
+     Requested Attributes queries and does not reply anything back.  This
+     usually leads into situation where server does not anymore send
+     the queries after seeing that client does not reply anything back.
+     If your application does not support Requested Attributes or you do
+     not want to use them set this to TRUE.  See SilcAttribute and
+     silc_client_attribute_add for more information on attributes. */
+  bool ignore_requested_attributes;
+
 } SilcClientParams;
 /***/
 
@@ -584,7 +605,7 @@ typedef struct {
 SilcClient silc_client_alloc(SilcClientOperations *ops, 
                             SilcClientParams *params,
                             void *application,
-                            const char *silc_version);
+                            const char *version_string);
 
 /****f* silcclient/SilcClientAPI/silc_client_free
  *
@@ -1063,6 +1084,7 @@ SilcClientEntry silc_client_get_client_by_id(SilcClient client,
  *    silc_client_get_client_by_id_resolve(SilcClient client,
  *                                         SilcClientConnection conn,
  *                                         SilcClientID *client_id,
+ *                                         SilcBuffer attributes,
  *                                         SilcGetClientCallback completion,
  *                                         void *context);
  *
@@ -1074,10 +1096,18 @@ SilcClientEntry silc_client_get_client_by_id(SilcClient client,
  *    is its ID. When server returns the client information it will be
  *    cache and can be accessed locally at a later time.
  *
+ *    If the `attributes' is non-NULL then the buffer includes Requested
+ *    Attributes which can be used to fetch very detailed information
+ *    about the user. If it is NULL then only normal WHOIS query is
+ *    made (for more information about attributes see SilcAttribute).
+ *    Caller may create the `attributes' with silc_client_attributes_request
+ *    function.
+ *
  ***/
 void silc_client_get_client_by_id_resolve(SilcClient client,
                                          SilcClientConnection conn,
                                          SilcClientID *client_id,
+                                         SilcBuffer attributes,
                                          SilcGetClientCallback completion,
                                          void *context);
 
@@ -1140,16 +1170,14 @@ SilcChannelEntry silc_client_get_channel(SilcClient client,
                                         SilcClientConnection conn,
                                         char *channel);
 
-/****f* silcclient/SilcClientAPI/silc_client_get_channel_id_resolve
+/****f* silcclient/SilcClientAPI/silc_client_get_channel_by_id
  *
  * SYNOPSIS
  *
- *    void 
- *    silc_client_get_channel_by_id_resolve(SilcClient client,
- *                                          SilcClientConnection conn,
- *                                          SilcChannelID *channel_id,
- *                                          SilcGetClientCallback completion,
- *                                          void *context);
+ *    SilcChannelEntry
+ *    silc_client_get_channel_by_id(SilcClient client,
+ *                                  SilcClientConnection conn,
+ *                                  SilcChannelID *channel_id);
  *
  * DESCRIPTION
  *
@@ -1377,6 +1405,14 @@ void silc_client_command_call(SilcClientCommand command,
  *    directly to the server using this function.  If application is using
  *    the silc_client_command_call, this function is usually not used.
  *
+ *    The variable arguments are a pair of { type, data, data_length },
+ *    and the `argc' is the number of these pairs.
+ *
+ * EXAMPLE
+ *
+ *    silc_client_command_send(client, conn, SILC_COMMAND_WHOIS, 0, 1,
+ *                             1, nickname, strlen(nickname));
+ *
  ***/
 void silc_client_command_send(SilcClient client, SilcClientConnection conn,
                              SilcCommand command, SilcUInt16 ident,
@@ -1486,33 +1522,6 @@ int silc_client_add_private_message_key_ske(SilcClient client,
                                            SilcSKEKeyMaterial *key,
                                            bool responder);
 
-/****f* silcclient/SilcClientAPI/silc_client_send_private_message_key
- *
- * SYNOPSIS
- *
- *    int silc_client_send_private_message_key(SilcClient client,
- *                                             SilcClientConnection conn,
- *                                             SilcClientEntry client_entry,
- *                                             int force_send);
- *
- * DESCRIPTION
- *
- *    Sends private message key payload to the remote client indicated by
- *    the `client_entry'. If the `force_send' is TRUE the packet is sent
- *    immediately. Returns FALSE if error occurs, TRUE otherwise. The
- *    application should call this function after setting the key to the
- *    client.
- *
- *    Note that the key sent using this function is sent to the remote client
- *    through the SILC network. The packet is protected using normal session
- *    keys. 
- *
- ***/
-int silc_client_send_private_message_key(SilcClient client,
-                                        SilcClientConnection conn,
-                                        SilcClientEntry client_entry,
-                                        int force_send);
-
 /****f* silcclient/SilcClientAPI/silc_client_del_private_message_key
  *
  * SYNOPSIS
@@ -2177,6 +2186,148 @@ SilcClientFileError silc_client_file_close(SilcClient client,
                                           SilcClientConnection conn,
                                           SilcUInt32 session_id);
 
+/****f* silcclient/SilcClientAPI/silc_client_attribute_add
+ *
+ * SYNOPSIS
+ *
+ *    SilcAttributePayload
+ *    silc_client_attribute_add(SilcClient client,
+ *                              SilcClientConnection conn,
+ *                              SilcAttribute attribute,
+ *                              void *object,
+ *                              SilcUInt32 object_size);
+ *
+ * DESCRIPTION
+ *
+ *    Add new Requsted Attribute for WHOIS command to the client library.
+ *    The `attribute' object indicated by `object' is added and allocated
+ *    SilcAttributePayload is returned.  The `object' must be of correct
+ *    type and of correct size.  See the SilcAttribute for object types
+ *    for different attributes.  You may also get all added attributes
+ *    from the client with silc_client_attributes_get function.
+ *
+ *    Requested Attributes are different personal information about the
+ *    user, status information and other information which other users
+ *    may query with WHOIS command.  Application may set these so that
+ *    if someone sends WHOIS query these attributes will be replied back
+ *    to the sender.  The library always puts the public key to the
+ *    Requested Attributes, but if application wishes to add additional
+ *    public keys (or certificates) it can be done with this interface.
+ *    Library also always computes digital signature of the attributes
+ *    automatically, so application does not need to do that.
+ *
+ ***/
+SilcAttributePayload silc_client_attribute_add(SilcClient client,
+                                              SilcClientConnection conn,
+                                              SilcAttribute attribute,
+                                              void *object,
+                                              SilcUInt32 object_size);
+
+/****f* silcclient/SilcClientAPI/silc_client_attribute_del
+ *
+ * SYNOPSIS
+ *
+ *    bool silc_client_attribute_del(SilcClient client,
+ *                                   SilcClientConnection conn,
+ *                                   SilcAttribute attribute,
+ *                                   SilcAttributePayload attr);
+ *
+ * DESCRIPTION
+ *
+ *    Delete a Requested Attribute from the client.  If the `attribute'
+ *    is non-zero then all attributes of that type are deleted and the
+ *    `attr' is ignored.  If `attr' is non-NULL then that specific
+ *    attribute is deleted and `attribute' is ignored.
+ *    
+ *    You may get all added attributes with the function
+ *    silc_client_attributes_get and to get the SilcAttributePayload.
+ *    This function Returns TRUE if the attribute was found and deleted.
+ *
+ ***/
+bool silc_client_attribute_del(SilcClient client,
+                              SilcClientConnection conn,
+                              SilcAttribute attribute,
+                              SilcAttributePayload attr);
+
+/****f* silcclient/SilcClientAPI/silc_client_attributes_get
+ *
+ * SYNOPSIS
+ *
+ *    const SilcHashTable
+ *    silc_client_attributes_get(SilcClient client,
+ *                               SilcClientConnection conn);
+ *
+ * DESCRIPTION
+ *
+ *    Returns pointer to the SilcHashTable which includes all the added
+ *    Requested Attributes.  The caller must not free the hash table.
+ *    The caller may use SilcHashTableList and silc_hash_table_list to
+ *    traverse the table.  Each entry in the hash table is one added
+ *    SilcAttributePayload.  It is possible to delete a attribute
+ *    payload while traversing the table.
+ *
+ ***/
+const SilcHashTable silc_client_attributes_get(SilcClient client,
+                                              SilcClientConnection conn);
+
+/****f* silcclient/SilcClientAPI/silc_client_attributes_request
+ *
+ * SYNOPSIS
+ *
+ *    SilcBuffer silc_client_attributes_request(SilcAttribute attribute, ...);
+ *
+ * DESCRIPTION
+ *
+ *    Constructs a Requested Attributes buffer. If the `attribute' is zero (0)
+ *    then all attributes are requested.  Alternatively, `attribute' and
+ *    all variable arguments can each be requested attribute.  In this case
+ *    the last must be set to zero (0) to complete the variable list of
+ *    requested attributes.  See SilcAttribute for all attributes.
+ *    You can give the returned buffer as argument to for example
+ *    silc_client_get_client_by_id_resolve function.
+ *
+ ***/
+SilcBuffer silc_client_attributes_request(SilcAttribute attribute, ...);
+
+/* Low level packet sending functions */
+
+/****f* silcclient/SilcClientAPI/silc_client_packet_send
+ *
+ * SYNOPSIS
+ *
+ *    void silc_client_packet_send(SilcClient client, 
+ *                                 SilcSocketConnection sock,
+ *                                 SilcPacketType type, 
+ *                                 void *dst_id,
+ *                                 SilcIdType dst_id_type,
+ *                                 SilcCipher cipher,
+ *                                 SilcHmac hmac,
+ *                                 unsigned char *data, 
+ *                                 SilcUInt32 data_len, 
+ *                                 bool force_send);
+ *
+ * DESCRIPTION
+ *
+ *    Constructs a Requested Attributes buffer. If the `attribute' is zero (0)
+ *    then all attributes are requested.  Alternatively, `attribute' and
+ *    all variable arguments can each be requested attribute.  In this case
+ *    the last must be set to zero (0) to complete the variable list of
+ *    requested attributes.  See SilcAttribute for all attributes.
+ *    You can give the returned buffer as argument to for example
+ *    silc_client_get_client_by_id_resolve function.
+ *
+ ***/
+void silc_client_packet_send(SilcClient client, 
+                            SilcSocketConnection sock,
+                            SilcPacketType type, 
+                            void *dst_id,
+                            SilcIdType dst_id_type,
+                            SilcCipher cipher,
+                            SilcHmac hmac,
+                            unsigned char *data, 
+                            SilcUInt32 data_len, 
+                            bool force_send);
+
 #include "client.h"
 #include "command.h"
 #include "command_reply.h"