X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcclient%2Fsilcclient_entry.h;h=4b57f859bcde386d125d05cc3be20e44160df1ad;hb=52e57c880aba9c5e89f59d962eb9af75670b76e0;hp=56cbaf7d6fe5c1c2b82eb0e97e15d257301310ec;hpb=5e0534a2c468177c5c2b0c503f529380e8dd3df4;p=silc.git diff --git a/lib/silcclient/silcclient_entry.h b/lib/silcclient/silcclient_entry.h index 56cbaf7d..4b57f859 100644 --- a/lib/silcclient/silcclient_entry.h +++ b/lib/silcclient/silcclient_entry.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2006 Pekka Riikonen + Copyright (C) 2006 - 2007 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 @@ -17,6 +17,25 @@ */ +/****h* silcclient/Client Library Interface + * + * DESCRIPTION + * + * This header file includes the SilcClientEntry, SilcChannelEntry and + * SilcServer entry structures and various routines to search, resolve and + * handle these structures. + * + * All entries (SilcClientEntry, SilcChannelEntry and SilcServerEntry) are + * reference counted. If application wishes to save an entry pointer it must + * always first acquire a reference. The reference must be released once the + * entry is not needed anymore. If application wants to read any data from + * the entry structure it must first lock the entry. This protects access to + * the entries in multithreaded environment. If threads are not used, locking + * the entries is not needed. They however still must be referenced even + * when threads are not used. + * + ***/ + #ifndef SILCCLIENT_ENTRY_H #define SILCCLIENT_ENTRY_H @@ -49,7 +68,7 @@ * it should always duplicated them. * * None of the string arrays are set if the first character is '\0'. - * All string arrays are always NULL terminated. + * All string arrays are always zero ('\0') terminated. * * If application stores the SilcClientEntry it must always take * a reference of it by calling silc_client_ref_client function. The @@ -59,7 +78,7 @@ * SOURCE */ struct SilcClientEntryStruct { - char nickname[128 + 1]; /* Nickname */ + char nickname[256 + 1]; /* Nickname */ char username[128 + 1]; /* Username */ char hostname[256 + 1]; /* Hostname */ char server [256 + 1]; /* SILC server name */ @@ -105,6 +124,7 @@ struct SilcClientEntryStruct { */ struct SilcChannelEntryStruct { char *channel_name; /* Channel name */ + char server[256 + 1]; /* SILC server name */ char *topic; /* Current topic, may be NULL */ SilcPublicKey founder_key; /* Founder key, may be NULL */ SilcDList channel_pubkeys; /* Channel public keys, may be NULL */ @@ -114,6 +134,8 @@ struct SilcChannelEntryStruct { SilcHashTable user_list; /* Joined users. Key to hash table is SilcClientEntry, context is SilcChannelUser. */ + const char *cipher; /* Current channel cipher algorithm*/ + const char *hmac; /* Current channel HMAC algorithm */ void *context; /* Application specific context */ SilcChannelEntryInternal internal; @@ -208,10 +230,17 @@ typedef void (*SilcGetClientCallback)(SilcClient client, * before reading any data from the `client_entry'. The lock must be * unlocked with silc_client_unlock_client. * + * NOTES + * * The entry must be unlocked before calling any Client Library API - * functions where the entry is given as argument. + * functions where the entry is given as argument, unless otherwise stated. + * + * The entry should not be locked for long periods of time. For example, + * it is not appropriate to hold the lock while waiting user interface to + * be drawn. The appropriate way is to read the data and duplicate it if + * necessary, unlock the entry, then draw on the user interface. * - * This function is not needed if application is not multithreaded + * This function is not needed if application is not multithreaded. * ***/ void silc_client_lock_client(SilcClientEntry client_entry); @@ -245,7 +274,7 @@ void silc_client_unlock_client(SilcClientEntry client_entry); * after it is not needed anymore. Returns `client_entry'. * ***/ -SilcClientEntry silc_client_ref_client(SilcClient client, +SilcClientEntry silc_client_ref_client(SilcClient client, SilcClientConnection conn, SilcClientEntry client_entry); @@ -299,8 +328,13 @@ void silc_client_list_free(SilcClient client, SilcClientConnection conn, * completion callback will be called when the client entries has been * found. After the server returns the client information it is cached * and can be accesses locally at a later time. The resolving is done - * with IDENTIFY command. The `server' may be NULL. Returns 0 on - * error and the command identifier used with the command otherwise. + * with IDENTIFY command. The `server' may be NULL. The server + * associated with the nickname may be in the `nickname' (nick@server). + * The `nickname' may also be a formatted nickname in which case the + * formatting is ignored and the base nickname is used. If the nickname + * is formatted it must be formatted as defined in SilcClientParams. + * Returns 0 on error and the command identifier used with the command + * otherwise. * * NOTES * @@ -342,8 +376,13 @@ SilcUInt16 silc_client_get_clients(SilcClient client, * completion callback will be called when the client entries has been * found. After the server returns the client information it is cached * and can be accesses locally at a later time. The resolving is done - * with WHOIS command. The `server' may be NULL. Returns 0 on error, - * and the command identifier used with the command otherwise. + * with WHOIS command. The `server' may be NULL. The server + * associated with the nickname may be in the `nickname' (nick@server). + * The `nickname' may also be a formatted nickname in which case the + * formatting is ignored and the base nickname is used. If the nickname + * is formatted it must be formatted as defined in SilcClientParams. + * Returns 0 on error and the command identifier used with the command + * otherwise. * * If the `attributes' is non-NULL then the buffer includes Requested * Attributes which can be used to fetch very detailed information @@ -374,19 +413,20 @@ SilcUInt16 silc_client_get_clients_whois(SilcClient client, * SilcDList silc_client_get_clients_local(SilcClient client, * SilcClientConnection conn, * const char *nickname, - * const char *format); + * SilcBool return_all); * * DESCRIPTION * * Same as silc_client_get_clients function but does not resolve anything - * 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 free the - * returned list by silc_client_list_free function. + * from the server. This checks local cache and returns matching clients + * from the local cache. If none was found this returns NULL. The + * `nickname' is the nickname to find and it may be a formatted nickname + * or a base nickname. If the `return_all' is TRUE this call will return + * all clients matching the `nickname' base. If it is FALSE this will + * return the exact match if `nickname' is a formatted nickname or the + * first matching nickname if it is not formatted. The formatted nickname + * must of the format specified in SilcClientParams. The caller must free + * the returned list by calling silc_client_list_free function. * * NOTES * @@ -401,87 +441,7 @@ SilcUInt16 silc_client_get_clients_whois(SilcClient client, SilcDList silc_client_get_clients_local(SilcClient client, SilcClientConnection conn, const char *nickname, - const char *format); - -/****f* silcclient/SilcClientAPI/silc_client_get_clients_by_channel - * - * SYNOPSIS - * - * void silc_client_get_clients_by_channel(SilcClient client, - * SilcClientConnection conn, - * SilcChannelEntry channel, - * SilcGetClientCallback completion, - * void *context); - * - * DESCRIPTION - * - * Gets client entries by the channel indicated by `channel'. Thus, - * it resovles the users currently on that channel. If all users are - * already resolved this returns the users from the channel. If the - * users are resolved only partially this resolves the complete user - * information. If no users are resolved on this channel at all, this - * calls USERS command to resolve all users on the channel. The `completion' - * will be called after the entries are available. When server returns - * the client information it will be cached and can be accessed locally - * at a later time. - * - * This function can be used for example in SILC_COMMAND_JOIN command - * reply handling in application to resolve users on that channel. It - * also can be used after calling silc_client_get_channel_resolve to - * resolve users on that channel. - * - * NOTES - * - * The resolving is done with WHOIS command. For this reason this - * command may take a long time because it resolves detailed user - * information. - * - ***/ -void silc_client_get_clients_by_channel(SilcClient client, - SilcClientConnection conn, - SilcChannelEntry channel, - SilcGetClientCallback completion, - void *context); - -/****f* silcclient/SilcClientAPI/silc_client_get_clients_by_list - * - * SYNOPSIS - * - * SilcUInt16 - * silc_client_get_clients_by_list(SilcClient client, - * SilcClientConnection conn, - * SilcUInt32 list_count, - * SilcBuffer client_id_list, - * SilcGetClientCallback completion, - * void *context); - * - * DESCRIPTION - * - * Gets client entries by the list of client ID's `client_id_list'. This - * always resolves those client ID's it doesn't know about from the server. - * The `client_id_list' is a list of ID Payloads added one after other. - * JOIN command reply and USERS command reply for example returns this sort - * of list. The `completion' will be called after the entries are available. - * When server returns the client information it will be cached and can be - * accessed locally at a later time. The resolving is done with WHOIS - * command. - * - * Returns command identifier for the resolving. It can be used to attach - * a pending command to it, if needed. Returns 0 when no resolving was - * done or wasn't needed (completion is called before this returns). - * - * NOTES - * - * If even after resolving some Client ID in the `client_id_list' is - * unknown it will be ignored and error is not returned. - * - ***/ -SilcUInt16 silc_client_get_clients_by_list(SilcClient client, - SilcClientConnection conn, - SilcUInt32 list_count, - SilcBuffer client_id_list, - SilcGetClientCallback completion, - void *context); + SilcBool return_all); /****f* silcclient/SilcClientAPI/silc_client_get_client_by_id * @@ -595,10 +555,17 @@ typedef void (*SilcGetChannelCallback)(SilcClient client, * before reading any data from the `channel_entry'. The lock must be * unlocked with silc_client_unlock_channel. * + * NOTES + * * The entry must be unlocked before calling any Client Library API - * functions where the entry is given as argument. + * functions where the entry is given as argument, unless otherwise stated. + * + * The entry should not be locked for long periods of time. For example, + * it is not appropriate to hold the lock while waiting user interface to + * be drawn. The appropriate way is to read the data and duplicate it if + * necessary, unlock the entry, then draw on the user interface. * - * This function is not needed if application is not multithreaded + * This function is not needed if application is not multithreaded. * ***/ void silc_client_lock_channel(SilcChannelEntry channel_entry); @@ -632,7 +599,7 @@ void silc_client_unlock_channel(SilcChannelEntry channel_entry); * after it is not needed anymore. Returns `channel_entry'. * ***/ -SilcChannelEntry silc_client_ref_channel(SilcClient client, +SilcChannelEntry silc_client_ref_channel(SilcClient client, SilcClientConnection conn, SilcChannelEntry channel_entry); @@ -712,7 +679,7 @@ SilcChannelEntry silc_client_get_channel(SilcClient client, * Resolves entry for channel by the channel name from the server. * The resolving is done with IDENTIFY command. Note that users on * the channel are not resolved at the same time. Use for example - * silc_client_get_clients_by_channel to resolve all users on a channel. + * USERS command to resolve all users on a channel. * ***/ void silc_client_get_channel_resolve(SilcClient client, @@ -768,8 +735,7 @@ SilcChannelEntry silc_client_get_channel_by_id(SilcClient client, * a pending command to it, if needed. Returns 0 on error. * * Note that users on the channel are not resolved at the same time. - * Use for example silc_client_get_clients_by_channel to resolve all - * users on a channel. + * Use for example USERS command to resolve all users on a channel. * ***/ SilcUInt16 @@ -826,10 +792,17 @@ typedef void (*SilcGetServerCallback)(SilcClient client, * before reading any data from the `server_entry'. The lock must be * unlocked with silc_client_unlock_server. * + * NOTES + * * The entry must be unlocked before calling any Client Library API - * functions where the entry is given as argument. + * functions where the entry is given as argument, unless otherwise stated. + * + * The entry should not be locked for long periods of time. For example, + * it is not appropriate to hold the lock while waiting user interface to + * be drawn. The appropriate way is to read the data and duplicate it if + * necessary, unlock the entry, then draw on the user interface. * - * This function is not needed if application is not multithreaded + * This function is not needed if application is not multithreaded. * ***/ void silc_client_lock_server(SilcServerEntry server_entry); @@ -863,7 +836,7 @@ void silc_client_unlock_server(SilcServerEntry server_entry); * after it is not needed anymore. Returns `server_entry'. * ***/ -SilcServerEntry silc_client_ref_server(SilcClient client, +SilcServerEntry silc_client_ref_server(SilcClient client, SilcClientConnection conn, SilcServerEntry server_entry);