lib/doc/command_reply_args.html

   1 <big><b>Command Reply Arguments</b></big>
   2
   3 <br />&nbsp;<br />
   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
  12 to process them.
  13
  14 <br />&nbsp;<br />
  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
  21 arguments.
  22
  23 <br />&nbsp;<br />&nbsp;<br />
  24 <b>command_reply Client Library operation</b>
  25
  26 <br />&nbsp;<br />
  27 The 'command_reply' client operation callback function prototype is as follows:
  28
  29 <br />&nbsp;<br />
  30 <tt>
  31 &nbsp;&nbsp;
  32 void (*command_reply)(SilcClient client, SilcClientConnection conn,<br />
  33 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  34 SilcCommandPayload cmd_payload, bool success, SilcCommand command,<br />
  35 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  36 SilcStatus status, ...);
  37 </tt>
  38
  39 <br />&nbsp;<br />
  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
  47 error arguments</a>).
  48
  49 <br />&nbsp;<br />
  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
  53 example:
  54
  55 <br />&nbsp;<br />
  56 <tt>
  57 &nbsp;&nbsp;switch(type)<br />
  58 &nbsp;&nbsp;&nbsp;&nbsp;{<br />
  59 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_COMMAND_WHOIS:<br />
  60 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  61 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  62 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_COMMAND_WHOWAS:<br />
  63 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  64 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  65 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_COMMAND_NICK:<br />
  66 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  67 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  68 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  69 &nbsp;&nbsp;&nbsp;&nbsp;}
  70 </tt>
  71
  72 <br />&nbsp;<br />&nbsp;<br />
  73 <b>Arguments</b>
  74
  75 <br />&nbsp;<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.
  82
  83 <br />&nbsp;<br />
  84 The 'command_reply' arguments for successful SilcCommand replies are as
  85 follows:
  86
  87 <br />&nbsp;<br />
  88 <table border="1" width="100%" cellpadding="3" cellspacing="0">
  89
  90 <tr>
  91 <td><small>Name</td>
  92 <td><small>Description</td>
  93 <td width="50%"><small>Variable Arguments</td>
  94 </tr>
  95
  96 <tr>
  97 <td><small>SILC_COMMAND_WHOIS</td>
  98 <td><small>
  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.
 108 </td>
 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,
 112 SilcDList attrs
 113 </td>
 114 </tr>
 115
 116 <tr>
 117 <td><small>SILC_COMMAND_WHOWAS</td>
 118 <td><small>
 119 Returns history information about user. The 'client_entry' and 'realname'
 120 may be NULL.
 121 </td>
 122 <td width="50%"><small>SilcClientEntry client_entry, char *nickname,
 123 char *username, char *realname
 124 </td>
 125 </tr>
 126
 127 <tr>
 128 <td><small>SILC_COMMAND_IDENTIFY</td>
 129 <td><small>
 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.
 134 </td>
 135 <td width="50%"><small>void *entry, char *name, char *info
 136 </td>
 137 </tr>
 138
 139 <tr>
 140 <td><small>SILC_COMMAND_NICK</td>
 141 <td><small>
 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.
 145 </td>
 146 <td width="50%"><small>SilcClientEntry local_entry, char *nickname,
 147 const SilcClientID *old_client_id
 148 </td>
 149 </tr>
 150
 151 <tr>
 152 <td><small>SILC_COMMAND_LIST</td>
 153 <td><small>
 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.
 161 </td>
 162 <td width="50%"><small>SilcChannelEntry channel, char *channel_name,
 163 char *channel_topic, SilcUInt32 user_count
 164 </td>
 165 </tr>
 166
 167 <tr>
 168 <td><small>SILC_COMMAND_TOPIC</td>
 169 <td><small>
 170 Returns the topic of the channel.
 171 </td>
 172 <td width="50%"><small>SilcChannelEntry channel, char *topic
 173 </td>
 174 </tr>
 175
 176 <tr>
 177 <td><small>SILC_COMMAND_INVITE</td>
 178 <td><small>
 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.
 186 </td>
 187 <td width="50%"><small>SilcChannelEntry channel, SilcBuffer invite_list
 188 </td>
 189 </tr>
 190
 191 <tr>
 192 <td><small>SILC_COMMAND_KILL</td>
 193 <td><small>
 194 Called after killing a client.  Returns the client that was killed.
 195 The `client_entry' may be NULL.
 196 </td>
 197 <td width="50%"><small>SilcClientEntry client_entry
 198 </td>
 199 </tr>
 200
 201 <tr>
 202 <td><small>SILC_COMMAND_INFO</td>
 203 <td><small>
 204 Returns information about the server user is connected to.
 205 </td>
 206 <td width="50%"><small>SilcServerEntry server, char *server_name,
 207 char *server_info
 208 </td>
 209 </tr>
 210
 211 <tr>
 212 <td><small>SILC_COMMAND_STATS</td>
 213 <td><small>
 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.
 221 </td>
 222 <td width="50%"><small>unsigned char *stats_buffer, SilcUInt32 buffer_length
 223 </td>
 224 </tr>
 225
 226 <tr>
 227 <td><small>SILC_COMMAND_PING</td>
 228 <td><small>
 229 Returns reply to earlier ping.  There is no arguments to this reply.
 230 </td>
 231 <td width="50%"><small>none
 232 </td>
 233 </tr>
 234
 235 <tr>
 236 <td><small>SILC_COMMAND_OPER</td>
 237 <td><small>
 238 Returns reply to earlier SILC_COMMAND_OPER command.  There is no arguments
 239 to this reply.
 240 </td>
 241 <td width="50%"><small>none
 242 </td>
 243 </tr>
 244
 245 <tr>
 246 <td><small>SILC_COMMAND_JOIN</td>
 247 <td><small>
 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.
 263 </td>
 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
 269 </td>
 270 </tr>
 271
 272 <tr>
 273 <td><small>SILC_COMMAND_MOTD</td>
 274 <td><small>
 275 Returns the Message of the Day from the server.  The 'motd' may be NULL.
 276 </td>
 277 <td width="50%"><small>char *motd
 278 </td>
 279 </tr>
 280
 281 <tr>
 282 <td><small>SILC_COMMAND_UMODE</td>
 283 <td><small>
 284 Returns the user mode after changing it.
 285 </td>
 286 <td width="50%"><small>SilcUInt32 user_mode
 287 </td>
 288 </tr>
 289
 290 <tr>
 291 <td><small>SILC_COMMAND_CMODE</td>
 292 <td><small>
 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
 298 Payload.
 299 </td>
 300 <td width="50%"><small>SilcChannelEntry channel, SilcUInt32 mode,
 301 SilcPublicKey founder_key, SilcBuffer channel_pubkeys,
 302 SilcUint32 user_limit
 303 </td>
 304 </tr>
 305
 306 <tr>
 307 <td><small>SILC_COMMAND_CUMODE</td>
 308 <td><small>
 309 Returns user's mode on channel after changing it.
 310 </td>
 311 <td width="50%"><small>SilcUInt32 mode, SilcChannelEntry channel,
 312 SilcClientEntry target_client
 313 </td>
 314 </tr>
 315
 316 <tr>
 317 <td><small>SILC_COMMAND_KICK</td>
 318 <td><small>
 319 Called after kicking a client.  Returns the client that was kicked from
 320 the 'channel'.  The `client_entry' and 'channel' may be NULL.
 321 </td>
 322 <td width="50%"><small>SilcChannelEntry channel, SilcClientEntry client_entry
 323 </td>
 324 </tr>
 325
 326 <tr>
 327 <td><small>SILC_COMMAND_BAN</td>
 328 <td><small>
 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.
 332 </td>
 333 <td width="50%"><small>SilcChannelEntry channel, SilcBuffer ban_list
 334 </td>
 335 </tr>
 336
 337 <tr>
 338 <td><small>SILC_COMMAND_DETACH</td>
 339 <td><small>
 340 Called after being detached from the SILC network. There is no arguments
 341 to this reply.
 342 </td>
 343 <td width="50%"><small>none
 344 </td>
 345 </tr>
 346
 347 <tr>
 348 <td><small>SILC_COMMAND_WATCH</td>
 349 <td><small>
 350 Called after modifying the watch list in the server.  There is no arguments
 351 to this reply.
 352 </td>
 353 <td width="50%"><small>none
 354 </td>
 355 </tr>
 356
 357 <tr>
 358 <td><small>SILC_COMMAND_SILCOPER</td>
 359 <td><small>
 360 Returns reply to earlier SILC_COMMAND_SILCOPER command.  There is no
 361 arguments to this reply.
 362 </td>
 363 <td width="50%"><small>none
 364 </td>
 365 </tr>
 366
 367 <tr>
 368 <td><small>SILC_COMMAND_LEAVE</td>
 369 <td><small>
 370 Called after leaving the channel.  Note that the `channel' will become
 371 invalid after command_reply client operation returns.
 372 </td>
 373 <td width="50%"><small>SilcChannelEntry channel
 374 </td>
 375 </tr>
 376
 377 <tr>
 378 <td><small>SILC_COMMAND_USERS</td>
 379 <td><small>
 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.
 384 </td>
 385 <td width="50%"><small>SilcChannelEntry channel, SilcUInt32 list_count,
 386 SilcBuffer client_id_list, SilcBuffer client_mode_list
 387 </td>
 388 </tr>
 389
 390 <tr>
 391 <td><small>SILC_COMMAND_GETKEY</td>
 392 <td><small>
 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.
 396 </td>
 397 <td width="50%"><small>SilcIdType entry_type, void *entry,
 398 SilcPublicKey public_key
 399 </td>
 400 </tr>
 401
 402 </table>
 403
 404 <br />&nbsp;<br />
 405 SILC protocol defines some additional commands but command replies to
 406 those commands are not delivered to the application.  Only the command
 407 replies listed above are delivered to application.