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 />&nbsp;<br />
  15 <b>command_reply Client Library operation</b>
  16
  17 <br />&nbsp;<br />
  18 The 'command_reply' client operation callback function prototype is as follows:
  19
  20 <br />&nbsp;<br />
  21 <tt>
  22 &nbsp;&nbsp;
  23 void (*command_reply)(SilcClient client, SilcClientConnection conn,<br />
  24 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  25 SilcCommandPayload cmd_payload, bool success, SilcCommand command,<br />
  26 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  27 SilcStatus status, ...);
  28 </tt>
  29
  30 <br />&nbsp;<br />
  31 The first argument 'client' is the SILC Client Library context, the 'conn'
  32 is the context for the connection to the remote server, the 'cmd_payload'
  33 is the raw SilcCommandPayload and application usually ignores it, the
  34 'success' boolean value indicates whether the earlier command was a success
  35 or not, the 'command' is the command reply enumeration, and the 'status'
  36 indicates the status of the command reply.  If 'success' is FALSE then
  37 'status' includes error status.
  38
  39 <br />&nbsp;<br />
  40 Rest of the arguments are 'command' specific and implementation should
  41 handle them by the SilcCommand for example in a <tt>switch</tt> statement.
  42 The commands are defined in lib/silccore/silccomand.h header file.  A short
  43 example:
  44
  45 <br />&nbsp;<br />
  46 <tt>
  47 &nbsp;&nbsp;switch(type)<br />
  48 &nbsp;&nbsp;&nbsp;&nbsp;{<br />
  49 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_COMMAND_WHOIS:<br />
  50 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  51 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  52 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_COMMAND_WHOWAS:<br />
  53 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  54 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  55 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_COMMAND_NICK:<br />
  56 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  57 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  58 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  59 &nbsp;&nbsp;&nbsp;&nbsp;}
  60 </tt>
  61
  62 <br />&nbsp;<br />&nbsp;<br />
  63 <b>Arguments</b>
  64
  65 <br />&nbsp;<br />
  66 The following table describes all commands and arguments that the client
  67 library sends in the 'command_reply' client operation to the application.
  68 By default all arguments that the library sends to application are valid
  69 pointers.  However, it is possible that some pointers may be NULL.  If
  70 this is the case it is separately mentioned that the argument may be NULL.
  71 In this case application must ignore that argument.  The 'command_reply'
  72 arguments per SilcCommand is as follows:
  73
  74 <br />&nbsp;<br />
  75 <table border="1" width="100%" cellpadding="3" cellspacing="0">
  76
  77 <tr>
  78 <td><small>Name</td>
  79 <td><small>Description</td>
  80 <td width="50%"><small>Variable Arguments</td>
  81 </tr>
  82
  83 <tr>
  84 <td><small>SILC_COMMAND_WHOIS</td>
  85 <td><small>
  86 Returns information about user. The following pointers may be NULL: 'channels',
  87 'fingerprint', 'channel_usermodes' and 'attrs'.  If 'fingerprint' is valid its
  88 length is 20 bytes. If 'channels' is valid it can be parsed with
  89 silc_channel_payload_parse_list function. It is the list of channels user
  90 has joined. If the 'channel_usermodes' is valid it can be parsed with
  91 silc_get_mode_list function. It is the list of the user's modes on the
  92 joined channels. The 'attr' is the Requested Attributes that may have been
  93 returned by the client and it can be parsed by traversing the SilcDList
  94 and using silc_attribute_get_attribute function.
  95 </td>
  96 <td width="50%"><small>SilcClientEntry client_entry, char *nickname,
  97 char *username, char *realname, SilcBuffer channels, SilcUInt32 usermode,
  98 SilcUInt32 idletime, unsigned char *fingerprint, SilcBuffer channel_usermodes,
  99 SilcDList attrs
 100 </td>
 101 </tr>
 102
 103 <tr>
 104 <td><small>SILC_COMMAND_WHOWAS</td>
 105 <td><small>
 106 Returns history information about user. The 'client_entry' and 'realname'
 107 may be NULL.
 108 </td>
 109 <td width="50%"><small>SilcClientEntry client_entry, char *nickname,
 110 char *username, char *realname
 111 </td>
 112 </tr>
 113
 114 <tr>
 115 <td><small>SILC_COMMAND_IDENTIFY</td>
 116 <td><small>
 117 Returns information about user, channel or server.  This is similar to
 118 WHOIS command but does not return so much information and can be used to
 119 get information about channels and servers too.  Application should ignore
 120 this command reply.  The 'name' and 'info' may be NULL.
 121 </td>
 122 <td width="50%"><small>void *entry, char *name, char *info
 123 </td>
 124 </tr>
 125
 126 <tr>
 127 <td><small>SILC_COMMAND_NICK</td>
 128 <td><small>
 129 Returns the new Client ID and new nickname inside the SilcClientEntry.
 130 The `old_client_id' is the odl Client ID used by the client before the
 131 nickname was changed.
 132 </td>
 133 <td width="50%"><small>SilcClientEntry local_entry, char *nickname,
 134 const SilcClientID *old_client_id
 135 </td>
 136 </tr>
 137
 138 <tr>
 139 <td><small>SILC_COMMAND_LIST</td>
 140 <td><small>
 141 Returns the list of channel in the SILC network. Each call of command reply
 142 returns one channel. This means that the command reply is called multiple
 143 times to return list of channels.  The 'channel_topic' may be NULL.
 144 </td>
 145 <td width="50%"><small>SilcChannelEntry channel, char *channel_name,
 146 char *channel_topic, SilcUInt32 user_count
 147 </td>
 148 </tr>
 149
 150 <tr>
 151 <td><small>SILC_COMMAND_TOPIC</td>
 152 <td><small>
 153 Returns the topic of the channel.
 154 </td>
 155 <td width="50%"><small>SilcChannelEntry channel, char *topic
 156 </td>
 157 </tr>
 158
 159 <tr>
 160 <td><small>SILC_COMMAND_INVITE</td>
 161 <td><small>
 162 Returns the invite list of the channel.  Called also even if invite list
 163 was not modified but SILC_COMMAND_INVITE command was used to invite a user
 164 into a channel.  In this case the invite list is not returned by the
 165 server and 'invite_list' is NULL.  The 'invite_list' is list of
 166 SilcArgumentPayloads.  The first 2 bytes are the number of arguments in
 167 the list and can be parsed with SILC_GET16_MSB macro.  The list can be
 168 parsed with silc_argument_payload_parse function.
 169 </td>
 170 <td width="50%"><small>SilcChannelEntry channel, SilcBuffer invite_list
 171 </td>
 172 </tr>
 173
 174 <tr>
 175 <td><small>SILC_COMMAND_KILL</td>
 176 <td><small>
 177 Called after killing a client.  Returns the client that was killed.
 178 The `client_entry' may be NULL.
 179 </td>
 180 <td width="50%"><small>SilcClientEntry client_entry
 181 </td>
 182 </tr>
 183
 184 <tr>
 185 <td><small>SILC_COMMAND_INFO</td>
 186 <td><small>
 187 Returns information about the server user is connected to.
 188 </td>
 189 <td width="50%"><small>SilcServerEntry server, char *server_name,
 190 char *server_info
 191 </td>
 192 </tr>
 193
 194 <tr>
 195 <td><small>SILC_COMMAND_STATS</td>
 196 <td><small>
 197 Returns network statistics from the server.  The 'stats_buffer' of length of
 198 'buffer_length' bytes includes 32-bit integers one after the other each
 199 representing some statistics.  The integers can be parsed for example with
 200 SILC_GET32_MSB macro.  The integers in the buffer are: starttime, uptime,
 201 local_clients, local_channels, local_serverops, local_routerops, cell_clients,
 202 cell_channels, cell_servers, all_clients, all_channel, all_servers,
 203 all_routers, all_serverops, all_routerops.  All integers are always present.
 204 </td>
 205 <td width="50%"><small>unsigned char *stats_buffer, SilcUInt32 buffer_length
 206 </td>
 207 </tr>
 208
 209 <tr>
 210 <td><small>SILC_COMMAND_PING</td>
 211 <td><small>
 212 Returns reply to earlier ping.  There is no arguments to this reply.
 213 </td>
 214 <td width="50%"><small>none
 215 </td>
 216 </tr>
 217
 218 <tr>
 219 <td><small>SILC_COMMAND_OPER</td>
 220 <td><small>
 221 Returns reply to earlier SILC_COMMAND_OPER command.  There is no arguments
 222 to this reply.
 223 </td>
 224 <td width="50%"><small>none
 225 </td>
 226 </tr>
 227
 228 <tr>
 229 <td><small>SILC_COMMAND_JOIN</td>
 230 <td><small>
 231 Reply received when user joined a channel.  The 'ignored' argument can
 232 be ignored by the application.  The 'topic' and 'hmac_name' may be NULL.
 233 The 'key_payload' is usually ignored by the application.  The 'list_count'
 234 is the number of entries in both 'client_id_list' and 'client_mode_list'.
 235 The 'client_id_list' is a list of clients on the channel and 'client_mode_list'
 236 includes those clients' modes on the channel.  If application likes to
 237 resolve information about the clients on the channel it may call
 238 silc_client_get_clients_by_list function and pass the 'client_id_list' as
 239 argument to it.  The 'client_mode_list' includes 32-bit integers one after
 240 the other and they are in same order as clients in 'client_mode_list'.
 241 If application resolves the information with silc_client_get_clients_by_list
 242 parsing the 'client_mode_list' is not necessary.  The 'founder_key' is the
 243 channel founder's key and may be NULL.  The 'channel_pubkeys' is Argument
 244 List Payload containing Public Key Payloads of all added channel public
 245 keys, it may be NULL.
 246 </td>
 247 <td width="50%"><small>char *channel_name, SilcChannelEntry channel,
 248 SilcUInt32 channel_mode, int ignored, SilcBuffer key_payload, NULL, NULL,
 249 char *topic, char *hmac_name, SilcUInt32 list_count, SilcBuffer client_id_list,
 250 SilcBuffer client_mode_list, SilcPublicKey founder_key,
 251 SilcBuffer channel_pubkeys
 252 </td>
 253 </tr>
 254
 255 <tr>
 256 <td><small>SILC_COMMAND_MOTD</td>
 257 <td><small>
 258 Returns the Message of the Day from the server.  The 'motd' may be NULL.
 259 </td>
 260 <td width="50%"><small>char *motd
 261 </td>
 262 </tr>
 263
 264 <tr>
 265 <td><small>SILC_COMMAND_UMODE</td>
 266 <td><small>
 267 Returns the user mode after changing it.
 268 </td>
 269 <td width="50%"><small>SilcUInt32 user_mode
 270 </td>
 271 </tr>
 272
 273 <tr>
 274 <td><small>SILC_COMMAND_CMODE</td>
 275 <td><small>
 276 Returns channel's mode after changing it.  Optionally may also return
 277 founder's public key when it was set.  It may also return the channel
 278 public key list when the list was altered.  The 'founder_key' and
 279 'channel_pubkeys' arguments may be NULL.  The 'channel_pubkeys' is an
 280 Argument List Payload where each argument includes one Public Key
 281 Payload.
 282 </td>
 283 <td width="50%"><small>SilcChannelEntry channel, SilcUInt32 mode,
 284 SilcPublicKey founder_key, SilcBuffer channel_pubkeys
 285 </td>
 286 </tr>
 287
 288 <tr>
 289 <td><small>SILC_COMMAND_CUMODE</td>
 290 <td><small>
 291 Returns user's mode on channel after changing it.
 292 </td>
 293 <td width="50%"><small>SilcUInt32 mode, SilcChannelEntry channel,
 294 SilcClientEntry target_client
 295 </td>
 296 </tr>
 297
 298 <tr>
 299 <td><small>SILC_COMMAND_KICK</td>
 300 <td><small>
 301 Called after kicking a client.  Returns the client that was kicked from
 302 the 'channel'.  The `client_entry' and 'channel' may be NULL.
 303 </td>
 304 <td width="50%"><small>SilcChannelEntry channel, SilcClientEntry client_entry
 305 </td>
 306 </tr>
 307
 308 <tr>
 309 <td><small>SILC_COMMAND_BAN</td>
 310 <td><small>
 311 Returns channel's ban list.  The 'ban_list' may be NULL.  The construction
 312 of that list is equivalent to invite list.  See description of
 313 SILC_COMMAND_INVITE command reply.
 314 </td>
 315 <td width="50%"><small>SilcChannelEntry channel, SilcBuffer ban_list
 316 </td>
 317 </tr>
 318
 319 <tr>
 320 <td><small>SILC_COMMAND_DETACH</td>
 321 <td><small>
 322 Called after being detached from the SILC network. There is no arguments
 323 to this reply.
 324 </td>
 325 <td width="50%"><small>none
 326 </td>
 327 </tr>
 328
 329 <tr>
 330 <td><small>SILC_COMMAND_WATCH</td>
 331 <td><small>
 332 Called after modifying the watch list in the server.  There is no arguments
 333 to this reply.
 334 </td>
 335 <td width="50%"><small>none
 336 </td>
 337 </tr>
 338
 339 <tr>
 340 <td><small>SILC_COMMAND_SILCOPER</td>
 341 <td><small>
 342 Returns reply to earlier SILC_COMMAND_SILCOPER command.  There is no
 343 arguments to this reply.
 344 </td>
 345 <td width="50%"><small>none
 346 </td>
 347 </tr>
 348
 349 <tr>
 350 <td><small>SILC_COMMAND_LEAVE</td>
 351 <td><small>
 352 Called after leaving the channel.  Note that the `channel' will become
 353 invalid after command_reply client operation returns.
 354 </td>
 355 <td width="50%"><small>SilcChannelEntry channel
 356 </td>
 357 </tr>
 358
 359 <tr>
 360 <td><small>SILC_COMMAND_USERS</td>
 361 <td><small>
 362 Returns list of users in channel.  If application wishes not to parse
 363 the raw lists the channel->user_list hash table is updated before calling
 364 this command reply and application may traverse that table instead of
 365 parssing the raw lists.
 366 </td>
 367 <td width="50%"><small>SilcChannelEntry channel, SilcUInt32 list_count,
 368 SilcBuffer client_id_list, SilcBuffer client_mode_list
 369 </td>
 370 </tr>
 371
 372 <tr>
 373 <td><small>SILC_COMMAND_GETKEY</td>
 374 <td><small>
 375 Returns public key of client or server.  The 'public_key' may be NULL.
 376 The 'entry_type' is used to check what type of pointer the entry' is.  For
 377 SILC_ID_CLIENT SilcClientEntry and for SILC_ID_SERVER SilcServerEntry.
 378 </td>
 379 <td width="50%"><small>SilcIdType entry_type, void *entry,
 380 SilcPublicKey public_key
 381 </td>
 382 </tr>
 383
 384 </table>
 385
 386 <br />&nbsp;<br />
 387 SILC protocol defines some additional commands but command replies to
 388 those commands are not delivered to the application.  Only the command
 389 replies listed above are delivered to application.