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

<big><b>Command Reply Arguments</b></big>

<br />&nbsp;<br />
The SILC Client Library 'command_reply client operation (which is part of the
<a href="silcclient-SilcClientOperations.html">
SilcClientOperation</a> callback functions) returns command replies
from the SILC Server for commands that the client has earlier sent to the
server.  The 'command_reply' client operation implementation has a variable
argument list to deliver <a href="silccommand-SilcCommand.html">SilcCommand</a>
specific arguments to the application.  This document describes these
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 />
The 'command_reply' client operation callback function prototype is as follows:

<br />&nbsp;<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, ...);
</tt>

<br />&nbsp;<br />
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
'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.
The commands are defined in lib/silccore/silccomand.h header file.  A short
example:

<br />&nbsp;<br />
<tt>
&nbsp;&nbsp;switch(type)<br />
&nbsp;&nbsp;&nbsp;&nbsp;{<br />
&nbsp;&nbsp;&nbsp;&nbsp;case SILC_COMMAND_WHOIS:<br />
&nbsp;&nbsp;&nbsp;&nbsp;...<br />
&nbsp;&nbsp;&nbsp;&nbsp;break;<br />
&nbsp;&nbsp;&nbsp;&nbsp;case SILC_COMMAND_WHOWAS:<br />
&nbsp;&nbsp;&nbsp;&nbsp;...<br />
&nbsp;&nbsp;&nbsp;&nbsp;break;<br />
&nbsp;&nbsp;&nbsp;&nbsp;case SILC_COMMAND_NICK:<br />
&nbsp;&nbsp;&nbsp;&nbsp;...<br />
&nbsp;&nbsp;&nbsp;&nbsp;break;<br />
&nbsp;&nbsp;&nbsp;&nbsp;...<br />
&nbsp;&nbsp;&nbsp;&nbsp;}
</tt>

<br />&nbsp;<br />&nbsp;<br />
<b>Arguments</b>

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

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

<tr>
<td><small>Name</td>
<td><small>Description</td>
<td width="50%"><small>Variable Arguments</td>
</tr>

<tr>
<td><small>SILC_COMMAND_WHOIS</td>
<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 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,
char *username, char *realname, SilcDList channels, SilcUInt32 usermode,
SilcUInt32 idletime, unsigned char *fingerprint, SilcUInt32 *channel_usermodes,
SilcDList attrs
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_WHOWAS</td>
<td><small>
Returns history information about user. The 'client_entry' and 'realname'
may be NULL.
</td>
<td width="50%"><small>SilcClientEntry client_entry, char *nickname,
char *username, char *realname
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_IDENTIFY</td>
<td><small>
Returns information about user, channel or server.  This is similar to
WHOIS command but does not return so much information and can be used to
get information about channels and servers too.  Application should ignore
this command reply.  The 'name' and 'info' may be NULL.
</td>
<td width="50%"><small>void *entry, char *name, char *info
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_NICK</td>
<td><small>
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 width="50%"><small>SilcClientEntry local_entry, char *nickname,
const SilcClientID *old_client_id
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_LIST</td>
<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', '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>
</tr>

<tr>
<td><small>SILC_COMMAND_TOPIC</td>
<td><small>
Returns the topic of the channel.
</td>
<td width="50%"><small>SilcChannelEntry channel, char *topic
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_INVITE</td>
<td><small>
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 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 width="50%"><small>SilcChannelEntry channel,
SilcArgumentPayload invite_list
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_KILL</td>
<td><small>
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 width="50%"><small>SilcClientEntry client_entry
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_INFO</td>
<td><small>
Returns information about the server user is connected to.
</td>
<td width="50%"><small>SilcServerEntry server, char *server_name,
char *server_info
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_STATS</td>
<td><small>
Returns network statistics from the server.  The `stats' structure contains
the statistics returned by the server.
</td>
<td width="50%"><small>SilcClientStats *stats
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_PING</td>
<td><small>
Returns reply to earlier ping.  There is no arguments to this reply.
</td>
<td width="50%"><small>none
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_OPER</td>
<td><small>
Returns reply to earlier SILC_COMMAND_OPER command.  There is no arguments
to this reply.
</td>
<td width="50%"><small>none
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_JOIN</td>
<td><small>
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,
SilcUInt32 channel_mode, SilcHashTableList *user_list, char *topic,
char *cipher, char *hmac, SilcPublicKey founder_key,
SilcDList channel_pubkeys, SilcUint32 user_limit
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_MOTD</td>
<td><small>
Returns the Message of the Day from the server.  The 'motd' may be NULL.
</td>
<td width="50%"><small>char *motd
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_UMODE</td>
<td><small>
Returns the user mode after changing it.
</td>
<td width="50%"><small>SilcUInt32 user_mode
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_CMODE</td>
<td><small>
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.
</td>
<td width="50%"><small>SilcChannelEntry channel, SilcUInt32 mode,
SilcPublicKey founder_key, SilcDList channel_pubkeys, SilcUint32 user_limit
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_CUMODE</td>
<td><small>
Returns user's mode on channel after changing it.
</td>
<td width="50%"><small>SilcUInt32 mode, SilcChannelEntry channel,
SilcClientEntry target_client
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_KICK</td>
<td><small>
Called after kicking a client.  Returns the client that was kicked from
the 'channel'.
</td>
<td width="50%"><small>SilcChannelEntry channel, SilcClientEntry client_entry
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_BAN</td>
<td><small>
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>
<td width="50%"><small>SilcChannelEntry channel, SilcArgumentPayload ban_list
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_DETACH</td>
<td><small>
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 width="50%"><small>SilcBuffer detach_data
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_WATCH</td>
<td><small>
Called after modifying the watch list in the server.  There is no arguments
to this reply.
</td>
<td width="50%"><small>none
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_SILCOPER</td>
<td><small>
Returns reply to earlier SILC_COMMAND_SILCOPER command.  There is no
arguments to this reply.
</td>
<td width="50%"><small>none
</td>
</tr>

<tr>
<td><small>SILC_COMMAND_LEAVE</td>
<td><small>
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>
</tr>

<tr>
<td><small>SILC_COMMAND_USERS</td>
<td><small>
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 width="50%"><small>SilcChannelEntry channel, SilcHashTableList *user_list
</td>
</tr>

<tr>
<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
SILC_ID_CLIENT SilcClientEntry and for SILC_ID_SERVER SilcServerEntry.
</td>
<td width="50%"><small>SilcIdType entry_type, void *entry,
SilcPublicKey public_key
</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 />
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.