Author: Pekka Riikonen <priikone@silcnet.org>
- 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
* 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
char *channel_name; /* Channel 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 */
SilcChannelID id; /* Channel ID */
SilcUInt32 mode; /* Channel mode, ChannelModes. */
SilcUInt32 user_limit; /* User limit on channel */
SilcDList clients,
void *context);
+/****f* silcclient/SilcClientAPI/silc_client_lock_client
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_lock_client(SilcClientEntry client_entry);
+ *
+ * DESCRIPTION
+ *
+ * Acquires lock for the client entry indicate by `client_entry'. When
+ * application wants to access `client_entry' it must lock the entry
+ * 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, 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.
+ *
+ ***/
+void silc_client_lock_client(SilcClientEntry client_entry);
+
+/****f* silcclient/SilcClientAPI/silc_client_unlock_client
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_unlock_client(SilcClientEntry client_entry);
+ *
+ * DESCRIPTION
+ *
+ * Releases the lock acquired with silc_client_lock_client.
+ *
+ ***/
+void silc_client_unlock_client(SilcClientEntry client_entry);
+
/****f* silcclient/SilcClientAPI/silc_client_ref_client
*
* SYNOPSIS
*
- * void silc_client_ref_client(SilcClient client,
- * SilcClientConnection conn,
- * SilcClientEntry client_entry);
+ * SilcClientEntry
+ * silc_client_ref_client(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientEntry client_entry);
*
* DESCRIPTION
*
* Takes a reference of the client entry indicated by `client_entry'
* The reference must be released by calling silc_client_unref_client
- * after it is not needed anymore.
+ * after it is not needed anymore. Returns `client_entry'.
*
***/
-void silc_client_ref_client(SilcClient client, SilcClientConnection conn,
- SilcClientEntry client_entry);
+SilcClientEntry silc_client_ref_client(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientEntry client_entry);
/****f* silcclient/SilcClientAPI/silc_client_unref_client
*
SilcGetClientCallback completion,
void *context);
-/****f* silcclient/SilcClientAPI/silc_client_get_clients_by_list
- *
- * SYNOPSIS
- *
- * void 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.
- *
- * NOTES
- *
- * If even after resolving some Client ID in the `client_id_list' is
- * unknown it will be ignored and error is not returned.
- *
- ***/
-void silc_client_get_clients_by_list(SilcClient client,
- SilcClientConnection conn,
- SilcUInt32 list_count,
- SilcBuffer client_id_list,
- SilcGetClientCallback completion,
- void *context);
-
/****f* silcclient/SilcClientAPI/silc_client_get_client_by_id
*
* SYNOPSIS
*
* SYNOPSIS
*
- * void
+ * SilcUInt16
* silc_client_get_client_by_id_resolve(SilcClient client,
* SilcClientConnection conn,
* SilcClientID *client_id,
* cache and can be accessed locally at a later time. The resolving
* is done by sending WHOIS command.
*
+ * Returns command identifier for the resolving. It can be used to attach
+ * a pending command to it, if needed. Returns 0 on error.
+ *
* If the `attributes' is non-NULL then the buffer includes Requested
* Attributes which can be used to fetch very detailed information
* about the user. If it is NULL then only normal WHOIS query is
* function.
*
***/
-void silc_client_get_client_by_id_resolve(SilcClient client,
- SilcClientConnection conn,
- SilcClientID *client_id,
- SilcBuffer attributes,
- SilcGetClientCallback completion,
- void *context);
+SilcUInt16
+silc_client_get_client_by_id_resolve(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientID *client_id,
+ SilcBuffer attributes,
+ SilcGetClientCallback completion,
+ void *context);
/* SilcChannelEntry routines */
SilcDList channels,
void *context);
+/****f* silcclient/SilcClientAPI/silc_client_lock_channel
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_lock_channel(SilcChannelEntry channel_entry);
+ *
+ * DESCRIPTION
+ *
+ * Acquires lock for the channel entry indicate by `channel_entry'. When
+ * application wants to access `channel_entry' it must lock the entry
+ * 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, 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.
+ *
+ ***/
+void silc_client_lock_channel(SilcChannelEntry channel_entry);
+
+/****f* silcclient/SilcClientAPI/silc_client_unlock_channel
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_unlock_channel(SilcChannelEntry channel_entry);
+ *
+ * DESCRIPTION
+ *
+ * Releases the lock acquired with silc_client_lock_channel.
+ *
+ ***/
+void silc_client_unlock_channel(SilcChannelEntry channel_entry);
+
/****f* silcclient/SilcClientAPI/silc_client_ref_channel
*
* SYNOPSIS
*
- * void silc_client_ref_channel(SilcClient client,
- * SilcClientConnection conn,
- * SilcChannelEntry channel_entry);
+ * SilcChannelEntry
+ * silc_client_ref_channel(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcChannelEntry channel_entry);
*
* DESCRIPTION
*
* Takes a reference of the channel entry indicated by `channel_entry'
* The reference must be released by calling silc_client_unref_channel
- * after it is not needed anymore.
+ * after it is not needed anymore. Returns `channel_entry'.
*
***/
-void silc_client_ref_channel(SilcClient client, SilcClientConnection conn,
- SilcChannelEntry channel_entry);
+SilcChannelEntry silc_client_ref_channel(SilcClient client,
+ SilcClientConnection conn,
+ SilcChannelEntry channel_entry);
/****f* silcclient/SilcClientAPI/silc_client_unref_channel
*
*
* SYNOPSIS
*
- * void
+ * SilcUInt16
* silc_client_get_channel_by_id_resolve(SilcClient client,
* SilcClientConnection conn,
* SilcChannelID *channel_id,
* by the `channel_id'. Use this only if you know that you do not have
* the entry cached locally. The resolving is done with IDENTIFY command.
*
+ * Returns command identifier for the resolving. It can be used to attach
+ * 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.
*
***/
-void silc_client_get_channel_by_id_resolve(SilcClient client,
- SilcClientConnection conn,
- SilcChannelID *channel_id,
- SilcGetChannelCallback completion,
- void *context);
+SilcUInt16
+silc_client_get_channel_by_id_resolve(SilcClient client,
+ SilcClientConnection conn,
+ SilcChannelID *channel_id,
+ SilcGetChannelCallback completion,
+ void *context);
/* SilcServerEntry routines */
SilcDList servers,
void *context);
+/****f* silcclient/SilcClientAPI/silc_client_lock_server
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_lock_server(SilcServerEntry server_entry);
+ *
+ * DESCRIPTION
+ *
+ * Acquires lock for the server entry indicate by `server_entry'. When
+ * application wants to access `server_entry' it must lock the entry
+ * 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, 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.
+ *
+ ***/
+void silc_client_lock_server(SilcServerEntry server_entry);
+
+/****f* silcclient/SilcClientAPI/silc_client_unlock_server
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_unlock_server(SilcServerEntry server_entry);
+ *
+ * DESCRIPTION
+ *
+ * Releases the lock acquired with silc_client_lock_server.
+ *
+ ***/
+void silc_client_unlock_server(SilcServerEntry server_entry);
+
/****f* silcclient/SilcClientAPI/silc_client_ref_server
*
* SYNOPSIS
*
- * void silc_client_ref_server(SilcClient client,
- * SilcClientConnection conn,
- * SilcServerEntry server_entry);
+ * SilcServerEntry
+ * silc_client_ref_server(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcServerEntry server_entry);
*
* DESCRIPTION
*
* Takes a reference of the server entry indicated by `server_entry'
* The reference must be released by calling silc_client_unref_server
- * after it is not needed anymore.
+ * after it is not needed anymore. Returns `server_entry'.
*
***/
-void silc_client_ref_server(SilcClient client, SilcClientConnection conn,
- SilcServerEntry server_entry);
+SilcServerEntry silc_client_ref_server(SilcClient client,
+ SilcClientConnection conn,
+ SilcServerEntry server_entry);
/****f* silcclient/SilcClientAPI/silc_client_unref_server
*
*
* SYNOPSIS
*
- * void
+ * SilcUInt16
* silc_client_get_server_by_id_resolve(SilcClient client,
* SilcClientConnection conn,
* SilcServerID *server_id,
* Resolves the server information by the `server_id'. The resolved
* server is returned into the `completion' callback.
*
+ * Returns command identifier for the resolving. It can be used to attach
+ * a pending command to it, if needed. Returns 0 on error.
+ *
***/
-void silc_client_get_server_by_id_resolve(SilcClient client,
- SilcClientConnection conn,
- SilcServerID *server_id,
- SilcGetServerCallback completion,
- void *context);
+SilcUInt16
+silc_client_get_server_by_id_resolve(SilcClient client,
+ SilcClientConnection conn,
+ SilcServerID *server_id,
+ SilcGetServerCallback completion,
+ void *context);
#endif /* SILCCLIENT_ENTRY_H */