updates.

[silc.git] / lib / silcclient / silcclient.h

diff --git a/lib/silcclient/silcclient.h b/lib/silcclient/silcclient.h
index 87c3b97c84ac77a4c1486b1d595ee64681c32d54..928650c788e8bfff98e8dd81c6b9bbec974bf0ad 100644 (file)
--- a/lib/silcclient/silcclient.h
+++ b/lib/silcclient/silcclient.h
@@ -254,6 +254,28 @@ typedef enum {
 } SilcClientMessageType;
 /***/
 
+/****d* silcclient/SilcClientAPI/SilcClientConnectionStatus
+ *
+ * NAME
+ *
+ *    typedef enum { ... } SilcClientConnectionStatus
+ *
+ * DESCRIPTION
+ *
+ *    This type is returned to the `connect' client operation to indicate
+ *    the status of the created connection.  It can indicated if it was
+ *    successful or whether an error occurred.
+ *
+ * SOURCE
+ */
+typedef enum {
+  SILC_CLIENT_CONN_SUCCESS,           /* Successfully connected */
+  SILC_CLIENT_CONN_SUCCESS_RESUME,     /* Successfully connected and
+                                         resumed old detached session */
+  SILC_CLIENT_CONN_ERROR,             /* Error occurred during connecting */
+} SilcClientConnectionStatus;
+/***/
+
 /****s* silcclient/SilcClientAPI/SilcClientOperations
  *
  * NAME
@@ -346,9 +368,11 @@ typedef struct {
   /* Called to indicate that connection was either successfully established
      or connecting failed.  This is also the first time application receives
      the SilcClientConnection object which it should save somewhere.
-     If the `success' is FALSE the application must always call the function
+     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, int success);
+  void (*connect)(SilcClient client, SilcClientConnection conn,
+                 SilcClientConnectionStatus status);
 
   /* Called to indicate that connection was disconnected to the server. */
   void (*disconnect)(SilcClient client, SilcClientConnection conn);
@@ -409,6 +433,26 @@ typedef struct {
   void (*ftp)(SilcClient client, SilcClientConnection conn,
              SilcClientEntry client_entry, SilcUInt32 session_id,
              const char *hostname, SilcUInt16 port);
+
+  /* Delivers SILC session detachment data indicated by `detach_data' to the
+     application.  If application has issued SILC_COMMAND_DETACH command     
+     the client session in the SILC network is not quit.  The client remains 
+     in the network but is detached.  The detachment data may be used later
+     to resume the session in the SILC Network.  The appliation is   
+     responsible of saving the `detach_data', to for example in a file.
+
+     The detachment data can be given as argument to the functions
+     silc_client_connect_to_server, or silc_client_add_connection when
+     creating connection to remote server, inside SilcClientConnectionParams
+     structure.  If it is provided the client library will attempt to resume
+     the session in the network.  After the connection is created
+     successfully, the application is responsible of setting the user
+     interface for user into the same state it was before detaching (showing
+     same channels, channel modes, etc).  It can do this by fetching the
+     information (like joined channels) from the client library. */
+  void (*detach)(SilcClient client, SilcClientConnection conn,
+                const unsigned char *detach_data,
+                SilcUInt32 detach_data_len);
 } SilcClientOperations;
 /***/
 
@@ -533,7 +577,8 @@ typedef struct {
  *    the client. The `application' is application specific user data pointer
  *    and caller must free it. The `silc_version' is the application version
  *    that will be used to compare against remote host's (usually a server)
- *    version string.
+ *    version string.  The `application' context is accessible by the
+ *    application by client->application, client being SilcClient.
  *
  ***/
 SilcClient silc_client_alloc(SilcClientOperations *ops, 
@@ -640,7 +685,14 @@ typedef struct {
   /* The SILC session detachment data that was returned by `detach' client
      operation when the application detached from the network.  Application
      is responsible of saving the data and giving it as argument here
-     for resuming the session in the SILC network. */
+     for resuming the session in the SILC network.
+
+     If this is provided here the client library will attempt to resume
+     the session in the network.  After the connection is created
+     successfully, the application is responsible of setting the user
+     interface for user into the same state it was before detaching (showing
+     same channels, channel modes, etc).  It can do this by fetching the
+     information (like joined channels) from the client library. */
   unsigned char *detach_data;
   SilcUInt32 detach_data_len;