updates.

[crypto.git] / lib / doc / command_reply_args.html

diff --git a/lib/doc/command_reply_args.html b/lib/doc/command_reply_args.html
index 5a964271658f52abaac40a08af5e8579ef4e0b0a..49b79d6a1bacda08f744a19ef8b252d816aef559 100644 (file)
--- a/lib/doc/command_reply_args.html
+++ b/lib/doc/command_reply_args.html
@@ -11,6 +11,15 @@ specific arguments to the application.  This document describes these
 arguments for all command replies to help SILC client software developers
 to process them.
 
 arguments for all command replies to help SILC client software developers
 to process them.
 

+<br />&nbsp;<br />
+<b>NOTE: </b>The following list of command reply arguments are sent when
+the command was executed successfully.  If an error occurred, the
+`command_reply' client operation's 'success' argument is FALSE, and the
+'status' argument includes the error status.  In this case the arguments
+returned are dependent of the 'status' argument.  See all
+<a href="silcstatus_args.html">SilcStatus error arguments</a> for these
+arguments.
+

 <br />&nbsp;<br />&nbsp;<br />
 <b>command_reply Client Library operation</b>
 
 <br />&nbsp;<br />&nbsp;<br />
 <b>command_reply Client Library operation</b>
 


@@ -21,25 +30,24 @@ The 'command_reply' client operation callback function prototype is as follows:
 <tt>
 &nbsp;&nbsp;
 void (*command_reply)(SilcClient client, SilcClientConnection conn,<br />
 <tt>
 &nbsp;&nbsp;
 void (*command_reply)(SilcClient client, SilcClientConnection conn,<br />

-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-SilcCommandPayload cmd_payload, bool success, SilcCommand command,<br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-SilcStatus status, ...);
+                      SilcCommand command, SilcStatus status,<br />
+                      SilcStatus error, va_list ap);

 </tt>
 
 <br />&nbsp;<br />
 </tt>
 
 <br />&nbsp;<br />

-The first argument 'client' is the SILC Client Library context, the 'conn' 
+The first argument 'client' is the SILC Client Library context, the 'conn'

 is the context for the connection to the remote server, the 'cmd_payload'
 is the raw SilcCommandPayload and application usually ignores it, the
 'success' boolean value indicates whether the earlier command was a success
 or not, the 'command' is the command reply enumeration, and the 'status'
 indicates the status of the command reply.  If 'success' is FALSE then
 is the context for the connection to the remote server, the 'cmd_payload'
 is the raw SilcCommandPayload and application usually ignores it, the
 'success' boolean value indicates whether the earlier command was a success
 or not, the 'command' is the command reply enumeration, and the 'status'
 indicates the status of the command reply.  If 'success' is FALSE then

-'status' includes error status.
+'status' includes error status (see <a href="silcstatus_args.html">SilcStatus
+error arguments</a>).

 
 <br />&nbsp;<br />
 Rest of the arguments are 'command' specific and implementation should
 handle them by the SilcCommand for example in a <tt>switch</tt> statement.
 
 <br />&nbsp;<br />
 Rest of the arguments are 'command' specific and implementation should
 handle them by the SilcCommand for example in a <tt>switch</tt> statement.

-The commands are defined in lib/silccore/silccomand.h header file.  A short 
+The commands are defined in lib/silccore/silccomand.h header file.  A short

 example:
 
 <br />&nbsp;<br />
 example:
 
 <br />&nbsp;<br />


@@ -64,12 +72,15 @@ example:
 
 <br />&nbsp;<br />
 The following table describes all commands and arguments that the client
 
 <br />&nbsp;<br />
 The following table describes all commands and arguments that the client

-library sends in the 'command_reply' client operation to the application.  
-By default all arguments that the library sends to application are valid 
-pointers.  However, it is possible that some pointers may be NULL.  If 
-this is the case it is separately mentioned that the argument may be NULL.  
-In this case application must ignore that argument.  The 'command_reply'
-arguments per SilcCommand is as follows:
+library sends in the 'command_reply' client operation to the application.
+By default all arguments that the library sends to application are valid
+pointers.  However, it is possible that some pointers may be NULL.  If
+this is the case it is separately mentioned that the argument may be NULL.
+In this case application must ignore that argument.
+
+<br />&nbsp;<br />
+The 'command_reply' arguments for successful SilcCommand replies are as
+follows:

 
 <br />&nbsp;<br />
 <table border="1" width="100%" cellpadding="3" cellspacing="0">
 
 <br />&nbsp;<br />
 <table border="1" width="100%" cellpadding="3" cellspacing="0">


@@ -85,17 +96,19 @@ arguments per SilcCommand is as follows:
 <td><small>
 Returns information about user. The following pointers may be NULL: 'channels',
 'fingerprint', 'channel_usermodes' and 'attrs'.  If 'fingerprint' is valid its
 <td><small>
 Returns information about user. The following pointers may be NULL: 'channels',
 'fingerprint', 'channel_usermodes' and 'attrs'.  If 'fingerprint' is valid its

-length is 20 bytes. If 'channels' is valid it can be parsed with
-silc_channel_payload_parse_list function. It is the list of channels user
-has joined. If the 'channel_usermodes' is valid it can be parsed with
-silc_get_mode_list function. It is the list of the user's modes on the
-joined channels. The 'attr' is the Requested Attributes that may have been
-returned by the client and it can be parsed by traversing the SilcDList
-and using silc_attribute_get_attribute function.
+length is 20 bytes. If 'channels' is valid each entry in the list is
+SilcChannelPayload.  If the `channel_usermodes' is valid then the table
+has as many entries as there are entries in the `channels' list, and the
+first entry in the table is the user mode on the first channel in the
+`channels' list.  The `channel_usermodes' is the table of the user's modes
+on the joined channels.  The 'attr' is the Requested Attributes that may
+have been returned by the client and it can be parsed by traversing the
+SilcDList and using silc_attribute_get_attribute function.  Each entry in
+the list is SilcAttribute.

 </td>
 <td width="50%"><small>SilcClientEntry client_entry, char *nickname,
 </td>
 <td width="50%"><small>SilcClientEntry client_entry, char *nickname,

-char *username, char *realname, SilcBuffer channels, SilcUInt32 usermode,
-SilcUInt32 idletime, unsigned char *fingerprint, SilcBuffer channel_usermodes,
+char *username, char *realname, SilcDList channels, SilcUInt32 usermode,
+SilcUInt32 idletime, unsigned char *fingerprint, SilcUInt32 *channel_usermodes,

 SilcDList attrs
 </td>
 </tr>
 SilcDList attrs
 </td>
 </tr>


@@ -126,9 +139,14 @@ this command reply.  The 'name' and 'info' may be NULL.
 <tr>
 <td><small>SILC_COMMAND_NICK</td>
 <td><small>
 <tr>
 <td><small>SILC_COMMAND_NICK</td>
 <td><small>

-Returns the new Client ID after user has changed nickname.
+Returns the new Client ID and new nickname inside the SilcClientEntry.
+The `old_client_id' is the old Client ID used by the client before the
+nickname was changed.  The `nickname' is the new nickname.  Note that,
+when user changes nickname SILC_NOTIFY_TYPE_NICK_CHANGE is not delivered
+to application.  Instead this SILC_COMMAND_NICK command reply is delivered.

 </td>
 </td>

-<td width="50%"><small>SilcClientEntry local_entry, char *nickname
+<td width="50%"><small>SilcClientEntry local_entry, char *nickname,
+const SilcClientID *old_client_id

 </td>
 </tr>
 
 </td>
 </tr>
 


@@ -137,7 +155,11 @@ Returns the new Client ID after user has changed nickname.
 <td><small>
 Returns the list of channel in the SILC network. Each call of command reply
 returns one channel. This means that the command reply is called multiple
 <td><small>
 Returns the list of channel in the SILC network. Each call of command reply
 returns one channel. This means that the command reply is called multiple

-times to return list of channels.  The 'channel_topic' may be NULL.
+times to return list of channels.  The 'channel', 'channel_name' and
+'channel_topic' may be NULL.  However, the 'channel' and 'channel_name'
+are NULL only if there are no channels in the network.  In this case
+this reply is called once with all arguments set to NULL.  Application
+must be able to handle this situation correctly.

 </td>
 <td width="50%"><small>SilcChannelEntry channel, char *channel_name,
 char *channel_topic, SilcUInt32 user_count
 </td>
 <td width="50%"><small>SilcChannelEntry channel, char *channel_name,
 char *channel_topic, SilcUInt32 user_count


@@ -159,21 +181,26 @@ Returns the topic of the channel.
 Returns the invite list of the channel.  Called also even if invite list
 was not modified but SILC_COMMAND_INVITE command was used to invite a user
 into a channel.  In this case the invite list is not returned by the
 Returns the invite list of the channel.  Called also even if invite list
 was not modified but SILC_COMMAND_INVITE command was used to invite a user
 into a channel.  In this case the invite list is not returned by the

-server and 'invite_list' is NULL.  The 'invite_list' is list of
-SilcArgumentPayloads.  The first 2 bytes are the number of arguments in
-the list and can be parsed with SILC_GET16_MSB macro.  The list can be
-parsed with silc_argument_payload_parse function.
+server and 'invite_list' is NULL.  The 'invite_list' is SilcArgumenPayload
+which contains one or more arguments, each is one invite list entry.  The
+entries can be retrieved with silc_argument_get_first_arg,
+silc_argument_get_next_arg, silc_argument_get_arg_type and
+silc_argument_get_decoded functions.

 </td>
 </td>

-<td width="50%"><small>SilcChannelEntry channel, SilcBuffer invite_list
+<td width="50%"><small>SilcChannelEntry channel,
+SilcArgumentPayload invite_list

 </td>
 </tr>
 
 <tr>
 <td><small>SILC_COMMAND_KILL</td>
 <td><small>
 </td>
 </tr>
 
 <tr>
 <td><small>SILC_COMMAND_KILL</td>
 <td><small>

-Called after killing a client.  There is no arguments to this reply.
+Called after killing a client.  Returns the client that was killed.
+The `client_entry' may be NULL.  The `client_entry' will become invalid
+after the command reply has returned from application.  The
+SILC_NOTIFY_TYPE_KILLED will not be delivered for clients that you killed.

 </td>
 </td>

-<td width="50%"><small>none
+<td width="50%"><small>SilcClientEntry client_entry

 </td>
 </tr>
 
 </td>
 </tr>
 


@@ -190,15 +217,10 @@ char *server_info
 <tr>
 <td><small>SILC_COMMAND_STATS</td>
 <td><small>
 <tr>
 <td><small>SILC_COMMAND_STATS</td>
 <td><small>

-Returns network statistics from the server.  The 'stats_buffer' of length of
-'buffer_length' bytes includes 32-bit integers one after the other each
-representing some statistics.  The integers can be parsed for example with
-SILC_GET32_MSB macro.  The integers in the buffer are: starttime, uptime,
-local_clients, local_channels, local_serverops, local_routerops, cell_clients,
-cell_channels, cell_servers, all_clients, all_channel, all_servers,
-all_routers, all_serverops, all_routerops.  All integers are always present.
+Returns network statistics from the server.  The `stats' structure contains
+the statistics returned by the server.

 </td>
 </td>

-<td width="50%"><small>unsigned char *stats_buffer, SilcUInt32 buffer_length
+<td width="50%"><small>SilcClientStats *stats

 </td>
 </tr>
 
 </td>
 </tr>
 


@@ -224,23 +246,24 @@ to this reply.
 <tr>
 <td><small>SILC_COMMAND_JOIN</td>
 <td><small>
 <tr>
 <td><small>SILC_COMMAND_JOIN</td>
 <td><small>

-Reply received when user joined a channel.  The 'ignored' argument can
-be ignored by the application.  The 'topic' and 'hmac_name' may be NULL.
-The 'key_payload' is usually ignored by the application.  The 'list_count'
-is the number of entries in both 'client_id_list' and 'client_mode_list'.
-The 'client_id_list' is a list of clients on the channel and 'client_mode_list'
-includes those clients' modes on the channel.  If application likes to
-resolve information about the clients on the channel it may call
-silc_client_get_clients_by_list function and pass the 'client_id_list' as
-argument to it.  The 'client_mode_list' includes 32-bit integers one after
-the other and they are in same order as clients in 'client_mode_list'.
-If application resolves the information with silc_client_get_clients_by_list
-parsing the 'client_mode_list' is not necessary.
+Reply received when user joined a channel.  The `channel_mode' contains
+the current channel mode.  The `user_list' is the user list on the channel
+and may be traversed with silc_hash_table_get function.  Each entry in the
+`user_list' is SilcChannelUser structure, which contains the SilcClientEntry
+and the client's mode on the channel.  The library will free the list.
+The `topic' is the current topic on channel or NULL if no topic is set.
+The `cipher' is the encryption algorithm used on channel or NULL if it is
+not available.  The `hmac' is the HMAC algorithm used on channel or NULL if
+it is not available.  The `founder_key' is the channel founder's public key
+or NULL if founder public key has not been set.  The `channel_pubkeys' is
+a list of channel public keys (for authentication on joining) or NULL if
+they have not been set.  Each entry in the list is SilcArgumentDecodedList
+each containing one channel SilcPublicKey.  The library will free the list.

 </td>
 <td width="50%"><small>char *channel_name, SilcChannelEntry channel,
 </td>
 <td width="50%"><small>char *channel_name, SilcChannelEntry channel,

-SilcUInt32 channel_mode, int ignored, SilcBuffer key_payload, NULL, NULL,
-char *topic, char *hmac_name, SilcUInt32 list_count, SilcBuffer client_id_list,
-SilcBuffer client_mode_list
+SilcUInt32 channel_mode, SilcHashTableList *user_list, char *topic,
+char *cipher, char *hmac, SilcPublicKey founder_key,
+SilcDList channel_pubkeys, SilcUint32 user_limit

 </td>
 </tr>
 
 </td>
 </tr>
 


@@ -265,9 +288,18 @@ Returns the user mode after changing it.
 <tr>
 <td><small>SILC_COMMAND_CMODE</td>
 <td><small>
 <tr>
 <td><small>SILC_COMMAND_CMODE</td>
 <td><small>

-Returns channel's mode after changing it.
-</td>
-<td width="50%"><small>SilcChannelEntry channel, SilcUInt32 mode
+Returns channel's mode after changing it.  Optionally may also return
+founder's public key when it was set.  It may also return the channel
+public key list when the list was altered.  The 'founder_key' and
+'channel_pubkeys' arguments may be NULL.  The 'channel_pubkeys' is a list
+of SilcArgumentDecodedList contexts which each contain one channel public
+key.  The library will automatically free the list.  If the `founder_key'
+was present it will be updated to `channel' entry by the library after
+calling the command_reply callback.  Application may check if the `founder_key'
+is different from the key in `channel' entry to detect if it was changed.
+</td>
+<td width="50%"><small>SilcChannelEntry channel, SilcUInt32 mode,
+SilcPublicKey founder_key, SilcDList channel_pubkeys, SilcUint32 user_limit

 </td>
 </tr>
 
 </td>
 </tr>
 


@@ -284,9 +316,10 @@ SilcClientEntry target_client
 <tr>
 <td><small>SILC_COMMAND_KICK</td>
 <td><small>
 <tr>
 <td><small>SILC_COMMAND_KICK</td>
 <td><small>

-Called after kicking a client.  There is no arguments to this reply.
+Called after kicking a client.  Returns the client that was kicked from
+the 'channel'.

 </td>
 </td>

-<td width="50%"><small>none
+<td width="50%"><small>SilcChannelEntry channel, SilcClientEntry client_entry

 </td>
 </tr>
 
 </td>
 </tr>
 


@@ -297,17 +330,21 @@ Returns channel's ban list.  The 'ban_list' may be NULL.  The construction
 of that list is equivalent to invite list.  See description of
 SILC_COMMAND_INVITE command reply.
 </td>
 of that list is equivalent to invite list.  See description of
 SILC_COMMAND_INVITE command reply.
 </td>

-<td width="50%"><small>SilcChannelEntry channel, SilcBuffer ban_list
+<td width="50%"><small>SilcChannelEntry channel, SilcArgumentPayload ban_list

 </td>
 </tr>
 
 <tr>
 <td><small>SILC_COMMAND_DETACH</td>
 <td><small>
 </td>
 </tr>
 
 <tr>
 <td><small>SILC_COMMAND_DETACH</td>
 <td><small>

-Called after being detached from the SILC network. There is no arguments
-to this reply.
+Called after being detached from the SILC network.  The command reply delivers
+the detachment data buffer `detach_data' that the application should save
+for example into a file.  The data will be needed when resuming back to
+the network.  When resuming the data is saved into SilcClientConnectionParams
+structure and given as argument to silc_client_connect_to_server or
+silc_client_key_exchange functions.

 </td>
 </td>

-<td width="50%"><small>none
+<td width="50%"><small>SilcBuffer detach_data

 </td>
 </tr>
 
 </td>
 </tr>
 


@@ -334,7 +371,8 @@ arguments to this reply.
 <tr>
 <td><small>SILC_COMMAND_LEAVE</td>
 <td><small>
 <tr>
 <td><small>SILC_COMMAND_LEAVE</td>
 <td><small>

-Called after leaving the channel.
+Called after leaving the channel.  Note that the `channel' will become
+invalid after command_reply client operation returns.

 </td>
 <td width="50%"><small>SilcChannelEntry channel
 </td>
 </td>
 <td width="50%"><small>SilcChannelEntry channel
 </td>


@@ -343,13 +381,12 @@ Called after leaving the channel.
 <tr>
 <td><small>SILC_COMMAND_USERS</td>
 <td><small>
 <tr>
 <td><small>SILC_COMMAND_USERS</td>
 <td><small>

-Returns list of users in channel.  If application wishes not to parse
-the raw lists the channel->user_list hash table is updated before calling
-this command reply and application may traverse that table instead of
-parssing the raw lists.
+Returns list of users in channel.  The `user_list' may be traversed with
+silc_hash_table_get function.  Each entry in the `user_list' is
+SilcChannelUser structure, which contains the SilcClientEntry and the
+client's mode on the channel.

 </td>
 </td>

-<td width="50%"><small>SilcChannelEntry channel, SilcUInt32 list_count,
-SilcBuffer client_id_list, SilcBuffer client_mode_list
+<td width="50%"><small>SilcChannelEntry channel, SilcHashTableList *user_list

 </td>
 </tr>
 
 </td>
 </tr>
 


@@ -357,7 +394,7 @@ SilcBuffer client_id_list, SilcBuffer client_mode_list
 <td><small>SILC_COMMAND_GETKEY</td>
 <td><small>
 Returns public key of client or server.  The 'public_key' may be NULL.
 <td><small>SILC_COMMAND_GETKEY</td>
 <td><small>
 Returns public key of client or server.  The 'public_key' may be NULL.

-The 'entry_type' is used to check what type of pointer the entry' is.  For 
+The 'entry_type' is used to check what type of pointer the entry' is.  For

 SILC_ID_CLIENT SilcClientEntry and for SILC_ID_SERVER SilcServerEntry.
 </td>
 <td width="50%"><small>SilcIdType entry_type, void *entry,
 SILC_ID_CLIENT SilcClientEntry and for SILC_ID_SERVER SilcServerEntry.
 </td>
 <td width="50%"><small>SilcIdType entry_type, void *entry,


@@ -365,9 +402,23 @@ SilcPublicKey public_key
 </td>
 </tr>
 
 </td>
 </tr>
 

+<tr>
+<td><small>SILC_COMMAND_SERVICE</td>
+<td><small>
+Returns the service list in the server, or information on the accepted
+and authenticated service.  The 'service_list' maybe NULL if server does
+not support any services.  It is NULL also when 'name' is not NULL.  The
+'service_list' is a comma separated list of services the server supports.
+The 'name' MAY be NULL also.  The 'name' is the requested service, and it is
+non-NULL only if server accepted and authenticated client's request.
+</td>
+<td width="50%"><small>const char *server_list, const char *service_name
+</td>
+</tr>
+

 </table>
 
 <br />&nbsp;<br />
 </table>
 
 <br />&nbsp;<br />

-SILC protocol defines some additional commands but command replies to 
+SILC protocol defines some additional commands but command replies to

 those commands are not delivered to the application.  Only the command
 replies listed above are delivered to application.
 those commands are not delivered to the application.  Only the command
 replies listed above are delivered to application.