Merged silc_1_1_branch to trunk.

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

diff --git a/lib/silcclient/silcclient.h b/lib/silcclient/silcclient.h
index 94f78481b27f0621b021ed035f66cb8bd611a880..898204a18f46663a571c0c38202d924fb9d3f089 100644 (file)
--- a/lib/silcclient/silcclient.h
+++ b/lib/silcclient/silcclient.h
@@ -277,7 +277,7 @@ struct SilcChannelUserStruct {
  *
  * SOURCE
  */
-typedef struct {
+typedef struct SilcClientStatsStruct {
   SilcUInt32 starttime;                /* SILC server start time */
   SilcUInt32 uptime;           /* SILC server uptime*/
   SilcUInt32 my_clients;       /* Number of clients in the server */
@@ -365,7 +365,7 @@ typedef void (*SilcKeyAgreementCallback)(SilcClient client,
  *
  * SOURCE
  */
-typedef struct {
+typedef struct SilcPrivateMessageKeysStruct {
   SilcClientEntry client_entry;       /* The remote client entry */
   char *cipher;                              /* The cipher name */
   unsigned char *key;                /* The original key, If the appliation
@@ -401,7 +401,7 @@ struct SilcChannelPrivateKeyStruct {
  *
  * SYNOPSIS
  *
- *    typedef void (*SilcAskPassphrase)(unsigned char *passphrase,
+ *    typedef void (*SilcAskPassphrase)(const unsigned char *passphrase,
  *                                     SilcUInt32 passphrase_len,
  *                                     void *context);
  *
@@ -414,7 +414,7 @@ struct SilcChannelPrivateKeyStruct {
  *    encoded, and if it is not then library will attempt to encode it.
  *
  ***/
-typedef void (*SilcAskPassphrase)(unsigned char *passphrase,
+typedef void (*SilcAskPassphrase)(const unsigned char *passphrase,
                                  SilcUInt32 passphrase_len,
                                  void *context);
 
@@ -437,9 +437,8 @@ typedef void (*SilcVerifyPublicKey)(SilcBool success, void *context);
  *
  * SYNOPSIS
  *
- *    typedef void (*SilcGetAuthMeth)(SilcBool success,
- *                                    SilcAuthMethod auth_meth,
- *                                    void *auth, SilcUInt32 auth_len,
+ *    typedef void (*SilcGetAuthMeth)(SilcAuthMethod auth_meth,
+ *                                    const void *auth, SilcUInt32 auth_len,
  *                                    void *context);
  *
  * DESCRIPTION
@@ -461,7 +460,7 @@ typedef void (*SilcVerifyPublicKey)(SilcBool success, void *context);
  *
  ***/
 typedef void (*SilcGetAuthMeth)(SilcAuthMethod auth_meth,
-                               void *auth, SilcUInt32 auth_len,
+                               const void *auth, SilcUInt32 auth_len,
                                void *context);
 
 /****d* silcclient/SilcClientAPI/SilcClientMessageType
@@ -501,7 +500,7 @@ typedef enum {
  *
  * SOURCE
  */
-typedef struct {
+typedef struct SilcClientOperationsStruct {
   /* Message sent to the application by library. `conn' associates the
      message to a specific connection.  `conn', however, may be NULL.
      The `type' indicates the type of the message sent by the library.
@@ -641,7 +640,7 @@ typedef struct {
  *
  * SOURCE
  */
-typedef struct {
+typedef struct SilcClientParamsStruct {
   /* If this boolean is set to TRUE then the client library will use
      threads.  Any of the callback functions in the SilcClientOperations
      and other callbacks may be called at any time in a thread.  The
@@ -666,13 +665,16 @@ typedef struct {
      %H  full hostname - the full hostname of the client
 
      Example format strings: "%n#%a"     (fe. nick#2, nick#3)
-                             "%n@%h%a"   (fe. nick@host, nick@host2)
-                             "%a!%n@%h"  (fe. nick@host, 2!nick@host)
+                             "%n#%h%a"   (fe. nick#host, nick#host2)
+                             "%a!%n#%h"  (fe. nick#host, 2!nick#host)
 
      Note that there must always be some separator characters around '%n'
      format.  It is not possible to put format characters before or after
      '%n' without separators (such ash '#').  Also note that the separator
      character should be a character that cannot be part of normal nickname.
+     Note that, using '@' as a separator is not recommended as the nickname
+     string may contain it to separate a server name from the nickname (eg.
+     nickname@silcnet.org).
   */
   char nickname_format[32];
 
@@ -684,6 +686,21 @@ typedef struct {
      value. */
   SilcBool nickname_force_format;
 
+  /* If this is set to TRUE then all nickname strings returned by the library
+     and stored by the library are in the format of 'nickname@server', eg.
+     nickname@silcnet.org.  If this is FALSE then the server name of the
+     nickname is available only from the SilcClientEntry structure.  When this
+     is TRUE the server name is still parsed to SilcClientEntry. */
+  SilcBool full_nicknames;
+
+  /* If this is set to TRUE then all channel name strings returned by the
+     library and stored by the library are in the format of 'channel@server',
+     eg. silc@silcnet.org.  If this is FALSE then the server name of the
+     channel is available only from the SilcChannelEntry structure.  When this
+     is TRUE the server name is still parsed to SilcChannelEntry.  Note that,
+     not all SILC server versions return such channel name strings. */
+  SilcBool full_channel_names;
+
   /* If this is set to TRUE, the silcclient library will not register and
      deregister the cipher, pkcs, hash and hmac algorithms. The application
      itself will need to handle that. */
@@ -757,7 +774,7 @@ void silc_client_free(SilcClient client);
  *    The `running' callback with `context' is called after the client is
  *    running after silc_client_run or silc_client_run_one has been called.
  *    Application may start using the Client library API after that.  Setting
- *    the callback is optional, but recommended.
+ *    the callback is optional, but highly recommended.
  *
  ***/
 SilcBool silc_client_init(SilcClient client, const char *username,
@@ -839,7 +856,7 @@ void silc_client_stop(SilcClient client, SilcClientStopped stopped,
  *
  * SOURCE
  */
-typedef struct {
+typedef struct SilcClientConnectionParamsStruct {
   /* If this is provided the user's nickname in the network will be the
      string given here.  If it is given, it must be UTF-8 encoded.  If this
      string is not given, the user's username by default is used as nickname.
@@ -1310,9 +1327,12 @@ SilcChannelUser silc_client_on_channel(SilcChannelEntry channel,
  *    be the command name.  The variable argument list must be terminated
  *    with NULL.
  *
- *    Returns FALSE if the command is not known and TRUE after command.
- *    execution.  The `command' client operation callback will be called when
- *    the command is executed to indicate whether or not the command executed
+ *    Returns command identifier for this sent command.  It can be used
+ *    to additionally attach to the command reply using the function
+ *    silc_client_command_pending, if needed.  Returns 0 on error.
+ *
+ *    The `command' client operation callback will be called when the
+ *    command is executed to indicate whether or not the command executed
  *    successfully.
  *
  *    The `command_reply' client operation callbak will be called when reply