X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fdoc%2Fcommand_reply_args.html;h=49b79d6a1bacda08f744a19ef8b252d816aef559;hb=a9c6c36d5712c2fa017d1e82126a7d3c6f32a05a;hp=5a964271658f52abaac40a08af5e8579ef4e0b0a;hpb=ecb19b3983b3e74bc4aaa82277abd125c53c3623;p=crypto.git diff --git a/lib/doc/command_reply_args.html b/lib/doc/command_reply_args.html index 5a964271..49b79d6a 100644 --- 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. +
 
+NOTE: 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 +SilcStatus error arguments for these +arguments. +
 
 
command_reply Client Library operation @@ -21,25 +30,24 @@ The 'command_reply' client operation callback function prototype is as follows:    void (*command_reply)(SilcClient client, SilcClientConnection conn,
-          -SilcCommandPayload cmd_payload, bool success, SilcCommand command,
-          -SilcStatus status, ...); + SilcCommand command, SilcStatus status,
+ SilcStatus error, va_list ap);
 
-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 SilcStatus +error arguments).
 
Rest of the arguments are 'command' specific and implementation should handle them by the SilcCommand for example in a switch 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:
 
@@ -64,12 +72,15 @@ example:
 
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. + +
 
+The 'command_reply' arguments for successful SilcCommand replies are as +follows:
 
@@ -85,17 +96,19 @@ arguments per SilcCommand is as follows: @@ -126,9 +139,14 @@ this command reply. The 'name' and 'info' may be NULL. - @@ -137,7 +155,11 @@ Returns the new Client ID after user has changed nickname. - - @@ -190,15 +217,10 @@ char *server_info - @@ -224,23 +246,24 @@ to this reply. @@ -265,9 +288,18 @@ Returns the user mode after changing it. - + @@ -284,9 +316,10 @@ SilcClientEntry target_client - @@ -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. - - @@ -334,7 +371,8 @@ arguments to this reply. @@ -343,13 +381,12 @@ Called after leaving the channel. - @@ -357,7 +394,7 @@ SilcBuffer client_id_list, SilcBuffer client_mode_list + + + + + +
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. 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
SILC_COMMAND_NICK -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. SilcClientEntry local_entry, char *nickname +SilcClientEntry local_entry, char *nickname, +const SilcClientID *old_client_id
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. 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 -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. SilcChannelEntry channel, SilcBuffer invite_list +SilcChannelEntry channel, +SilcArgumentPayload invite_list
SILC_COMMAND_KILL -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. none +SilcClientEntry client_entry
SILC_COMMAND_STATS -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. unsigned char *stats_buffer, SilcUInt32 buffer_length +SilcClientStats *stats
SILC_COMMAND_JOIN -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. 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
SILC_COMMAND_CMODE -Returns channel's mode after changing it. -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. +SilcChannelEntry channel, SilcUInt32 mode, +SilcPublicKey founder_key, SilcDList channel_pubkeys, SilcUint32 user_limit
SILC_COMMAND_KICK -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'. none +SilcChannelEntry channel, SilcClientEntry client_entry
SilcChannelEntry channel, SilcBuffer ban_list +SilcChannelEntry channel, SilcArgumentPayload ban_list
SILC_COMMAND_DETACH -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. none +SilcBuffer detach_data
SILC_COMMAND_LEAVE -Called after leaving the channel. +Called after leaving the channel. Note that the `channel' will become +invalid after command_reply client operation returns. SilcChannelEntry channel
SILC_COMMAND_USERS -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. SilcChannelEntry channel, SilcUInt32 list_count, -SilcBuffer client_id_list, SilcBuffer client_mode_list +SilcChannelEntry channel, SilcHashTableList *user_list
SILC_COMMAND_GETKEY 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. SilcIdType entry_type, void *entry, @@ -365,9 +402,23 @@ SilcPublicKey public_key
SILC_COMMAND_SERVICE +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. +const char *server_list, const char *service_name +

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