Copyright © 2001 - 2007 SILC Project SILC Project Website | SILC Toolkit Reference Manual Index

SILC Toolkit Reference Manual
SILC VCard Library
SILC VCard Interface
SILC Crypto Library
Introduction to SILC RNG
SILC RNG Interface
SILC Cipher API
SILC PKCS API
SILC Public Key API
SILC PKCS #1 API
SILC Hash Interface
SILC HMAC Interface
SILC Client Library
Using SILC Client Library Tutorial
Arguments for command_reply Client Operation
SilcStatus Error Arguments in command_reply Client Operation
Arguments for notify Client Operation
Unicode and UTF-8 Strings in Client Library
Client Library Interface Reference
Client Entry Interface Reference
SILC Math Library
SILC MP Interface
SILC Math Interface
SILC Application Utility Library
SILC Application Utilities
SILC ID Cache Interface
SILC Key Repository Library
SILC SKR Interface
SILC ASN.1 Library
SILC ASN.1 Interface
SILC BER interface
SILC Key Exchange Library
SILC SKE Interface
SILC Connection Authentication Interface
SILC SFTP Library
SILC SFTP Interface
SFTP Filesystems Interface
SILC Core Library
SILC Authentication Interface
SILC Message Interface
SILC Channel Interface
SILC Command Interface
SILC Notify Interface
SILC Status Types
SILC Modes
SILC ID Interface
SILC Argument Interface
SILC Attributes Interface
Packet Engine Interface
SILC Public Key Payload Interface
SILC Utility Library
Basic Types and Definitions
Data Buffer Interface
Data Buffer Format Interface
Hash Table Interface
Memory Allocation Interface
Data Stack (memory pool) Interface
Finite State Machine Interface
Thread Interface
Mutual Exclusion Lock Interface
Condition Variable Interface
Atomic Operations Interface
Network (TCP and UDP) Interface
Scheduler Interface
Asynchronous Operation Interface
Abstract Stream Interface
Socket Stream Interface
File Descriptor Stream Interface
File Utility Functions
String Utility Interface
Snprintf Interface
UTF-8 String Interface
Stringprep Interface
Utility Functions
List Interface
Dynamic List Interface
MIME Interface
Time Utility Functions
Logging Interface
Config File Interface
SILC HTTP Library
SILC HTTP Server Interface
SILC HTTP PHP Translator
Resource Links
SILC Project Website
SILC Protocol Documentation
SILC White Paper
SILC FAQs

Command Reply Arguments
The SILC Client Library 'command_reply client operation (which is part of the SilcClientOperation 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 SilcCommand 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
The 'command_reply' client operation callback function prototype is as follows:
`void (*command_reply)(SilcClient client, SilcClientConnection conn,
SilcCommand command, SilcStatus status,
SilcStatus error, va_list ap);`
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 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 example:
`switch(type)
{
case SILC_COMMAND_WHOIS:
...
break;
case SILC_COMMAND_WHOWAS:
...
break;
case SILC_COMMAND_NICK:
...
break;
...
}`
Arguments
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 for successful SilcCommand replies are as follows:

Name | Description | Variable Arguments

SILC_COMMAND_WHOIS

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.

SilcClientEntry client_entry, char *nickname, char *username, char *realname, SilcDList channels, SilcUInt32 usermode, SilcUInt32 idletime, unsigned char *fingerprint, SilcUInt32 *channel_usermodes, SilcDList attrs

SILC_COMMAND_WHOWAS | Returns history information about user. The 'client_entry' and 'realname' may be NULL. | SilcClientEntry client_entry, char *nickname, char *username, char *realname
SILC_COMMAND_IDENTIFY | 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. | void *entry, char *name, char *info

SILC_COMMAND_NICK

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, const SilcClientID *old_client_id

SILC_COMMAND_LIST

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.

SilcChannelEntry channel, char *channel_name, char *channel_topic, SilcUInt32 user_count

SILC_COMMAND_TOPIC | Returns the topic of the channel. | SilcChannelEntry channel, char *topic

SILC_COMMAND_INVITE

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.

SilcChannelEntry channel, SilcArgumentPayload invite_list

SILC_COMMAND_KILL | 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. | SilcClientEntry client_entry
SILC_COMMAND_INFO | Returns information about the server user is connected to. | SilcServerEntry server, char *server_name, char *server_info
SILC_COMMAND_STATS | Returns network statistics from the server. The `stats' structure contains the statistics returned by the server. | SilcClientStats *stats
SILC_COMMAND_PING | Returns reply to earlier ping. There is no arguments to this reply. | none
SILC_COMMAND_OPER | Returns reply to earlier SILC_COMMAND_OPER command. There is no arguments to this reply. | none

SILC_COMMAND_JOIN

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, SilcHashTableList *user_list, char *topic, char *cipher, char *hmac, SilcPublicKey founder_key, SilcDList channel_pubkeys, SilcUint32 user_limit

SILC_COMMAND_MOTD | Returns the Message of the Day from the server. The 'motd' may be NULL. | char *motd
SILC_COMMAND_UMODE | Returns the user mode after changing it. | SilcUInt32 user_mode

SILC_COMMAND_CMODE

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.

SilcChannelEntry channel, SilcUInt32 mode, SilcPublicKey founder_key, SilcDList channel_pubkeys, SilcUint32 user_limit

SILC_COMMAND_CUMODE | Returns user's mode on channel after changing it. | SilcUInt32 mode, SilcChannelEntry channel, SilcClientEntry target_client
SILC_COMMAND_KICK | Called after kicking a client. Returns the client that was kicked from the 'channel'. | SilcChannelEntry channel, SilcClientEntry client_entry
SILC_COMMAND_BAN | 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. | SilcChannelEntry channel, SilcArgumentPayload ban_list

SILC_COMMAND_DETACH

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.

SilcBuffer detach_data

SILC_COMMAND_WATCH | Called after modifying the watch list in the server. There is no arguments to this reply. | none
SILC_COMMAND_SILCOPER | Returns reply to earlier SILC_COMMAND_SILCOPER command. There is no arguments to this reply. | none
SILC_COMMAND_LEAVE | 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. 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, 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 SILC_ID_CLIENT SilcClientEntry and for SILC_ID_SERVER SilcServerEntry. | SilcIdType entry_type, void *entry, 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 those commands are not delivered to the application. Only the command replies listed above are delivered to application.

Copyright © 2001 - 2007 SILC Project SILC Project Website | SILC Toolkit Reference Manual Index