*
* Ask passphrase callback. This is called by the application when the
* library calls `ask_passphrase' client operation. The callback delivers
- * the passphrase to the library.
+ * the passphrase to the library. The passphrases in SILC protocol
+ * MUST be in UTF-8 encoding, therefore the `passphrase' SHOULD be UTF-8
+ * encoded, and if it is not then library will attempt to encode it.
*
***/
typedef void (*SilcAskPassphrase)(unsigned char *passphrase,
} 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
`msg' maybe NULL. */
void (*channel_message)(SilcClient client, SilcClientConnection conn,
SilcClientEntry sender, SilcChannelEntry channel,
- SilcMessageFlags flags, char *msg);
+ SilcMessageFlags flags,
+ const unsigned char *message,
+ SilcUInt32 message_len);
/* Private message to the client. The `sender' is the sender of the
message. */
void (*private_message)(SilcClient client, SilcClientConnection conn,
SilcClientEntry sender, SilcMessageFlags flags,
- char *msg);
+ const unsigned char *message,
+ SilcUInt32 message_len);
/* Notify message to the client. The notify arguments are sent in the
same order as servers sends them. The arguments are same as received
SilcClientEntry. */
void (*command_reply)(SilcClient client, SilcClientConnection conn,
SilcCommandPayload cmd_payload, int success,
- SilcCommand command, SilcCommandStatus status, ...);
+ SilcCommand command, SilcStatus status, ...);
/* Called to indicate that connection was either successfully established
or connecting failed. This is also the first time application receives
- the SilcClientConnection objecet which it should save somewhere.
- If the `success' is FALSE the application must always call the function
+ the SilcClientConnection object which it should save somewhere.
+ 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);
/* Ask (interact, that is) a passphrase from user. The passphrase is
returned to the library by calling the `completion' callback with
- the `context'. */
+ the `context'. The returned passphrase SHOULD be in UTF-8 encoded,
+ if not then the library will attempt to encode. */
void (*ask_passphrase)(SilcClient client, SilcClientConnection conn,
SilcAskPassphrase completion, void *context);
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;
/***/
* 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,
/* Connecting functions (client.c) */
+/****s* silcclient/SilcClientAPI/SilcClientConnectionParams
+ *
+ * NAME
+ *
+ * typedef struct { ... } SilcClientConnectionParams;
+ *
+ * DESCRIPTION
+ *
+ * Client connection parameters. This can be filled by the application
+ * and given as argument to silc_client_connect_to_server or to
+ * silc_client_add_connection.
+ *
+ * SOURCE
+ */
+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.
+
+ 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;
+
+} SilcClientConnectionParams;
+/***/
+
/****f* silcclient/SilcClientAPI/silc_client_connect_to_server
*
* SYNOPSIS
*
- * int silc_client_connect_to_server(SilcClient client, int port,
- * char *host, void *context);
+ * int silc_client_connect_to_server(SilcClient client,
+ * SilcClientConnectionParams *params,
+ * int port, char *host, void *context);
*
* DESCRIPTION
*
* that is created after the connection is created. Note that application
* may handle the connecting process outside the library. If this is the
* case then this function is not used at all. When the connecting is
- * done the `connect' client operation is called.
+ * done the `connect' client operation is called, and the `context' is
+ * accessible with conn->context, conn being SilcClientConnection.
+ * If the `params' is provided they are used by the routine.
*
***/
-int silc_client_connect_to_server(SilcClient client, int port,
- char *host, void *context);
+int silc_client_connect_to_server(SilcClient client,
+ SilcClientConnectionParams *params,
+ int port, char *host, void *context);
/****f* silcclient/SilcClientAPI/silc_client_add_connection
*
* SYNOPSIS
*
- * SilcClientConnection silc_client_add_connection(SilcClient client,
- * char *hostname,
- * int port,
- * void *context);
+ *
+ * SilcClientConnection
+ * silc_client_add_connection(SilcClient client,
+ * SilcClientConnectionParams *params,
+ * char *hostname, int port, void *context);
*
* DESCRIPTION
*
* connection to the connection table and returns a pointer to it. A client
* can have multiple connections to multiple servers. Every connection must
* be added to the client using this function. User data `context' may
- * be sent as argument. This function is normally used only if the
- * application performed the connecting outside the library. The library
+ * be sent as argument. If the `params' is provided they are used by
+ * the routine.
+ *
+ * NOTES
+ *
+ * This function is normally used only if the application performed
+ * the connecting outside the library, and did not called the
+ * silc_client_connect_to_server function at all. The library
* however may use this internally.
*
***/
-SilcClientConnection silc_client_add_connection(SilcClient client,
- char *hostname,
- int port,
- void *context);
+SilcClientConnection
+silc_client_add_connection(SilcClient client,
+ SilcClientConnectionParams *params,
+ char *hostname, int port, void *context);
/****f* silcclient/SilcClientAPI/silc_client_del_connection
*
* SYNOPSIS
*
* void silc_client_close_connection(SilcClient client,
- * SilcSocketConnection sock,
* SilcClientConnection conn);
*
* DESCRIPTION
*
* Closes connection to remote end. Free's all allocated data except
* for some information such as nickname etc. that are valid at all time.
- * If the `sock' is NULL then the conn->sock will be used. If `sock' is
- * provided it will be checked whether the sock and `conn->sock' are the
- * same (they can be different, ie. a socket can use `conn' as its
- * connection but `conn->sock' might be actually a different connection
- * than the `sock').
*
***/
void silc_client_close_connection(SilcClient client,
- SilcSocketConnection sock,
SilcClientConnection conn);
projects / silc.git / blobdiff