silcapi.h
- Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
+ Author: Pekka Riikonen <priikone@silcnet.org>
Copyright (C) 2000 - 2001 Pekka Riikonen
SILC_KEY_AGREEMENT_ERROR, /* Unknown error occurred */
SILC_KEY_AGREEMENT_FAILURE, /* The protocol failed */
SILC_KEY_AGREEMENT_TIMEOUT, /* The protocol timeout */
+ SILC_KEY_AGREEMENT_ABORTED, /* The protocol aborted */
} SilcKeyAgreementStatus;
/***/
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, char *hostname,
- int port,
- SilcKeyAgreementCallback *completion,
+ SilcClientEntry client_entry, const char *hostname,
+ uint16 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
+ the `hostname' and `port'. The `session_id' is the file transfer
+ session and it can be used to either accept or reject the file
+ 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);
} SilcClientOperations;
/***/
+/****f* silcclient/SilcClientAPI/SilcNicknameFormatParse
+ *
+ * SYNOPSIS
+ *
+ * typedef void (*SilcNicknameFormatParse)(const char *nickname,
+ * char **ret_nickname);
+ *
+ * DESCRIPTION
+ *
+ * A callback function provided by the application for the library in
+ * SilcClientParams structure. This function parses the formatted
+ * nickname string `nickname' and returns the true nickname to the
+ * `ret_nickname' pointer. The library can call this function at
+ * any time.
+ *
+ ***/
+typedef void (*SilcNicknameFormatParse)(const char *nickname,
+ char **ret_nickname);
+
/****s* silcclient/SilcClientAPI/SilcClientParams
*
* NAME
in this time interval we'll assume the reply will not come at all.
If set to zero, the default value (2 seconds) will be used. */
unsigned int connauth_request_secs;
+
+ /* Nickname format string. This can be used to order the client library
+ to save the nicknames in the library in a certain format. Since
+ nicknames are not unique in SILC it is possible to have multiple same
+ nicknames. Using this format string it is possible to order the library
+ to separate the multiple same nicknames from each other. The format
+ types are defined below and they can appear in any order in the format
+ string. If this is NULL then default format is used which is the
+ default nickname without anything else. The string MUST be NULL
+ terminated.
+
+ Following format types are available:
+
+ %n nickname - the real nickname returned by the server (mandatory)
+ %h hostname - the stripped hostname of the client
+ %H full hostname - the full hostname of the client
+ %s server name - the server name the client is connected
+ %S full server - the full server name the client is connected
+ %a number - ascending number in case there are several
+ same nicknames (fe. nick@host and nick@host2)
+
+ Example format strings: "%n@%h%a" (fe. nick@host, nick@host2)
+ "%a!%n@%s" (fe. nick@server, 2!nick@server)
+ "%n@%H" (fe. nick@host.domain.com)
+
+ By default this format is employed to the nicknames by the libary
+ only when there appears multiple same nicknames. If the library has
+ only one nickname cached the nickname is saved as is and without the
+ defined format. If you want always to save the nickname in the defined
+ format set the boolean field `nickname_force_format' to value TRUE.
+ */
+ char nickname_format[32];
+
+ /* If this is set to TRUE then the `nickname_format' is employed to all
+ saved nicknames even if there are no multiple same nicknames in the
+ cache. By default this is FALSE, which means that the `nickname_format'
+ is employed only if the library will receive a nickname that is
+ already saved in the cache. It is recommended to leave this to FALSE
+ value. */
+ bool nickname_force_format;
+
+ /* A callback function provided by the application for the library to
+ parse the nickname from the formatted nickname string. Even though
+ the libary formats the nicknames the application knows generally the
+ format better so this function should be provided for the library
+ if the application sets the `nickname_format' field. The library
+ will call this to get the true nickname from the provided formatted
+ nickname string whenever it needs the true nickname. */
+ SilcNicknameFormatParse nickname_parse;
+
} SilcClientParams;
/***/
***/
void silc_client_run(SilcClient client);
+/****f* silcclient/SilcClientAPI/silc_client_run_one
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_run_one(SilcClient client);
+ *
+ * DESCRIPTION
+ *
+ * Runs the client and returns immeadiately. This function is used when
+ * the SILC Client object indicated by the `client' is run under some
+ * other scheduler, or event loop or main loop. On GUI applications,
+ * for example this may be desired to used to run the client under the
+ * GUI application's main loop. Typically the GUI application would
+ * register an idle task that calls this function multiple times in
+ * a second to quickly process the SILC specific data.
+ *
+ ***/
+void silc_client_run_one(SilcClient client);
+
/****f* silcclient/SilcClientAPI/silc_client_stop
*
* SYNOPSIS
*
* SYNOPSIS
*
- * int silc_client_start_key_exchange(SilcClient client,
- * SilcClientConnection conn,
- * int fd);
+ * void silc_client_start_key_exchange(SilcClient client,
+ * SilcClientConnection conn,
+ * int fd);
*
* DESCRIPTION
*
* 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.
+ * library. The library however may use this internally. Returns FALSE
+ * if the key exchange could not be started.
*
***/
-int silc_client_start_key_exchange(SilcClient client,
- SilcClientConnection conn,
- int fd);
+void silc_client_start_key_exchange(SilcClient client,
+ SilcClientConnection conn,
+ int fd);
/****f* silcclient/SilcClientAPI/silc_client_close_connection
*
*
* void silc_client_get_clients(SilcClient client,
* SilcClientConnection conn,
- * char *nickname,
- * char *server,
+ * const char *nickname,
+ * const char *server,
* SilcGetClientCallback completion,
* void *context);
*
***/
void silc_client_get_clients(SilcClient client,
SilcClientConnection conn,
- char *nickname,
- char *server,
+ const char *nickname,
+ const char *server,
SilcGetClientCallback completion,
void *context);
*
* SilcClientEntry *silc_client_get_clients_local(SilcClient client,
* SilcClientConnection conn,
- * char *nickname,
- * char *server,
+ * const char *nickname,
+ * const char *format,
* uint32 *clients_count);
*
* DESCRIPTION
*
* Same as silc_client_get_clients function but does not resolve anything
- * from the server. This checks local cache and returns all clients from
- * the local cache.
+ * from the server. This checks local cache and returns all matching
+ * clients from the local cache. If none was found this returns NULL.
+ * The `nickname' is the real nickname of the client, and the `format'
+ * is the formatted nickname to find exact match from multiple found
+ * entries. The format must be same as given in the SilcClientParams
+ * structure to the client library. If the `format' is NULL all found
+ * clients by `nickname' are returned. The caller must return the
+ * returned array.
*
***/
SilcClientEntry *silc_client_get_clients_local(SilcClient client,
SilcClientConnection conn,
- char *nickname,
- char *server,
+ const char *nickname,
+ const char *format,
uint32 *clients_count);
/****f* silcclient/SilcClientAPI/silc_client_get_clients_by_list
*
* SYNOPSIS
*
- * typedef void (*SilcGetClientCallback)(SilcClient client,
- * SilcClientConnection conn,
- * SilcClientEntry *clients,
- * uint32 clients_count,
- * void *context);
+ * typedef void (*SilcGetChannelCallback)(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcChannelEntry *channels,
+ * uint32 channels_count,
+ * void *context);
*
* DESCRIPTION
*
SilcClientConnection conn,
SilcChannelID *channel_id);
-/****f* silcclient/SilcClientAPI/silc_client_get_channel
+/****f* silcclient/SilcClientAPI/silc_client_get_channel_by_id_resolve
*
* SYNOPSIS
*
bool silc_client_del_server(SilcClient client, SilcClientConnection conn,
SilcServerEntry server);
+/****f* silcclient/SilcClientAPI/silc_client_on_channel
+ *
+ * SYNOPSIS
+ *
+ * SilcChannelUser silc_client_on_channel(SilcChannelEntry channel,
+ * SilcClientEntry client_entry);
+ *
+ * DESCRIPTION
+ *
+ * Returns the ChannelUser entry if the `client_entry' is joined on the
+ * channel indicated by the `channel'. NULL if client is not joined on
+ * the channel.
+ *
+ ***/
+SilcChannelUser silc_client_on_channel(SilcChannelEntry channel,
+ SilcClientEntry client_entry);
+
/* Command management (command.c) */
/****f* silcclient/SilcClientAPI/silc_client_command_alloc
*
* SYNOPSIS
*
- * SilcClientCommandContext silc_client_command_alloc();
+ * SilcClientCommandContext silc_client_command_alloc(void);
*
* DESCRIPTION
*
* context.
*
***/
-SilcClientCommandContext silc_client_command_alloc();
+SilcClientCommandContext silc_client_command_alloc(void);
/****f* silcclient/SilcClientAPI/silc_client_command_free
*
*
* SYNOPSIS
*
- * SilcClientCommand *silc_client_command_find(const char *name);
+ * SilcClientCommand silc_client_command_find(SilcClient client,
+ * const char *name);
*
* DESCRIPTION
*
* command is not found. See the `command.[ch]' for the command list.
*
***/
-SilcClientCommand *silc_client_command_find(const char *name);
+SilcClientCommand silc_client_command_find(SilcClient client,
+ const char *name);
-/****f* silcclient/SilcClientAPI/silc_client_send_command
+/****f* silcclient/SilcClientAPI/silc_client_command_call
*
* SYNOPSIS
*
- * void silc_client_send_command(SilcClient client,
- * SilcClientConnection conn,
- * SilcCommand command, uint16 ident,
- * uint32 argc, ...);
+ * void silc_client_command_call(SilcClientCommand command);
*
* DESCRIPTION
*
- * Generic function to send any command. The arguments must be sent already
- * encoded into correct form and in correct order.
+ * Calls the command (executes it). Application can call this after
+ * it has allocated the SilcClientCommandContext with the function
+ * silc_client_command_alloc and found the command from the client
+ * library by calling silc_client_command_find. This will execute
+ * the command.
+ *
+ * Application can call the command function directly too if it
+ * wishes to do so. See the command.h for details of the
+ * SilcClientCommand structure.
*
***/
-void silc_client_send_command(SilcClient client, SilcClientConnection conn,
- SilcCommand command, uint16 ident,
- uint32 argc, ...);
+void silc_client_command_call(SilcClientCommand command,
+ SilcClientCommandContext cmd);
-/****f* silcclient/SilcClientAPI/SilcClientPendingDestructor
+/****f* silcclient/SilcClientAPI/silc_client_command_send
*
* SYNOPSIS
*
- * typedef void (*SilcClientPendingDestructor)(void *context);
+ * void silc_client_command_send(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcCommand command, uint16 ident,
+ * uint32 argc, ...);
*
* DESCRIPTION
*
- * Pending Command callback destructor. This is called after calling the
- * pending callback or if error occurs while processing the pending command.
- * If error occurs then the callback won't be called at all, and only this
- * destructor is called. The `context' is the context given for the function
- * silc_client_command_pending.
+ * Generic function to send any command. The arguments must be sent already
+ * encoded into correct form and in correct order. If application wants
+ * to perform the commands by itself, it can do so and send the data
+ * directly to the server using this function. If application is using
+ * the silc_client_command_call, this function is usually not used.
*
***/
-typedef void (*SilcClientPendingDestructor)(void *context);
+void silc_client_command_send(SilcClient client, SilcClientConnection conn,
+ SilcCommand command, uint16 ident,
+ uint32 argc, ...);
/****f* silcclient/SilcClientAPI/silc_client_command_pending
*
* void silc_client_command_pending(SilcClientConnection conn,
* SilcCommand reply_cmd,
* uint16 ident,
- * SilcClientPendingDestructor destructor,
* SilcCommandCb callback,
* void *context);
*
*
* Add new pending command to be executed when reply to a command has been
* received. The `reply_cmd' is the command that will call the `callback'
- * with `context' when reply has been received. If `ident is non-zero
+ * with `context' when reply has been received. If `ident' is non-zero
* the `callback' will be executed when received reply with command
* identifier `ident'.
*
+ * Note that the application is notified about the received command
+ * reply through the `command_reply' client operation before calling
+ * the `callback` pending command callback.
+ *
***/
void silc_client_command_pending(SilcClientConnection conn,
SilcCommand reply_cmd,
uint16 ident,
- SilcClientPendingDestructor destructor,
SilcCommandCb callback,
void *context);
void silc_client_send_key_agreement(SilcClient client,
SilcClientConnection conn,
SilcClientEntry client_entry,
- char *hostname,
+ const char *hostname,
+ const char *bindhost,
int port,
uint32 timeout_secs,
SilcKeyAgreementCallback completion,
* before the key agreement protocol has been performed. After it has
* been performed the library will automatically unbind the port. The
* `client_entry' is the client to which we sent the key agreement
- * request.
+ * request. The key agreement completion callback will be called
+ * with SILC_KEY_AGREEMENT_ABORTED status.
*
***/
void silc_client_abort_key_agreement(SilcClient client,
SilcConnectionAuthRequest callback,
void *context);
+/****d* silcclient/SilcClientAPI/SilcClientMonitorStatus
+ *
+ * NAME
+ *
+ * typedef enum { ... } SilcClientMonitorStatus;
+ *
+ * DESCRIPTION
+ *
+ * File transmission session status types. These will indicate
+ * the status of the file transmission session.
+ *
+ * SOURCE
+ */
+typedef enum {
+ SILC_CLIENT_FILE_MONITOR_KEY_AGREEMENT, /* In key agreemenet phase */
+ SILC_CLIENT_FILE_MONITOR_SEND, /* Sending file */
+ SILC_CLIENT_FILE_MONITOR_RECEIVE, /* Receiving file */
+ SILC_CLIENT_FILE_MONITOR_GET,
+ SILC_CLIENT_FILE_MONITOR_PUT,
+ SILC_CLIENT_FILE_MONITOR_CLOSED, /* Session closed */
+ SILC_CLIENT_FILE_MONITOR_ERROR, /* Error during session */
+} SilcClientMonitorStatus;
+/***/
+
+/****d* silcclient/SilcClientAPI/SilcClientFileError
+ *
+ * NAME
+ *
+ * typedef enum { ... } SilcClientFileError;
+ *
+ * DESCRIPTION
+ *
+ * File transmission error types. These types are returned by
+ * some of the file transmission functions, and by the monitor
+ * callback to indicate error.
+ *
+ * SOURCE
+ */
+typedef enum {
+ SILC_CLIENT_FILE_OK,
+ SILC_CLIENT_FILE_ERROR,
+ SILC_CLIENT_FILE_UNKNOWN_SESSION,
+ SILC_CLIENT_FILE_ALREADY_STARTED,
+ SILC_CLIENT_FILE_NO_SUCH_FILE,
+ SILC_CLIENT_FILE_PERMISSION_DENIED,
+ SILC_CLIENT_FILE_KEY_AGREEMENT_FAILED,
+} SilcClientFileError;
+/***/
+
+/****f* silcclient/SilcClientAPI/SilcClientFileMonitor
+ *
+ * SYNOPSIS
+ *
+ * typedef void (*SilcClientFileMonitor)(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientMonitorStatus status,
+ * SilcClientFileError error,
+ * uint64 offset,
+ * uint64 filesize,
+ * SilcClientEntry client_entry,
+ * uint32 session_id,
+ * const char *filepath,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * Monitor callback that is called during the file transmission to
+ * monitor the transmission process. The `status' indicates the current
+ * monitoring process. The `error' will indicate the error type
+ * if `status' is SILC_CLIENT_FILE_MONITOR_ERROR. The `offset' is the
+ * currently transmitted amount of total `filesize'. The `client_entry'
+ * indicates the remote client, and the transmission session ID is the
+ * `session_id'. The filename being transmitted is indicated by the
+ * `filepath'.
+ *
+ ***/
+typedef void (*SilcClientFileMonitor)(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientMonitorStatus status,
+ SilcClientFileError error,
+ uint64 offset,
+ uint64 filesize,
+ SilcClientEntry client_entry,
+ uint32 session_id,
+ const char *filepath,
+ void *context);
+
+/****f* silcclient/SilcClientAPI/silc_client_file_send
+ *
+ * SYNOPSIS
+ *
+ * SilcClientFileError
+ * silc_client_file_send(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientFileMonitor monitor,
+ * void *monitor_context,
+ * const char *local_ip,
+ * uint32 local_port,
+ * SilcClientEntry client_entry,
+ * const char *filepath);
+ * uint32 *session_id);
+ *
+ * DESCRIPTION
+ *
+ * Sends a file indicated by the `filepath' to the remote client
+ * indicated by the `client_entry'. This will negotiate a secret key
+ * with the remote client before actually starting the transmission of
+ * the file. The `monitor' callback will be called to monitor the
+ * transmission of the file.
+ *
+ * This returns a file session ID for the file transmission to the
+ * `session_id' pointer.. It can be used to close the session (and
+ * abort the file transmission) by calling the silc_client_file_close
+ * function. The session ID is also returned in the `monitor' callback.
+ *
+ * If the `local_ip' is provided then this will try to bind the
+ * listener for key exchange protocol to that IP. If `local_port' is
+ * non-zero that port is used. If `local_ip' is NULL then this will
+ * automatically attempt to bind it to local IP address of the machine.
+ * If that fails then this does not bind to any address and port, and
+ * assume that the remote client will provide the listener for the
+ * key exchange protocol.
+ *
+ * If error will occur during the file transfer process the error
+ * status will be returned in the monitor callback. In this case
+ * the application must call silc_client_file_close to close the
+ * session.
+ *
+ ***/
+SilcClientFileError
+silc_client_file_send(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientFileMonitor monitor,
+ void *monitor_context,
+ const char *local_ip,
+ uint32 local_port,
+ SilcClientEntry client_entry,
+ const char *filepath,
+ uint32 *session_id);
+
+/****f* silcclient/SilcClientAPI/silc_client_file_receive
+ *
+ * SYNOPSIS
+ *
+ * SilcClientFileError
+ * silc_client_file_receive(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientFileMonitor monitor,
+ * void *monitor_context,
+ * uint32 session_id);
+ *
+ * DESCRIPTION
+ *
+ * Receives a file from a client indicated by the `client_entry'. The
+ * `session_id' indicates the file transmission session and it has been
+ * received in the `ftp' client operation function. This will actually
+ * perform the key agreement protocol with the remote client before
+ * actually starting the file transmission. The `monitor' callback
+ * will be called to monitor the transmission.
+ *
+ * If error will occur during the file transfer process the error
+ * status will be returned in the monitor callback. In this case
+ * the application must call silc_client_file_close to close the
+ * session.
+ *
+ ***/
+SilcClientFileError
+silc_client_file_receive(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientFileMonitor monitor,
+ void *monitor_context,
+ uint32 session_id);
+
+/****f* silcclient/SilcClientAPI/silc_client_file_close
+ *
+ * SYNOPSIS
+ *
+ * SilcClientFileError silc_client_file_close(SilcClient client,
+ * SilcClientConnection conn,
+ * uint32 session_id);
+ *
+ * DESCRIPTION
+ *
+ * Closes file transmission session indicated by the `session_id'.
+ * If file transmission is being conducted it will be aborted
+ * automatically. This function is also used to close the session
+ * after successful file transmission. This function can be used
+ * also to reject incoming file transmission request.
+ *
+ ***/
+SilcClientFileError silc_client_file_close(SilcClient client,
+ SilcClientConnection conn,
+ uint32 session_id);
+
#endif