Header documentation changes.

[silc.git] / lib / silcclient / silcclient_entry.h

diff --git a/lib/silcclient/silcclient_entry.h b/lib/silcclient/silcclient_entry.h
index 0f4e996a8572955a0576ef8bd308862a782459da..6ebe4129e35c93bf209560833da26c7597eacec8 100644 (file)
--- a/lib/silcclient/silcclient_entry.h
+++ b/lib/silcclient/silcclient_entry.h
@@ -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
@@ -450,46 +469,6 @@ void silc_client_get_clients_by_channel(SilcClient client,
                                        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