Merged silc_1_0_branch to trunk.

[silc.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..fa9019b08ed3c8be09d54d3c956d99d70ef239cc 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>
 


@@ -28,18 +37,19 @@ SilcStatus status, ...);
 </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 +74,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">


@@ -126,9 +139,12 @@ 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 odl Client ID used by the client before the
+nickname was changed.

 </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>
 


@@ -171,9 +187,10 @@ parsed with silc_argument_payload_parse function.
 <tr>
 <td><small>SILC_COMMAND_KILL</td>
 <td><small>
 <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.

 </td>
 </td>

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

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


@@ -235,12 +252,16 @@ 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
 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.
+parsing the 'client_mode_list' is not necessary.  The 'founder_key' is the
+channel founder's key and may be NULL.  The 'channel_pubkeys' is Argument
+List Payload containing Public Key Payloads of all added channel public
+keys, it may be NULL.

 </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,
 </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
+SilcBuffer client_mode_list, SilcPublicKey founder_key,
+SilcBuffer channel_pubkeys

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


@@ -265,9 +286,15 @@ 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.
+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 an
+Argument List Payload where each argument includes one Public Key
+Payload.

 </td>
 </td>

-<td width="50%"><small>SilcChannelEntry channel, SilcUInt32 mode
+<td width="50%"><small>SilcChannelEntry channel, SilcUInt32 mode,
+SilcPublicKey founder_key, SilcBuffer channel_pubkeys

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


@@ -284,9 +311,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'.  The `client_entry' and 'channel' may be NULL.

 </td>
 </td>

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

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


@@ -334,7 +362,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>


@@ -357,7 +386,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,


@@ -368,6 +397,6 @@ SilcPublicKey public_key
 </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.