1 <big><b>Command Reply Arguments</b></big>
4 The SILC Client Library 'command_reply client operation (which is part of the
5 <a href="silcclient-SilcClientOperations.html">
6 SilcClientOperation</a> callback functions) returns command replies
7 from the SILC Server for commands that the client has earlier sent to the
8 server. The 'command_reply' client operation implementation has a variable
9 argument list to deliver <a href="silccommand-SilcCommand.html">SilcCommand</a>
10 specific arguments to the application. This document describes these
11 arguments for all command replies to help SILC client software developers
15 <b>NOTE: </b>The following list of command reply arguments are sent when
16 the command was executed successfully. If an error occurred, the
17 `command_reply' client operation's 'success' argument is FALSE, and the
18 'status' argument includes the error status. In this case the arguments
19 returned are dependent of the 'status' argument. See all
20 <a href="silcstatus_args.html">SilcStatus error arguments</a> for these
23 <br /> <br /> <br />
24 <b>command_reply Client Library operation</b>
27 The 'command_reply' client operation callback function prototype is as follows:
32 void (*command_reply)(SilcClient client, SilcClientConnection conn,<br />
33
34 SilcCommandPayload cmd_payload, bool success, SilcCommand command,<br />
35
36 SilcStatus status, ...);
40 The first argument 'client' is the SILC Client Library context, the 'conn'
41 is the context for the connection to the remote server, the 'cmd_payload'
42 is the raw SilcCommandPayload and application usually ignores it, the
43 'success' boolean value indicates whether the earlier command was a success
44 or not, the 'command' is the command reply enumeration, and the 'status'
45 indicates the status of the command reply. If 'success' is FALSE then
46 'status' includes error status (see <a href="silcstatus_args.html">SilcStatus
50 Rest of the arguments are 'command' specific and implementation should
51 handle them by the SilcCommand for example in a <tt>switch</tt> statement.
52 The commands are defined in lib/silccore/silccomand.h header file. A short
57 switch(type)<br />
58 {<br />
59 case SILC_COMMAND_WHOIS:<br />
60 ...<br />
61 break;<br />
62 case SILC_COMMAND_WHOWAS:<br />
63 ...<br />
64 break;<br />
65 case SILC_COMMAND_NICK:<br />
66 ...<br />
67 break;<br />
68 ...<br />
69 }
72 <br /> <br /> <br />
76 The following table describes all commands and arguments that the client
77 library sends in the 'command_reply' client operation to the application.
78 By default all arguments that the library sends to application are valid
79 pointers. However, it is possible that some pointers may be NULL. If
80 this is the case it is separately mentioned that the argument may be NULL.
81 In this case application must ignore that argument.
84 The 'command_reply' arguments for successful SilcCommand replies are as
88 <table border="1" width="100%" cellpadding="3" cellspacing="0">
92 <td><small>Description</td>
93 <td width="50%"><small>Variable Arguments</td>
97 <td><small>SILC_COMMAND_WHOIS</td>
99 Returns information about user. The following pointers may be NULL: 'channels',
100 'fingerprint', 'channel_usermodes' and 'attrs'. If 'fingerprint' is valid its
101 length is 20 bytes. If 'channels' is valid it can be parsed with
102 silc_channel_payload_parse_list function. It is the list of channels user
103 has joined. If the 'channel_usermodes' is valid it can be parsed with
104 silc_get_mode_list function. It is the list of the user's modes on the
105 joined channels. The 'attr' is the Requested Attributes that may have been
106 returned by the client and it can be parsed by traversing the SilcDList
107 and using silc_attribute_get_attribute function.
109 <td width="50%"><small>SilcClientEntry client_entry, char *nickname,
110 char *username, char *realname, SilcBuffer channels, SilcUInt32 usermode,
111 SilcUInt32 idletime, unsigned char *fingerprint, SilcBuffer channel_usermodes,
117 <td><small>SILC_COMMAND_WHOWAS</td>
119 Returns history information about user. The 'client_entry' and 'realname'
122 <td width="50%"><small>SilcClientEntry client_entry, char *nickname,
123 char *username, char *realname
128 <td><small>SILC_COMMAND_IDENTIFY</td>
130 Returns information about user, channel or server. This is similar to
131 WHOIS command but does not return so much information and can be used to
132 get information about channels and servers too. Application should ignore
133 this command reply. The 'name' and 'info' may be NULL.
135 <td width="50%"><small>void *entry, char *name, char *info
140 <td><small>SILC_COMMAND_NICK</td>
142 Returns the new Client ID and new nickname inside the SilcClientEntry.
143 The `old_client_id' is the odl Client ID used by the client before the
144 nickname was changed.
146 <td width="50%"><small>SilcClientEntry local_entry, char *nickname,
147 const SilcClientID *old_client_id
152 <td><small>SILC_COMMAND_LIST</td>
154 Returns the list of channel in the SILC network. Each call of command reply
155 returns one channel. This means that the command reply is called multiple
156 times to return list of channels. The 'channel', 'channel_name' and
157 'channel_topic' may be NULL. However, the 'channel' and 'channel_name'
158 are NULL only if there are no channels in the network. In this case
159 this reply is called once with all arguments set to NULL. Application
160 must be able to handle this situation correctly.
162 <td width="50%"><small>SilcChannelEntry channel, char *channel_name,
163 char *channel_topic, SilcUInt32 user_count
168 <td><small>SILC_COMMAND_TOPIC</td>
170 Returns the topic of the channel.
172 <td width="50%"><small>SilcChannelEntry channel, char *topic
177 <td><small>SILC_COMMAND_INVITE</td>
179 Returns the invite list of the channel. Called also even if invite list
180 was not modified but SILC_COMMAND_INVITE command was used to invite a user
181 into a channel. In this case the invite list is not returned by the
182 server and 'invite_list' is NULL. The 'invite_list' is list of
183 SilcArgumentPayloads. The first 2 bytes are the number of arguments in
184 the list and can be parsed with SILC_GET16_MSB macro. The list can be
185 parsed with silc_argument_payload_parse function.
187 <td width="50%"><small>SilcChannelEntry channel, SilcBuffer invite_list
192 <td><small>SILC_COMMAND_KILL</td>
194 Called after killing a client. Returns the client that was killed.
195 The `client_entry' may be NULL.
197 <td width="50%"><small>SilcClientEntry client_entry
202 <td><small>SILC_COMMAND_INFO</td>
204 Returns information about the server user is connected to.
206 <td width="50%"><small>SilcServerEntry server, char *server_name,
212 <td><small>SILC_COMMAND_STATS</td>
214 Returns network statistics from the server. The 'stats_buffer' of length of
215 'buffer_length' bytes includes 32-bit integers one after the other each
216 representing some statistics. The integers can be parsed for example with
217 SILC_GET32_MSB macro. The integers in the buffer are: starttime, uptime,
218 local_clients, local_channels, local_serverops, local_routerops, cell_clients,
219 cell_channels, cell_servers, all_clients, all_channel, all_servers,
220 all_routers, all_serverops, all_routerops. All integers are always present.
222 <td width="50%"><small>unsigned char *stats_buffer, SilcUInt32 buffer_length
227 <td><small>SILC_COMMAND_PING</td>
229 Returns reply to earlier ping. There is no arguments to this reply.
231 <td width="50%"><small>none
236 <td><small>SILC_COMMAND_OPER</td>
238 Returns reply to earlier SILC_COMMAND_OPER command. There is no arguments
241 <td width="50%"><small>none
246 <td><small>SILC_COMMAND_JOIN</td>
248 Reply received when user joined a channel. The 'ignored' argument can
249 be ignored by the application. The 'topic' and 'hmac_name' may be NULL.
250 The 'key_payload' is usually ignored by the application. The 'list_count'
251 is the number of entries in both 'client_id_list' and 'client_mode_list'.
252 The 'client_id_list' is a list of clients on the channel and 'client_mode_list'
253 includes those clients' modes on the channel. If application likes to
254 resolve information about the clients on the channel it may call
255 silc_client_get_clients_by_list function and pass the 'client_id_list' as
256 argument to it. The 'client_mode_list' includes 32-bit integers one after
257 the other and they are in same order as clients in 'client_mode_list'.
258 If application resolves the information with silc_client_get_clients_by_list
259 parsing the 'client_mode_list' is not necessary. The 'founder_key' is the
260 channel founder's key and may be NULL. The 'channel_pubkeys' is Argument
261 List Payload containing Public Key Payloads of all added channel public
262 keys, it may be NULL.
264 <td width="50%"><small>char *channel_name, SilcChannelEntry channel,
265 SilcUInt32 channel_mode, int ignored, SilcBuffer key_payload, NULL, NULL,
266 char *topic, char *hmac_name, SilcUInt32 list_count, SilcBuffer client_id_list,
267 SilcBuffer client_mode_list, SilcPublicKey founder_key,
268 SilcBuffer channel_pubkeys, SilcUint32 user_limit
273 <td><small>SILC_COMMAND_MOTD</td>
275 Returns the Message of the Day from the server. The 'motd' may be NULL.
277 <td width="50%"><small>char *motd
282 <td><small>SILC_COMMAND_UMODE</td>
284 Returns the user mode after changing it.
286 <td width="50%"><small>SilcUInt32 user_mode
291 <td><small>SILC_COMMAND_CMODE</td>
293 Returns channel's mode after changing it. Optionally may also return
294 founder's public key when it was set. It may also return the channel
295 public key list when the list was altered. The 'founder_key' and
296 'channel_pubkeys' arguments may be NULL. The 'channel_pubkeys' is an
297 Argument List Payload where each argument includes one Public Key
300 <td width="50%"><small>SilcChannelEntry channel, SilcUInt32 mode,
301 SilcPublicKey founder_key, SilcBuffer channel_pubkeys,
302 SilcUint32 user_limit
307 <td><small>SILC_COMMAND_CUMODE</td>
309 Returns user's mode on channel after changing it.
311 <td width="50%"><small>SilcUInt32 mode, SilcChannelEntry channel,
312 SilcClientEntry target_client
317 <td><small>SILC_COMMAND_KICK</td>
319 Called after kicking a client. Returns the client that was kicked from
320 the 'channel'. The `client_entry' and 'channel' may be NULL.
322 <td width="50%"><small>SilcChannelEntry channel, SilcClientEntry client_entry
327 <td><small>SILC_COMMAND_BAN</td>
329 Returns channel's ban list. The 'ban_list' may be NULL. The construction
330 of that list is equivalent to invite list. See description of
331 SILC_COMMAND_INVITE command reply.
333 <td width="50%"><small>SilcChannelEntry channel, SilcBuffer ban_list
338 <td><small>SILC_COMMAND_DETACH</td>
340 Called after being detached from the SILC network. There is no arguments
343 <td width="50%"><small>none
348 <td><small>SILC_COMMAND_WATCH</td>
350 Called after modifying the watch list in the server. There is no arguments
353 <td width="50%"><small>none
358 <td><small>SILC_COMMAND_SILCOPER</td>
360 Returns reply to earlier SILC_COMMAND_SILCOPER command. There is no
361 arguments to this reply.
363 <td width="50%"><small>none
368 <td><small>SILC_COMMAND_LEAVE</td>
370 Called after leaving the channel. Note that the `channel' will become
371 invalid after command_reply client operation returns.
373 <td width="50%"><small>SilcChannelEntry channel
378 <td><small>SILC_COMMAND_USERS</td>
380 Returns list of users in channel. If application wishes not to parse
381 the raw lists the channel->user_list hash table is updated before calling
382 this command reply and application may traverse that table instead of
383 parssing the raw lists.
385 <td width="50%"><small>SilcChannelEntry channel, SilcUInt32 list_count,
386 SilcBuffer client_id_list, SilcBuffer client_mode_list
391 <td><small>SILC_COMMAND_GETKEY</td>
393 Returns public key of client or server. The 'public_key' may be NULL.
394 The 'entry_type' is used to check what type of pointer the entry' is. For
395 SILC_ID_CLIENT SilcClientEntry and for SILC_ID_SERVER SilcServerEntry.
397 <td width="50%"><small>SilcIdType entry_type, void *entry,
398 SilcPublicKey public_key
403 <td><small>SILC_COMMAND_SERVICE</td>
405 Returns the service list in the server, or information on the accepted
406 and authenticated service. The 'service_list' maybe NULL if server does
407 not support any services. It is NULL also when 'name' is not NULL. The
408 'service_list' is a comma separated list of services the server supports.
409 The 'name' MAY be NULL also. The 'name' is the requested service, and it is
410 non-NULL only if server accepted and authenticated client's request.
412 <td width="50%"><small>const char *server_list, const char *service_name
419 SILC protocol defines some additional commands but command replies to
420 those commands are not delivered to the application. Only the command
421 replies listed above are delivered to application.