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