*/
-/****h* silcclient/SilcClientAPI
+/****h* silcclient/Client Library Interface
*
* DESCRIPTION
*
typedef struct SilcClientCommandContextStruct *SilcClientCommandContext;
typedef struct SilcClientCommandReplyContextStruct
*SilcClientCommandReplyContext;
-typedef struct SilcChannelPrivateKeyStruct *SilcChannelPrivateKey;
typedef struct SilcChannelUserStruct *SilcChannelUser;
/* General definitions */
provided it. This is NULL if the
library generated the key or if
the SKE key material was used. */
- uint32 key_len; /* The key length */
+ SilcUInt32 key_len; /* The key length */
} *SilcPrivateMessageKeys;
/***/
+/****s* silcclient/SilcClientAPI/SilcChannelPrivateKey
+ *
+ * NAME
+ *
+ * typedef struct { ... } SilcChannelPrivateKey;
+ *
+ * DESCRIPTION
+ *
+ * Structure to hold one channel private key. The array of this structure
+ * is returned by silc_client_list_channel_private_keys function.
+ *
+ * SOURCE
+ */
+typedef struct SilcChannelPrivateKeyStruct {
+ char *name; /* Application given name */
+ SilcCipher cipher; /* The cipher and key */
+ SilcHmac hmac; /* The HMAC and hmac key */
+ unsigned char *key; /* The key data */
+ SilcUInt32 key_len; /* The key length */
+} *SilcChannelPrivateKey;
+/***/
/****f* silcclient/SilcClientAPI/SilcAskPassphrase
*
* SYNOPSIS
*
* typedef void (*SilcAskPassphrase)(unsigned char *passphrase,
- * uint32 passphrase_len,
+ * SilcUInt32 passphrase_len,
* void *context);
*
* DESCRIPTION
*
* 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,
- uint32 passphrase_len,
+ SilcUInt32 passphrase_len,
void *context);
/****f* silcclient/SilcClientAPI/SilcVerifyPublicKey
* typedef void (*SilcGetAuthMeth)(bool success,
* SilcProtocolAuthMeth auth_meth,
* const unsigned char *auth_data,
- * uint32 auth_data_len, void *context);
+ * SilcUInt32 auth_data_len, void *context);
*
* DESCRIPTION
*
typedef void (*SilcGetAuthMeth)(bool success,
SilcProtocolAuthMeth auth_meth,
const unsigned char *auth_data,
- uint32 auth_data_len, void *context);
+ SilcUInt32 auth_data_len, void *context);
/****d* silcclient/SilcClientAPI/SilcClientMessageType
*
} 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
the command reply status server returned. The `command' is the command
reply being processed. The function has variable argument list and each
command defines the number and type of arguments it passes to the
- application (on error they are not sent). */
+ application (on error they are not sent).
+
+ The arguments are sent in the same order as servers sends them. The
+ arguments are same as received from the server except for ID's. If
+ ID is received application receives the corresponding entry to the
+ ID. For example, if Client ID is receives application receives
+ SilcClientEntry. */
void (*command_reply)(SilcClient client, SilcClientConnection conn,
SilcCommandPayload cmd_payload, int success,
SilcCommand command, SilcCommandStatus 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);
authentication method and authentication data is called. The `conn'
may be NULL. */
void (*get_auth_method)(SilcClient client, SilcClientConnection conn,
- char *hostname, uint16 port,
+ char *hostname, SilcUInt16 port,
SilcGetAuthMeth completion, void *context);
/* Verifies received public key. The `conn_type' indicates which entity
`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,
- uint32 pk_len, SilcSKEPKType pk_type,
+ SilcUInt32 pk_len, SilcSKEPKType pk_type,
SilcVerifyPublicKey completion, void *context);
/* 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);
`completion' and `context' arguments must be set by the application. */
int (*key_agreement)(SilcClient client, SilcClientConnection conn,
SilcClientEntry client_entry, const char *hostname,
- uint16 port, SilcKeyAgreementCallback *completion,
+ SilcUInt16 port, SilcKeyAgreementCallback *completion,
void **context);
/* Notifies application that file transfer protocol session is being
transfer request, by calling the silc_client_file_receive or
silc_client_file_close, respectively. */
void (*ftp)(SilcClient client, SilcClientConnection conn,
- SilcClientEntry client_entry, uint32 session_id,
- const char *hostname, uint16 port);
+ 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
*
* directly if application is performing its own connecting and does not
* use the connecting provided by this library. This function is normally
* used only if the application performed the connecting outside the
- * library. The library however may use this internally. Returns FALSE
- * if the key exchange could not be started.
+ * library. The library however may use this internally. After the
+ * key exchange is performed the `connect' client operation is called.
*
***/
void silc_client_start_key_exchange(SilcClient client,
* 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);
* SilcChannelPrivateKey key,
* SilcMessageFlags flags,
* unsigned char *data,
- * uint32 data_len,
+ * SilcUInt32 data_len,
* int force_send);
*
* DESCRIPTION
SilcChannelPrivateKey key,
SilcMessageFlags flags,
unsigned char *data,
- uint32 data_len,
+ SilcUInt32 data_len,
int force_send);
/****f* silcclient/SilcClientAPI/silc_client_send_private_message
* SilcClientEntry client_entry,
* SilcMessageFlags flags,
* unsigned char *data,
- * uint32 data_len,
+ * SilcUInt32 data_len,
* int force_send);
*
* DESCRIPTION
SilcClientEntry client_entry,
SilcMessageFlags flags,
unsigned char *data,
- uint32 data_len,
+ SilcUInt32 data_len,
int force_send);
* typedef void (*SilcGetClientCallback)(SilcClient client,
* SilcClientConnection conn,
* SilcClientEntry *clients,
- * uint32 clients_count,
+ * SilcUInt32 clients_count,
* void *context);
*
* DESCRIPTION
typedef void (*SilcGetClientCallback)(SilcClient client,
SilcClientConnection conn,
SilcClientEntry *clients,
- uint32 clients_count,
+ SilcUInt32 clients_count,
void *context);
/****f* silcclient/SilcClientAPI/silc_client_get_clients
* SilcClientConnection conn,
* const char *nickname,
* const char *format,
- * uint32 *clients_count);
+ * SilcUInt32 *clients_count);
*
* DESCRIPTION
*
SilcClientConnection conn,
const char *nickname,
const char *format,
- uint32 *clients_count);
+ SilcUInt32 *clients_count);
/****f* silcclient/SilcClientAPI/silc_client_get_clients_by_list
*
*
* void silc_client_get_clients_by_list(SilcClient client,
* SilcClientConnection conn,
- * uint32 list_count,
+ * SilcUInt32 list_count,
* SilcBuffer client_id_list,
* SilcGetClientCallback completion,
* void *context);
***/
void silc_client_get_clients_by_list(SilcClient client,
SilcClientConnection conn,
- uint32 list_count,
+ SilcUInt32 list_count,
SilcBuffer client_id_list,
SilcGetClientCallback completion,
void *context);
* typedef void (*SilcGetChannelCallback)(SilcClient client,
* SilcClientConnection conn,
* SilcChannelEntry *channels,
- * uint32 channels_count,
+ * SilcUInt32 channels_count,
* void *context);
*
* DESCRIPTION
typedef void (*SilcGetChannelCallback)(SilcClient client,
SilcClientConnection conn,
SilcChannelEntry *channels,
- uint32 channels_count,
+ SilcUInt32 channels_count,
void *context);
/****f* silcclient/SilcClientAPI/silc_client_get_channel
*
* void silc_client_command_send(SilcClient client,
* SilcClientConnection conn,
- * SilcCommand command, uint16 ident,
- * uint32 argc, ...);
+ * SilcCommand command, SilcUInt16 ident,
+ * SilcUInt32 argc, ...);
*
* DESCRIPTION
*
*
***/
void silc_client_command_send(SilcClient client, SilcClientConnection conn,
- SilcCommand command, uint16 ident,
- uint32 argc, ...);
+ SilcCommand command, SilcUInt16 ident,
+ SilcUInt32 argc, ...);
/****f* silcclient/SilcClientAPI/silc_client_command_pending
*
*
* void silc_client_command_pending(SilcClientConnection conn,
* SilcCommand reply_cmd,
- * uint16 ident,
+ * SilcUInt16 ident,
* SilcCommandCb callback,
* void *context);
*
***/
void silc_client_command_pending(SilcClientConnection conn,
SilcCommand reply_cmd,
- uint16 ident,
+ SilcUInt16 ident,
SilcCommandCb callback,
void *context);
* SilcClientEntry client_entry,
* char *cipher,
* unsigned char *key,
- * uint32 key_len,
+ * SilcUInt32 key_len,
* bool generate_key,
* bool responder);
*
SilcClientEntry client_entry,
char *cipher,
unsigned char *key,
- uint32 key_len,
+ SilcUInt32 key_len,
bool generate_key,
bool responder);
* SilcPrivateMessageKeys
* silc_client_list_private_message_keys(SilcClient client,
* SilcClientConnection conn,
- * uint32 *key_count);
+ * SilcUInt32 *key_count);
*
* DESCRIPTION
*
SilcPrivateMessageKeys
silc_client_list_private_message_keys(SilcClient client,
SilcClientConnection conn,
- uint32 *key_count);
+ SilcUInt32 *key_count);
/****f* silcclient/SilcClientAPI/silc_client_free_private_message_keys
*
* SYNOPSIS
*
* void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys,
- * uint32 key_count);
+ * SilcUInt32 key_count);
*
* DESCRIPTION
*
*
***/
void silc_client_free_private_message_keys(SilcPrivateMessageKeys keys,
- uint32 key_count);
+ SilcUInt32 key_count);
/* Channel private key management (client_channel.c,
* int silc_client_add_channel_private_key(SilcClient client,
* SilcClientConnection conn,
* SilcChannelEntry channel,
+ * const char *name,
* char *cipher,
* char *hmac,
* unsigned char *key,
- * uint32 key_len);
+ * SilcUInt32 key_len);
*
* DESCRIPTION
*
* key in order to decrypt the messages. However, it is possible to have
* several private keys per one channel. In this case only some of the
* clients on the channel may know the one key and only some the other key.
+ * The `name' can be application given name for the key.
*
* The private key for channel is optional. If it is not set then the
* channel messages are encrypted using the channel key generated by the
int silc_client_add_channel_private_key(SilcClient client,
SilcClientConnection conn,
SilcChannelEntry channel,
+ const char *name,
char *cipher,
char *hmac,
unsigned char *key,
- uint32 key_len);
+ SilcUInt32 key_len);
/****f* silcclient/SilcClientAPI/silc_client_del_channel_private_keys
*
* silc_client_list_channel_private_keys(SilcClient client,
* SilcClientConnection conn,
* SilcChannelEntry channel,
- * uint32 *key_count);
+ * SilcUInt32 *key_count);
*
* DESCRIPTION
*
silc_client_list_channel_private_keys(SilcClient client,
SilcClientConnection conn,
SilcChannelEntry channel,
- uint32 *key_count);
+ SilcUInt32 *key_count);
/****f* silcclient/SilcClientAPI/silc_client_free_channel_private_keys
*
* SYNOPSIS
*
* void silc_client_free_channel_private_keys(SilcChannelPrivateKey *keys,
- * uint32 key_count);
+ * SilcUInt32 key_count);
*
* DESCRIPTION
*
*
***/
void silc_client_free_channel_private_keys(SilcChannelPrivateKey *keys,
- uint32 key_count);
+ SilcUInt32 key_count);
+
+/****f* silcclient/SilcClientAPI/silc_client_current_channel_private_key
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_current_channel_private_key(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcChannelEntry channel,
+ * SilcChannelPrivateKey key);
+ *
+ * DESCRIPTION
+ *
+ * Sets the `key' to be used as current channel private key on the
+ * `channel'. Packet sent after calling this function will be secured
+ * with `key'.
+ *
+ ***/
+void silc_client_current_channel_private_key(SilcClient client,
+ SilcClientConnection conn,
+ SilcChannelEntry channel,
+ SilcChannelPrivateKey key);
/* Key Agreement routines (client_keyagr.c) */
* SilcClientEntry client_entry,
* char *hostname,
* int port,
- * uint32 timeout_secs,
+ * SilcUInt32 timeout_secs,
* SilcKeyAgreementCallback completion,
* void *context);
*
const char *hostname,
const char *bindhost,
int port,
- uint32 timeout_secs,
+ SilcUInt32 timeout_secs,
SilcKeyAgreementCallback completion,
void *context);
* SilcClientConnection conn,
* SilcClientMonitorStatus status,
* SilcClientFileError error,
- * uint64 offset,
- * uint64 filesize,
+ * SilcUInt64 offset,
+ * SilcUInt64 filesize,
* SilcClientEntry client_entry,
- * uint32 session_id,
+ * SilcUInt32 session_id,
* const char *filepath,
* void *context);
*
SilcClientConnection conn,
SilcClientMonitorStatus status,
SilcClientFileError error,
- uint64 offset,
- uint64 filesize,
+ SilcUInt64 offset,
+ SilcUInt64 filesize,
SilcClientEntry client_entry,
- uint32 session_id,
+ SilcUInt32 session_id,
const char *filepath,
void *context);
* SilcClientFileMonitor monitor,
* void *monitor_context,
* const char *local_ip,
- * uint32 local_port,
+ * SilcUInt32 local_port,
* SilcClientEntry client_entry,
* const char *filepath);
- * uint32 *session_id);
+ * SilcUInt32 *session_id);
*
* DESCRIPTION
*
SilcClientFileMonitor monitor,
void *monitor_context,
const char *local_ip,
- uint32 local_port,
+ SilcUInt32 local_port,
SilcClientEntry client_entry,
const char *filepath,
- uint32 *session_id);
+ SilcUInt32 *session_id);
/****f* silcclient/SilcClientAPI/silc_client_file_receive
*
* SilcClientConnection conn,
* SilcClientFileMonitor monitor,
* void *monitor_context,
- * uint32 session_id);
+ * SilcUInt32 session_id);
*
* DESCRIPTION
*
SilcClientConnection conn,
SilcClientFileMonitor monitor,
void *monitor_context,
- uint32 session_id);
+ SilcUInt32 session_id);
/****f* silcclient/SilcClientAPI/silc_client_file_close
*
*
* SilcClientFileError silc_client_file_close(SilcClient client,
* SilcClientConnection conn,
- * uint32 session_id);
+ * SilcUInt32 session_id);
*
* DESCRIPTION
*
***/
SilcClientFileError silc_client_file_close(SilcClient client,
SilcClientConnection conn,
- uint32 session_id);
+ SilcUInt32 session_id);
#include "client.h"
#include "command.h"
projects / silc.git / blobdiff