If channel user list could not be resolved or was not even
[crypto.git] / lib / silcclient / silcclient.h
index fedeea7489abcf93b8001db5786a846fa489a5a1..1edc5e90a12c98db512d5caf4524bb0dac9857c5 100644 (file)
@@ -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,9 +686,24 @@ typedef struct {
      value. */
   SilcBool nickname_force_format;
 
-  /* 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. */
+  /* 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 initialize
+     or uninitialize the SILC Crypto Toolkit.  The application will have
+     to do that itself by calling silc_crypto_init and silc_crypto_uninit. */
   SilcBool dont_register_crypto_library;
 
 } SilcClientParams;
@@ -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
@@ -1371,7 +1391,7 @@ SilcUInt16 silc_client_command_call(SilcClient client,
  *
  *    If FALSE is returned in this function this callback will not be called
  *    again for `command' even if there are more comand replies.  By returning
- *    FALSE the caller my stop the command reply handling when needed.
+ *    FALSE the caller may stop the command reply handling when needed.
  *
  ***/
 typedef SilcBool (*SilcClientCommandReply)(SilcClient client,