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 each entry in the list is
 102 SilcChannelPayload.  If the `channel_usermodes' is valid then the table
 103 has as many entries as there are entries in the `channels' list, and the
 104 first entry in the table is the user mode on the first channel in the
 105 `channels' list.  The `channel_usermodes' is the table of the user's mdoes
 106 no the joined channels.  The 'attr' is the Requested Attributes that may
 107 have been returned by the client and it can be parsed by traversing the
 108 SilcDList and using silc_attribute_get_attribute function.  Each entry in
 109 the list is SilcAttribute.
 110 </td>
 111 <td width="50%"><small>SilcClientEntry client_entry, char *nickname,
 112 char *username, char *realname, SilcDList channels, SilcUInt32 usermode,
 113 SilcUInt32 idletime, unsigned char *fingerprint, SilcUInt32 *channel_usermodes,
 114 SilcDList attrs
 115 </td>
 116 </tr>
 117
 118 <tr>
 119 <td><small>SILC_COMMAND_WHOWAS</td>
 120 <td><small>
 121 Returns history information about user. The 'client_entry' and 'realname'
 122 may be NULL.
 123 </td>
 124 <td width="50%"><small>SilcClientEntry client_entry, char *nickname,
 125 char *username, char *realname
 126 </td>
 127 </tr>
 128
 129 <tr>
 130 <td><small>SILC_COMMAND_IDENTIFY</td>
 131 <td><small>
 132 Returns information about user, channel or server.  This is similar to
 133 WHOIS command but does not return so much information and can be used to
 134 get information about channels and servers too.  Application should ignore
 135 this command reply.  The 'name' and 'info' may be NULL.
 136 </td>
 137 <td width="50%"><small>void *entry, char *name, char *info
 138 </td>
 139 </tr>
 140
 141 <tr>
 142 <td><small>SILC_COMMAND_NICK</td>
 143 <td><small>
 144 Returns the new Client ID and new nickname inside the SilcClientEntry.
 145 The `old_client_id' is the old Client ID used by the client before the
 146 nickname was changed.
 147 </td>
 148 <td width="50%"><small>SilcClientEntry local_entry, char *nickname,
 149 const SilcClientID *old_client_id
 150 </td>
 151 </tr>
 152
 153 <tr>
 154 <td><small>SILC_COMMAND_LIST</td>
 155 <td><small>
 156 Returns the list of channel in the SILC network. Each call of command reply
 157 returns one channel. This means that the command reply is called multiple
 158 times to return list of channels.  The 'channel', 'channel_name' and
 159 'channel_topic' may be NULL.  However, the 'channel' and 'channel_name'
 160 are NULL only if there are no channels in the network.  In this case
 161 this reply is called once with all arguments set to NULL.  Application
 162 must be able to handle this situation correctly.
 163 </td>
 164 <td width="50%"><small>SilcChannelEntry channel, char *channel_name,
 165 char *channel_topic, SilcUInt32 user_count
 166 </td>
 167 </tr>
 168
 169 <tr>
 170 <td><small>SILC_COMMAND_TOPIC</td>
 171 <td><small>
 172 Returns the topic of the channel.
 173 </td>
 174 <td width="50%"><small>SilcChannelEntry channel, char *topic
 175 </td>
 176 </tr>
 177
 178 <tr>
 179 <td><small>SILC_COMMAND_INVITE</td>
 180 <td><small>
 181 Returns the invite list of the channel.  Called also even if invite list
 182 was not modified but SILC_COMMAND_INVITE command was used to invite a user
 183 into a channel.  In this case the invite list is not returned by the
 184 server and 'invite_list' is NULL.  The 'invite_list' is list of
 185 SilcArgumentPayloads.  The first 2 bytes are the number of arguments in
 186 the list and can be parsed with SILC_GET16_MSB macro.  The list can be
 187 parsed with silc_argument_payload_parse function.
 188 </td>
 189 <td width="50%"><small>SilcChannelEntry channel, SilcBuffer invite_list
 190 </td>
 191 </tr>
 192
 193 <tr>
 194 <td><small>SILC_COMMAND_KILL</td>
 195 <td><small>
 196 Called after killing a client.  Returns the client that was killed.
 197 The `client_entry' may be NULL.  The `client_entry' will become invalid
 198 after the command reply has returned from application.
 199 </td>
 200 <td width="50%"><small>SilcClientEntry client_entry
 201 </td>
 202 </tr>
 203
 204 <tr>
 205 <td><small>SILC_COMMAND_INFO</td>
 206 <td><small>
 207 Returns information about the server user is connected to.
 208 </td>
 209 <td width="50%"><small>SilcServerEntry server, char *server_name,
 210 char *server_info
 211 </td>
 212 </tr>
 213
 214 <tr>
 215 <td><small>SILC_COMMAND_STATS</td>
 216 <td><small>
 217 Returns network statistics from the server.  The `stats' structure contains
 218 the statistics returned by the server.
 219 </td>
 220 <td width="50%"><small>SilcClientStats *stats
 221 </td>
 222 </tr>
 223
 224 <tr>
 225 <td><small>SILC_COMMAND_PING</td>
 226 <td><small>
 227 Returns reply to earlier ping.  There is no arguments to this reply.
 228 </td>
 229 <td width="50%"><small>none
 230 </td>
 231 </tr>
 232
 233 <tr>
 234 <td><small>SILC_COMMAND_OPER</td>
 235 <td><small>
 236 Returns reply to earlier SILC_COMMAND_OPER command.  There is no arguments
 237 to this reply.
 238 </td>
 239 <td width="50%"><small>none
 240 </td>
 241 </tr>
 242
 243 <tr>
 244 <td><small>SILC_COMMAND_JOIN</td>
 245 <td><small>
 246 Reply received when user joined a channel.  The 'ignored' argument can
 247 be ignored by the application.  The 'topic' and 'hmac_name' may be NULL.
 248 The 'key_payload' is usually ignored by the application.  The 'list_count'
 249 is the number of entries in both 'client_id_list' and 'client_mode_list'.
 250 The 'client_id_list' is a list of clients on the channel and 'client_mode_list'
 251 includes those clients' modes on the channel.  If application likes to
 252 resolve information about the clients on the channel it may call
 253 silc_client_get_clients_by_list function and pass the 'client_id_list' as
 254 argument to it.  The 'client_mode_list' includes 32-bit integers one after
 255 the other and they are in same order as clients in 'client_mode_list'.
 256 If application resolves the information with silc_client_get_clients_by_list
 257 parsing the 'client_mode_list' is not necessary.  The 'founder_key' is the
 258 channel founder's key and may be NULL.  The 'channel_pubkeys' is Argument
 259 List Payload containing Public Key Payloads of all added channel public
 260 keys, it may be NULL.
 261 </td>
 262 <td width="50%"><small>char *channel_name, SilcChannelEntry channel,
 263 SilcUInt32 channel_mode, int ignored, SilcBuffer key_payload, NULL, NULL,
 264 char *topic, char *hmac_name, SilcUInt32 list_count, SilcBuffer client_id_list,
 265 SilcBuffer client_mode_list, SilcPublicKey founder_key,
 266 SilcBuffer channel_pubkeys, SilcUint32 user_limit
 267 </td>
 268 </tr>
 269
 270 <tr>
 271 <td><small>SILC_COMMAND_MOTD</td>
 272 <td><small>
 273 Returns the Message of the Day from the server.  The 'motd' may be NULL.
 274 </td>
 275 <td width="50%"><small>char *motd
 276 </td>
 277 </tr>
 278
 279 <tr>
 280 <td><small>SILC_COMMAND_UMODE</td>
 281 <td><small>
 282 Returns the user mode after changing it.
 283 </td>
 284 <td width="50%"><small>SilcUInt32 user_mode
 285 </td>
 286 </tr>
 287
 288 <tr>
 289 <td><small>SILC_COMMAND_CMODE</td>
 290 <td><small>
 291 Returns channel's mode after changing it.  Optionally may also return
 292 founder's public key when it was set.  It may also return the channel
 293 public key list when the list was altered.  The 'founder_key' and
 294 'channel_pubkeys' arguments may be NULL.  The 'channel_pubkeys' is an
 295 Argument List Payload where each argument includes one Public Key
 296 Payload.
 297 </td>
 298 <td width="50%"><small>SilcChannelEntry channel, SilcUInt32 mode,
 299 SilcPublicKey founder_key, SilcBuffer channel_pubkeys,
 300 SilcUint32 user_limit
 301 </td>
 302 </tr>
 303
 304 <tr>
 305 <td><small>SILC_COMMAND_CUMODE</td>
 306 <td><small>
 307 Returns user's mode on channel after changing it.
 308 </td>
 309 <td width="50%"><small>SilcUInt32 mode, SilcChannelEntry channel,
 310 SilcClientEntry target_client
 311 </td>
 312 </tr>
 313
 314 <tr>
 315 <td><small>SILC_COMMAND_KICK</td>
 316 <td><small>
 317 Called after kicking a client.  Returns the client that was kicked from
 318 the 'channel'.
 319 </td>
 320 <td width="50%"><small>SilcChannelEntry channel, SilcClientEntry client_entry
 321 </td>
 322 </tr>
 323
 324 <tr>
 325 <td><small>SILC_COMMAND_BAN</td>
 326 <td><small>
 327 Returns channel's ban list.  The 'ban_list' may be NULL.  The construction
 328 of that list is equivalent to invite list.  See description of
 329 SILC_COMMAND_INVITE command reply.
 330 </td>
 331 <td width="50%"><small>SilcChannelEntry channel, SilcBuffer ban_list
 332 </td>
 333 </tr>
 334
 335 <tr>
 336 <td><small>SILC_COMMAND_DETACH</td>
 337 <td><small>
 338 Called after being detached from the SILC network. There is no arguments
 339 to this reply.
 340 </td>
 341 <td width="50%"><small>none
 342 </td>
 343 </tr>
 344
 345 <tr>
 346 <td><small>SILC_COMMAND_WATCH</td>
 347 <td><small>
 348 Called after modifying the watch list in the server.  There is no arguments
 349 to this reply.
 350 </td>
 351 <td width="50%"><small>none
 352 </td>
 353 </tr>
 354
 355 <tr>
 356 <td><small>SILC_COMMAND_SILCOPER</td>
 357 <td><small>
 358 Returns reply to earlier SILC_COMMAND_SILCOPER command.  There is no
 359 arguments to this reply.
 360 </td>
 361 <td width="50%"><small>none
 362 </td>
 363 </tr>
 364
 365 <tr>
 366 <td><small>SILC_COMMAND_LEAVE</td>
 367 <td><small>
 368 Called after leaving the channel.  Note that the `channel' will become
 369 invalid after command_reply client operation returns.
 370 </td>
 371 <td width="50%"><small>SilcChannelEntry channel
 372 </td>
 373 </tr>
 374
 375 <tr>
 376 <td><small>SILC_COMMAND_USERS</td>
 377 <td><small>
 378 Returns list of users in channel.  The `user_list' may be traversed with
 379 silc_hash_table_get function.  Each entry in the `user_list' is
 380 SilcChannelUser structure, which contains the SilcClientEntry and the
 381 client's mode on the channel.
 382 </td>
 383 <td width="50%"><small>SilcChannelEntry channel, SilcHashTableList user_list
 384 </td>
 385 </tr>
 386
 387 <tr>
 388 <td><small>SILC_COMMAND_GETKEY</td>
 389 <td><small>
 390 Returns public key of client or server.  The 'public_key' may be NULL.
 391 The 'entry_type' is used to check what type of pointer the entry' is.  For
 392 SILC_ID_CLIENT SilcClientEntry and for SILC_ID_SERVER SilcServerEntry.
 393 </td>
 394 <td width="50%"><small>SilcIdType entry_type, void *entry,
 395 SilcPublicKey public_key
 396 </td>
 397 </tr>
 398
 399 <tr>
 400 <td><small>SILC_COMMAND_SERVICE</td>
 401 <td><small>
 402 Returns the service list in the server, or information on the accepted
 403 and authenticated service.  The 'service_list' maybe NULL if server does
 404 not support any services.  It is NULL also when 'name' is not NULL.  The
 405 'service_list' is a comma separated list of services the server supports.
 406 The 'name' MAY be NULL also.  The 'name' is the requested service, and it is
 407 non-NULL only if server accepted and authenticated client's request.
 408 </td>
 409 <td width="50%"><small>const char *server_list, const char *service_name
 410 </td>
 411 </tr>
 412
 413 </table>
 414
 415 <br />&nbsp;<br />
 416 SILC protocol defines some additional commands but command replies to
 417 those commands are not delivered to the application.  Only the command
 418 replies listed above are delivered to application.