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
*/
+/****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
* 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
* 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);
* 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);
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);
-
/****f* silcclient/SilcClientAPI/silc_client_get_client_by_id
*
* SYNOPSIS
* 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);
* 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);
* 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);
* 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);
projects / silc.git / blobdiff