X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcclient%2Fsilcapi.h;h=7bb917848aaecbcb56979466ed37ddc979c6bd79;hb=9a85416f729ef965606a688fffb6baa9d22927a5;hp=175af9bca4bcbeea53e56a4f803a485249af37cc;hpb=157f4732888e39853b3de6617eeeffd910a4a06d;p=silc.git diff --git a/lib/silcclient/silcapi.h b/lib/silcclient/silcapi.h index 175af9bc..7bb91784 100644 --- a/lib/silcclient/silcapi.h +++ b/lib/silcclient/silcapi.h @@ -74,6 +74,7 @@ typedef enum { 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; /***/ @@ -533,6 +534,25 @@ int silc_client_init(SilcClient client); ***/ 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 @@ -650,9 +670,9 @@ void silc_client_del_socket(SilcClient client, SilcSocketConnection sock); * * 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 * @@ -665,7 +685,7 @@ void silc_client_del_socket(SilcClient client, SilcSocketConnection sock); * if the key exchange could not be started. * ***/ -bool silc_client_start_key_exchange(SilcClient client, +void silc_client_start_key_exchange(SilcClient client, SilcClientConnection conn, int fd); @@ -944,11 +964,11 @@ bool silc_client_del_client(SilcClient client, SilcClientConnection conn, * * 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 * @@ -1097,13 +1117,30 @@ SilcServerEntry silc_client_get_server_by_id(SilcClient client, 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 * @@ -1114,7 +1151,7 @@ bool silc_client_del_server(SilcClient client, SilcClientConnection conn, * context. * ***/ -SilcClientCommandContext silc_client_command_alloc(); +SilcClientCommandContext silc_client_command_alloc(void); /****f* silcclient/SilcClientAPI/silc_client_command_free * @@ -1151,7 +1188,8 @@ SilcClientCommandContext silc_client_command_dup(SilcClientCommandContext ctx); * * SYNOPSIS * - * SilcClientCommand *silc_client_command_find(const char *name); + * SilcClientCommand silc_client_command_find(SilcClient client, + * const char *name); * * DESCRIPTION * @@ -1159,43 +1197,52 @@ SilcClientCommandContext silc_client_command_dup(SilcClientCommandContext ctx); * 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 * @@ -1204,7 +1251,6 @@ typedef void (*SilcClientPendingDestructor)(void *context); * void silc_client_command_pending(SilcClientConnection conn, * SilcCommand reply_cmd, * uint16 ident, - * SilcClientPendingDestructor destructor, * SilcCommandCb callback, * void *context); * @@ -1212,15 +1258,18 @@ typedef void (*SilcClientPendingDestructor)(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); @@ -1586,7 +1635,8 @@ void silc_client_free_channel_private_keys(SilcChannelPrivateKey *keys, 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, @@ -1682,7 +1732,8 @@ void silc_client_perform_key_agreement_fd(SilcClient client, * 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, @@ -1766,16 +1817,44 @@ silc_client_request_authentication_method(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, - SILC_CLIENT_FILE_MONITOR_SEND, - SILC_CLIENT_FILE_MONITOR_RECEIVE, + 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, - SILC_CLIENT_FILE_MONITOR_ERROR, + 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, @@ -1784,8 +1863,9 @@ typedef enum { SILC_CLIENT_FILE_NO_SUCH_FILE, SILC_CLIENT_FILE_PERMISSION_DENIED, } SilcClientFileError; +/***/ -/****f* silcclient/SilcClientAPI/silc_client_file_receive +/****f* silcclient/SilcClientAPI/SilcClientFileMonitor * * SYNOPSIS * @@ -1804,10 +1884,12 @@ typedef enum { * * Monitor callback that is called during the file transmission to * monitor the transmission process. The `status' indicates the current - * monitoring process. 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'. + * 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, @@ -1825,12 +1907,14 @@ typedef void (*SilcClientFileMonitor)(SilcClient client, * * SYNOPSIS * - * void silc_client_file_send(SilcClient client, - * SilcClientConnection conn, - * SilcClientFileMonitor monitor, - * void *monitor_context, - * SilcClientEntry client_entry, - * const char *filepath); + * uint32 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); * * DESCRIPTION *