X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcclient%2Fsilcapi.h;h=7bb917848aaecbcb56979466ed37ddc979c6bd79;hb=9a85416f729ef965606a688fffb6baa9d22927a5;hp=e7d7b9cc25355e491e33f5053c5d803d25df0495;hpb=70fceb1b71e76e1ff2719988cad63a9113b38641;p=silc.git diff --git a/lib/silcclient/silcapi.h b/lib/silcclient/silcapi.h index e7d7b9cc..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); @@ -843,7 +863,8 @@ void silc_client_get_clients(SilcClient client, * 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. + * clients by `nickname' are returned. The caller must return the + * returned array. * ***/ SilcClientEntry *silc_client_get_clients_local(SilcClient client, @@ -943,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 * @@ -1096,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 * @@ -1113,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 * @@ -1150,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 * @@ -1158,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 * @@ -1203,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); * @@ -1211,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); @@ -1585,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, @@ -1681,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, @@ -1765,21 +1817,62 @@ 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_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_CLOSE, + SILC_CLIENT_FILE_MONITOR_CLOSED, /* Session closed */ + SILC_CLIENT_FILE_MONITOR_ERROR, /* Error during session */ } SilcClientMonitorStatus; +/***/ -/****f* silcclient/SilcClientAPI/silc_client_file_receive +/****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, +} SilcClientFileError; +/***/ + +/****f* silcclient/SilcClientAPI/SilcClientFileMonitor * * SYNOPSIS * * typedef void (*SilcClientFileMonitor)(SilcClient client, * SilcClientConnection conn, * SilcClientMonitorStatus status, + * SilcClientFileError error, * uint64 offset, * uint64 filesize, * SilcClientEntry client_entry, @@ -1791,15 +1884,18 @@ 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, SilcClientConnection conn, SilcClientMonitorStatus status, + SilcClientFileError error, uint64 offset, uint64 filesize, SilcClientEntry client_entry, @@ -1811,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 * @@ -1833,11 +1931,26 @@ typedef void (*SilcClientFileMonitor)(SilcClient client, * file indicated by the `filepath' is being transmitted to the remote * client indicated by the `client_entry', already. * + * 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. + * ***/ 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); @@ -1845,12 +1958,12 @@ uint32 silc_client_file_send(SilcClient client, * * SYNOPSIS * - * bool silc_client_file_receive(SilcClient client, - * SilcClientConnection conn, - * SilcClientFileMonitor monitor, - * void *monitor_context, - * SilcClientEntry client_entry, - * uint32 session_id); + * SilcClientFileError + * silc_client_file_receive(SilcClient client, + * SilcClientConnection conn, + * SilcClientFileMonitor monitor, + * void *monitor_context, + * uint32 session_id); * * DESCRIPTION * @@ -1861,21 +1974,26 @@ uint32 silc_client_file_send(SilcClient client, * 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. + * ***/ -bool silc_client_file_receive(SilcClient client, - SilcClientConnection conn, - SilcClientFileMonitor monitor, - void *monitor_context, - SilcClientEntry client_entry, - uint32 session_id); +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 * - * bool silc_client_file_close(SilcClient client, - * SilcClientConnection conn, - * uint32 session_id); + * SilcClientFileError silc_client_file_close(SilcClient client, + * SilcClientConnection conn, + * uint32 session_id); * * DESCRIPTION * @@ -1883,12 +2001,11 @@ bool silc_client_file_receive(SilcClient client, * 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. Returns TRUE - * if the session was closed and FALSE if such session does not exist. + * also to reject incoming file transmission request. * ***/ -bool silc_client_file_close(SilcClient client, - SilcClientConnection conn, - uint32 session_id); +SilcClientFileError silc_client_file_close(SilcClient client, + SilcClientConnection conn, + uint32 session_id); #endif