X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcclient%2Fsilcapi.h;h=22266d68248e6eb5d396c337641ef6c8d306880c;hb=017dec75a98209fbef49eb496c2269b0c49e736d;hp=1dec749bb7b95c954173cb5f59854fdc679ee4e3;hpb=7f9a1c08b891a4f549458e5a6b6264e5ea18248b;p=silc.git diff --git a/lib/silcclient/silcapi.h b/lib/silcclient/silcapi.h index 1dec749b..22266d68 100644 --- a/lib/silcclient/silcapi.h +++ b/lib/silcclient/silcapi.h @@ -2,7 +2,7 @@ silcapi.h - Author: Pekka Riikonen + Author: Pekka Riikonen Copyright (C) 2000 - 2001 Pekka Riikonen @@ -166,6 +166,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 @@ -277,15 +303,13 @@ typedef struct { 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 @@ -327,6 +351,25 @@ typedef struct { } 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 @@ -351,6 +394,62 @@ typedef struct { /* Rekey timeout in seconds. The client will perform rekey in this 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; /***/ @@ -553,12 +652,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); +bool silc_client_start_key_exchange(SilcClient client, + SilcClientConnection conn, + int fd); /****f* silcclient/SilcClientAPI/silc_client_close_connection * @@ -688,8 +788,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); * @@ -710,8 +810,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); @@ -721,21 +821,26 @@ 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. * ***/ 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 @@ -1600,4 +1705,55 @@ 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); + #endif