Fixed nickname parsing with WHOIS command to accept formatted

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

diff --git a/lib/silcclient/silcclient_entry.h b/lib/silcclient/silcclient_entry.h
index aae2c0442fb05563439f298401a49f69a17aacae..20f6e9e3d189854d393e9325ec88985161308f93 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
 
@@ -306,8 +325,10 @@ 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).
+ *    Returns 0 on error and the command identifier used with the command
+ *    otherwise.
  *
  * NOTES
  *
@@ -349,8 +370,10 @@ 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).
+ *    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
@@ -381,19 +404,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
  *
@@ -408,7 +432,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);
+                                       SilcBool return_all);
 
 /****f* silcclient/SilcClientAPI/silc_client_get_clients_by_channel
  *