X-Git-Url: http://git.silcnet.org/gitweb/?p=website.git;a=blobdiff_plain;f=docs%2Ftoolkit%2Fmanual%2Fcommand_reply_args.html;fp=docs%2Ftoolkit%2Fmanual%2Fcommand_reply_args.html;h=2e8762333d2f9af4c8cd690350e52c55b33db7b6;hp=0000000000000000000000000000000000000000;hb=80b80cef93d9dff6acc4bc8e3a522c55fcdc3fca;hpb=43e53f529ca5c7d2ddb7cee8e76e273631e6f1e2 diff --git a/docs/toolkit/manual/command_reply_args.html b/docs/toolkit/manual/command_reply_args.html new file mode 100644 index 0000000..2e87623 --- /dev/null +++ b/docs/toolkit/manual/command_reply_args.html @@ -0,0 +1,615 @@ + + + + + + + + + + + + + + + + + + + +
Copyright © 2001 - 2007 SILC Project
+ SILC Project Website
+ SILC Toolkit Reference Manual
+ Index
+ + +
+ + + + + + + + + + + + + + +
+ + + +
+
+ + + +SILC Toolkit Reference Manual
+ + +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 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 Key Exchange Library
+    SILC SKE Interface
+    SILC Connection Authentication Interface
+SILC VCard Library
+    SILC VCard Interface
+SILC Math Library
+    SILC MP Interface
+    SILC Math 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 ASN.1 Library
+    SILC ASN.1 Interface
+    SILC BER interface
+SILC HTTP Library
+    SILC HTTP Server Interface
+    SILC HTTP PHP Translator
+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 Key Repository Library
+    SILC SKR Interface
+SILC Application Utility Library
+    SILC Application Utilities
+    SILC ID Cache Interface
+SILC SFTP Library
+    SILC SFTP Interface
+    SFTP Filesystems Interface
+ +
+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: + +
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionVariable 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
+ + +