X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcclient%2Fsilcapi.h;h=7bb917848aaecbcb56979466ed37ddc979c6bd79;hb=9a85416f729ef965606a688fffb6baa9d22927a5;hp=ed5c5f0f94d4a1f94577c4695e2e03f94b59f031;hpb=a13a1924bf35d6f8d9422a2c60364329fd6511b3;p=silc.git diff --git a/lib/silcclient/silcapi.h b/lib/silcclient/silcapi.h index ed5c5f0f..7bb91784 100644 --- a/lib/silcclient/silcapi.h +++ b/lib/silcclient/silcapi.h @@ -1,29 +1,29 @@ -/****h* silcclient/silcapi.h - * - * NAME - * - * silcapi.h - * - * COPYRIGHT - * - * Author: Pekka Riikonen - * - * Copyright (C) 2000 - 2001 Pekka Riikonen - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. +/* + + silcapi.h + + Author: Pekka Riikonen + + Copyright (C) 2000 - 2001 Pekka Riikonen + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + +*/ + +/****h* silcclient/SilcClientAPI * * DESCRIPTION * - * This file defines the SILC Client Library API for the application. The - * client operations are defined first. These are callback functions that + * This interface defines the SILC Client Library API for the application. + * The client operations are defined first. These are callback functions that * the application MUST implement since the library may call the functions * at any time. At the end of file is the API for the application that * it can use from the library. This is the only file that the application @@ -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; /***/ @@ -166,6 +167,32 @@ typedef void (*SilcAskPassphrase)(unsigned char *passphrase, ***/ typedef void (*SilcVerifyPublicKey)(bool success, void *context); +/****f* silcclient/SilcClientAPI/SilcGetAuthMeth + * + * SYNOPSIS + * + * typedef void (*SilcGetAuthMeth)(bool success, + * SilcProtocolAuthMeth auth_meth, + * const unsigned char *auth_data, + * uint32 auth_data_len, void *context); + * + * DESCRIPTION + * + * Authentication method resolving callback. This is called by the + * application to return the resolved authentication method. The client + * library has called the get_auth_method client operation and given + * this function pointer as argument. The `success' will indicate whether + * the authentication method could be resolved. The `auth_meth' is the + * resolved authentication method. The `auth_data' and the `auth_data_len' + * are the resolved authentication data. The `context' is the libary's + * context sent to the get_auth_method client operation. + * + ***/ +typedef void (*SilcGetAuthMeth)(bool success, + SilcProtocolAuthMeth auth_meth, + const unsigned char *auth_data, + uint32 auth_data_len, void *context); + /****d* silcclient/SilcClientAPI/SilcClientMessageType * * NAME @@ -268,22 +295,22 @@ typedef struct { /* 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. */ + the SilcClientConnection objecet which it should save somewhere. + If the `success' is FALSE the application must always call the function + silc_client_close_connection. */ void (*connect)(SilcClient client, SilcClientConnection conn, int success); /* Called to indicate that connection was disconnected to the server. */ void (*disconnect)(SilcClient client, SilcClientConnection conn); /* Find authentication method and authentication data by hostname and - port. The hostname may be IP address as well. The found authentication - method and authentication data is returned to `auth_meth', `auth_data' - and `auth_data_len'. The function returns TRUE if authentication method - is found and FALSE if not. `conn' may be NULL. */ - int (*get_auth_method)(SilcClient client, SilcClientConnection conn, - char *hostname, uint16 port, - SilcProtocolAuthMeth *auth_meth, - unsigned char **auth_data, - uint32 *auth_data_len); + port. The hostname may be IP address as well. When the authentication + method has been resolved the `completion' callback with the found + authentication method and authentication data is called. The `conn' + may be NULL. */ + void (*get_auth_method)(SilcClient client, SilcClientConnection conn, + char *hostname, uint16 port, + SilcGetAuthMeth completion, void *context); /* Verifies received public key. The `conn_type' indicates which entity (server, client etc.) has sent the public key. If user decides to trust @@ -318,13 +345,41 @@ typedef struct { 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 @@ -340,9 +395,71 @@ typedef struct { * SOURCE */ typedef struct { + /* Number of maximum tasks the client library's scheduler can handle. + If set to zero, the default value will be used (200). For WIN32 + systems this should be set to 64 as it is the hard limit dictated + by the WIN32. */ + int task_max; + /* Rekey timeout in seconds. The client will perform rekey in this - time interval. If set to zero, default value will be used. */ + time interval. If set to zero, the default value will be used. */ unsigned int rekey_secs; + + /* Connection authentication method request timeout. If server does not + reply back the current authentication method when we've requested it + 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; /***/ @@ -417,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 @@ -534,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 * @@ -545,12 +681,13 @@ void silc_client_del_socket(SilcClient client, SilcSocketConnection sock); * 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 * @@ -680,8 +817,8 @@ typedef void (*SilcGetClientCallback)(SilcClient client, * * void silc_client_get_clients(SilcClient client, * SilcClientConnection conn, - * char *nickname, - * char *server, + * const char *nickname, + * const char *server, * SilcGetClientCallback completion, * void *context); * @@ -702,8 +839,8 @@ typedef void (*SilcGetClientCallback)(SilcClient client, ***/ void silc_client_get_clients(SilcClient client, SilcClientConnection conn, - char *nickname, - char *server, + const char *nickname, + const char *server, SilcGetClientCallback completion, void *context); @@ -713,21 +850,27 @@ void silc_client_get_clients(SilcClient client, * * 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 @@ -817,33 +960,15 @@ void silc_client_get_client_by_id_resolve(SilcClient client, bool silc_client_del_client(SilcClient client, SilcClientConnection conn, SilcClientEntry client_entry); -/****f* silcclient/SilcClientAPI/silc_client_del_client_by_id - * - * SYNOPSIS - * - * bool silc_client_del_client_by_id(SilcClient client, - * SilcClientConnection conn, - * SilcClientID *client_id); - * - * DESCRIPTION - * - * Removes client from local cache by the Client ID indicated by - * the `Client ID'. Returns TRUE if the deletion were successful. - * - ***/ -bool silc_client_del_client_by_id(SilcClient client, - SilcClientConnection conn, - SilcClientID *client_id); - /****f* silcclient/SilcClientAPI/SilcGetChannelCallback * * 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 * @@ -878,7 +1003,7 @@ SilcChannelEntry silc_client_get_channel(SilcClient client, SilcClientConnection conn, char *channel); -/****f* silcclient/SilcClientAPI/silc_client_get_channel +/****f* silcclient/SilcClientAPI/silc_client_get_channel_id_resolve * * SYNOPSIS * @@ -899,7 +1024,7 @@ SilcChannelEntry silc_client_get_channel_by_id(SilcClient client, SilcClientConnection conn, SilcChannelID *channel_id); -/****f* silcclient/SilcClientAPI/silc_client_get_channel +/****f* silcclient/SilcClientAPI/silc_client_get_channel_by_id_resolve * * SYNOPSIS * @@ -923,6 +1048,23 @@ void silc_client_get_channel_by_id_resolve(SilcClient client, SilcGetChannelCallback completion, void *context); +/****f* silcclient/SilcClientAPI/silc_client_del_channel + * + * SYNOPSIS + * + * bool silc_client_del_channel(SilcClient client, + * SilcClientConnection conn, + * SilcChannelEntry channel) + * + * DESCRIPTION + * + * Removes channel from local cache by the channel entry indicated by + * the `channel'. Returns TRUE if the deletion were successful. + * + ***/ +bool silc_client_del_channel(SilcClient client, SilcClientConnection conn, + SilcChannelEntry channel); + /****f* silcclient/SilcClientAPI/silc_client_get_server * * SYNOPSIS @@ -959,6 +1101,38 @@ SilcServerEntry silc_client_get_server_by_id(SilcClient client, SilcClientConnection conn, SilcServerID *server_id); +/****f* silcclient/SilcClientAPI/silc_client_del_server + * + * SYNOPSIS + * + * bool silc_client_del_server(SilcClient client, SilcClientConnection conn, + * SilcServerEntry server); + * + * DESCRIPTION + * + * Removes server from local cache by the server entry indicated by + * the `server'. Returns TRUE if the deletion were successful. + * + ***/ +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) */ @@ -966,7 +1140,7 @@ SilcServerEntry silc_client_get_server_by_id(SilcClient client, * * SYNOPSIS * - * SilcClientCommandContext silc_client_command_alloc(); + * SilcClientCommandContext silc_client_command_alloc(void); * * DESCRIPTION * @@ -977,7 +1151,7 @@ SilcServerEntry silc_client_get_server_by_id(SilcClient client, * context. * ***/ -SilcClientCommandContext silc_client_command_alloc(); +SilcClientCommandContext silc_client_command_alloc(void); /****f* silcclient/SilcClientAPI/silc_client_command_free * @@ -1014,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 * @@ -1022,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 * @@ -1067,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); * @@ -1075,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); @@ -1233,7 +1419,7 @@ silc_client_list_private_message_keys(SilcClient client, SilcClientConnection conn, uint32 *key_count); -/****f* silcclient/SilcClientAPI/silc_client_list_private_message_keys +/****f* silcclient/SilcClientAPI/silc_client_free_private_message_keys * * SYNOPSIS * @@ -1449,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, @@ -1545,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, @@ -1578,4 +1766,246 @@ void silc_client_set_away_message(SilcClient client, SilcClientConnection conn, char *message); + +/****f* silcclient/SilcClientAPI/SilcConnectionAuthRequest + * + * SYNOPSIS + * + * typedef void (*SilcConnectionAuthRequest)(SilcClient client, + * SilcClientConnection conn, + * SilcAuthMethod auth_meth, + * void *context); + * + * DESCRIPTION + * + * Connection authentication method request callback. This is called + * by the client library after it has received the authentication method + * that the application requested by calling the function + * silc_client_request_authentication_method. + * + ***/ +typedef void (*SilcConnectionAuthRequest)(SilcClient client, + SilcClientConnection conn, + SilcAuthMethod auth_meth, + void *context); + +/****f* silcclient/SilcClientAPI/silc_client_request_authentication_method + * + * SYNOPSIS + * + * void + * silc_client_request_authentication_method(SilcClient client, + * SilcClientConnection conn, + * SilcConnectionAuthRequest + * callback, + * void *context); + * + * DESCRIPTION + * + * This function can be used to request the current authentication method + * from the server. This may be called when connecting to the server + * and the client library requests the authentication data from the + * application. If the application does not know the current authentication + * method it can request it from the server using this function. + * The `callback' with `context' will be called after the server has + * replied back with the current authentication method. + * + ***/ +void +silc_client_request_authentication_method(SilcClient client, + SilcClientConnection conn, + 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, +} 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 + * + * 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 + * + * 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. 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. This returns 0 if the + * 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); + +/****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