arguments for all command replies to help SILC client software developers
to process them.
+<br /> <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 /> <br /> <br />
<b>command_reply Client Library operation</b>
<tt>
void (*command_reply)(SilcClient client, SilcClientConnection conn,<br />
-
-SilcCommandPayload cmd_payload, bool success, SilcCommand command,<br />
-
-SilcStatus status, ...);
+ SilcCommand command, SilcStatus status,<br />
+ SilcStatus error, va_list ap);
</tt>
<br /> <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
-'status' includes error status.
+'status' includes error status (see <a href="silcstatus_args.html">SilcStatus
+error arguments</a>).
<br /> <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 /> <br />
<br /> <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 /> <br />
+The 'command_reply' arguments for successful SilcCommand replies are as
+follows:
<br /> <br />
<table border="1" width="100%" cellpadding="3" cellspacing="0">
<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,
-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>
<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 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><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
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 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>
-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 width="50%"><small>none
+<td width="50%"><small>SilcClientEntry client_entry
</td>
</tr>
<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 width="50%"><small>unsigned char *stats_buffer, SilcUInt32 buffer_length
+<td width="50%"><small>SilcClientStats *stats
</td>
</tr>
<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,
-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>
<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>
<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 width="50%"><small>none
+<td width="50%"><small>SilcChannelEntry channel, SilcClientEntry client_entry
</td>
</tr>
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>
-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 width="50%"><small>none
+<td width="50%"><small>SilcBuffer detach_data
</td>
</tr>
<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>
<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 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><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,
</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 /> <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.
projects / crypto.git / blobdiff