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_topic' may be NULL.
 157 </td>
 158 <td width="50%"><small>SilcChannelEntry channel, char *channel_name,
 159 char *channel_topic, SilcUInt32 user_count
 160 </td>
 161 </tr>
 162
 163 <tr>
 164 <td><small>SILC_COMMAND_TOPIC</td>
 165 <td><small>
 166 Returns the topic of the channel.
 167 </td>
 168 <td width="50%"><small>SilcChannelEntry channel, char *topic
 169 </td>
 170 </tr>
 171
 172 <tr>
 173 <td><small>SILC_COMMAND_INVITE</td>
 174 <td><small>
 175 Returns the invite list of the channel.  Called also even if invite list
 176 was not modified but SILC_COMMAND_INVITE command was used to invite a user
 177 into a channel.  In this case the invite list is not returned by the
 178 server and 'invite_list' is NULL.  The 'invite_list' is list of
 179 SilcArgumentPayloads.  The first 2 bytes are the number of arguments in
 180 the list and can be parsed with SILC_GET16_MSB macro.  The list can be
 181 parsed with silc_argument_payload_parse function.
 182 </td>
 183 <td width="50%"><small>SilcChannelEntry channel, SilcBuffer invite_list
 184 </td>
 185 </tr>
 186
 187 <tr>
 188 <td><small>SILC_COMMAND_KILL</td>
 189 <td><small>
 190 Called after killing a client.  Returns the client that was killed.
 191 The `client_entry' may be NULL.
 192 </td>
 193 <td width="50%"><small>SilcClientEntry client_entry
 194 </td>
 195 </tr>
 196
 197 <tr>
 198 <td><small>SILC_COMMAND_INFO</td>
 199 <td><small>
 200 Returns information about the server user is connected to.
 201 </td>
 202 <td width="50%"><small>SilcServerEntry server, char *server_name,
 203 char *server_info
 204 </td>
 205 </tr>
 206
 207 <tr>
 208 <td><small>SILC_COMMAND_STATS</td>
 209 <td><small>
 210 Returns network statistics from the server.  The 'stats_buffer' of length of
 211 'buffer_length' bytes includes 32-bit integers one after the other each
 212 representing some statistics.  The integers can be parsed for example with
 213 SILC_GET32_MSB macro.  The integers in the buffer are: starttime, uptime,
 214 local_clients, local_channels, local_serverops, local_routerops, cell_clients,
 215 cell_channels, cell_servers, all_clients, all_channel, all_servers,
 216 all_routers, all_serverops, all_routerops.  All integers are always present.
 217 </td>
 218 <td width="50%"><small>unsigned char *stats_buffer, SilcUInt32 buffer_length
 219 </td>
 220 </tr>
 221
 222 <tr>
 223 <td><small>SILC_COMMAND_PING</td>
 224 <td><small>
 225 Returns reply to earlier ping.  There is no arguments to this reply.
 226 </td>
 227 <td width="50%"><small>none
 228 </td>
 229 </tr>
 230
 231 <tr>
 232 <td><small>SILC_COMMAND_OPER</td>
 233 <td><small>
 234 Returns reply to earlier SILC_COMMAND_OPER command.  There is no arguments
 235 to this reply.
 236 </td>
 237 <td width="50%"><small>none
 238 </td>
 239 </tr>
 240
 241 <tr>
 242 <td><small>SILC_COMMAND_JOIN</td>
 243 <td><small>
 244 Reply received when user joined a channel.  The 'ignored' argument can
 245 be ignored by the application.  The 'topic' and 'hmac_name' may be NULL.
 246 The 'key_payload' is usually ignored by the application.  The 'list_count'
 247 is the number of entries in both 'client_id_list' and 'client_mode_list'.
 248 The 'client_id_list' is a list of clients on the channel and 'client_mode_list'
 249 includes those clients' modes on the channel.  If application likes to
 250 resolve information about the clients on the channel it may call
 251 silc_client_get_clients_by_list function and pass the 'client_id_list' as
 252 argument to it.  The 'client_mode_list' includes 32-bit integers one after
 253 the other and they are in same order as clients in 'client_mode_list'.
 254 If application resolves the information with silc_client_get_clients_by_list
 255 parsing the 'client_mode_list' is not necessary.  The 'founder_key' is the
 256 channel founder's key and may be NULL.  The 'channel_pubkeys' is Argument
 257 List Payload containing Public Key Payloads of all added channel public
 258 keys, it may be NULL.
 259 </td>
 260 <td width="50%"><small>char *channel_name, SilcChannelEntry channel,
 261 SilcUInt32 channel_mode, int ignored, SilcBuffer key_payload, NULL, NULL,
 262 char *topic, char *hmac_name, SilcUInt32 list_count, SilcBuffer client_id_list,
 263 SilcBuffer client_mode_list, SilcPublicKey founder_key,
 264 SilcBuffer channel_pubkeys
 265 </td>
 266 </tr>
 267
 268 <tr>
 269 <td><small>SILC_COMMAND_MOTD</td>
 270 <td><small>
 271 Returns the Message of the Day from the server.  The 'motd' may be NULL.
 272 </td>
 273 <td width="50%"><small>char *motd
 274 </td>
 275 </tr>
 276
 277 <tr>
 278 <td><small>SILC_COMMAND_UMODE</td>
 279 <td><small>
 280 Returns the user mode after changing it.
 281 </td>
 282 <td width="50%"><small>SilcUInt32 user_mode
 283 </td>
 284 </tr>
 285
 286 <tr>
 287 <td><small>SILC_COMMAND_CMODE</td>
 288 <td><small>
 289 Returns channel's mode after changing it.  Optionally may also return
 290 founder's public key when it was set.  It may also return the channel
 291 public key list when the list was altered.  The 'founder_key' and
 292 'channel_pubkeys' arguments may be NULL.  The 'channel_pubkeys' is an
 293 Argument List Payload where each argument includes one Public Key
 294 Payload.
 295 </td>
 296 <td width="50%"><small>SilcChannelEntry channel, SilcUInt32 mode,
 297 SilcPublicKey founder_key, SilcBuffer channel_pubkeys
 298 </td>
 299 </tr>
 300
 301 <tr>
 302 <td><small>SILC_COMMAND_CUMODE</td>
 303 <td><small>
 304 Returns user's mode on channel after changing it.
 305 </td>
 306 <td width="50%"><small>SilcUInt32 mode, SilcChannelEntry channel,
 307 SilcClientEntry target_client
 308 </td>
 309 </tr>
 310
 311 <tr>
 312 <td><small>SILC_COMMAND_KICK</td>
 313 <td><small>
 314 Called after kicking a client.  Returns the client that was kicked from
 315 the 'channel'.  The `client_entry' and 'channel' may be NULL.
 316 </td>
 317 <td width="50%"><small>SilcChannelEntry channel, SilcClientEntry client_entry
 318 </td>
 319 </tr>
 320
 321 <tr>
 322 <td><small>SILC_COMMAND_BAN</td>
 323 <td><small>
 324 Returns channel's ban list.  The 'ban_list' may be NULL.  The construction
 325 of that list is equivalent to invite list.  See description of
 326 SILC_COMMAND_INVITE command reply.
 327 </td>
 328 <td width="50%"><small>SilcChannelEntry channel, SilcBuffer ban_list
 329 </td>
 330 </tr>
 331
 332 <tr>
 333 <td><small>SILC_COMMAND_DETACH</td>
 334 <td><small>
 335 Called after being detached from the SILC network. There is no arguments
 336 to this reply.
 337 </td>
 338 <td width="50%"><small>none
 339 </td>
 340 </tr>
 341
 342 <tr>
 343 <td><small>SILC_COMMAND_WATCH</td>
 344 <td><small>
 345 Called after modifying the watch list in the server.  There is no arguments
 346 to this reply.
 347 </td>
 348 <td width="50%"><small>none
 349 </td>
 350 </tr>
 351
 352 <tr>
 353 <td><small>SILC_COMMAND_SILCOPER</td>
 354 <td><small>
 355 Returns reply to earlier SILC_COMMAND_SILCOPER command.  There is no
 356 arguments to this reply.
 357 </td>
 358 <td width="50%"><small>none
 359 </td>
 360 </tr>
 361
 362 <tr>
 363 <td><small>SILC_COMMAND_LEAVE</td>
 364 <td><small>
 365 Called after leaving the channel.  Note that the `channel' will become
 366 invalid after command_reply client operation returns.
 367 </td>
 368 <td width="50%"><small>SilcChannelEntry channel
 369 </td>
 370 </tr>
 371
 372 <tr>
 373 <td><small>SILC_COMMAND_USERS</td>
 374 <td><small>
 375 Returns list of users in channel.  If application wishes not to parse
 376 the raw lists the channel->user_list hash table is updated before calling
 377 this command reply and application may traverse that table instead of
 378 parssing the raw lists.
 379 </td>
 380 <td width="50%"><small>SilcChannelEntry channel, SilcUInt32 list_count,
 381 SilcBuffer client_id_list, SilcBuffer client_mode_list
 382 </td>
 383 </tr>
 384
 385 <tr>
 386 <td><small>SILC_COMMAND_GETKEY</td>
 387 <td><small>
 388 Returns public key of client or server.  The 'public_key' may be NULL.
 389 The 'entry_type' is used to check what type of pointer the entry' is.  For
 390 SILC_ID_CLIENT SilcClientEntry and for SILC_ID_SERVER SilcServerEntry.
 391 </td>
 392 <td width="50%"><small>SilcIdType entry_type, void *entry,
 393 SilcPublicKey public_key
 394 </td>
 395 </tr>
 396
 397 </table>
 398
 399 <br />&nbsp;<br />
 400 SILC protocol defines some additional commands but command replies to
 401 those commands are not delivered to the application.  Only the command
 402 replies listed above are delivered to application.