lib/doc/silcstatus_args.html

   1 <big><b>SilcStatus Arguments</b></big>
   2
   3 <br />&nbsp;<br />
   4 The <a href="silcstatus-SilcStatus.html">SilcStatus</a> is used to indicate
   5 a status (usually error status) of command execution and command reply
   6 status.  It is also used to deliver disconnection status when server
   7 disconnects client from the server.  For application it is mainly important
   8 in case of `command_reply' client operation, where the SilcStatus indicates
   9 the error status of the command that was executed.  If error occurred the
  10 arguments returned by the `command_reply' are then dependent of the SilcStatus
  11 type instead of the <a href="command_reply_args.html">SilcCommand
  12 arguments</a>.
  13
  14 <br />&nbsp;<br />
  15 This documents describes how the application should interpret the SilcStatus
  16 type in the `command_reply' client operation to be able to handle all
  17 error conditions properly.  Any status type can be returned for any
  18 SilcCommand.  For this reason application should be able to handle any
  19 error with any command.
  20
  21
  22 <br />&nbsp;<br />&nbsp;<br />
  23 <b>Error Status In command_reply Client Operation</b>
  24
  25 <br />&nbsp;<br />
  26 When error occurs in execution of a command the `command_reply' client
  27 operation is called with error status.  In this case the 'success'
  28 argument of the client operation is set to FALSE, to indicate that command
  29 execution failed, and the 'status' argument indicates the error.
  30 If the 'status' argument is SILC_STATUS_OK then error did not occur and the
  31 arguments are as described in <a href="command_reply_args.html">SilcCommand
  32 arguments</a>.
  33
  34 <br />&nbsp;<br />
  35 Application should handle the error status arguments by the SilcStatus
  36 type for example in a <tt>switch</tt> statement.  The SilcStatus values
  37 are defined in lib/silccore/silcstatus.h header file.  A short example.
  38
  39 <br />&nbsp;<br />
  40 <tt>
  41 &nbsp;&nbsp;switch(status)<br />
  42 &nbsp;&nbsp;&nbsp;&nbsp;{<br />
  43 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_STATUS_ERR_NO_SUCH_NICK:<br />
  44 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  45 &nbsp;&nbsp;&nbsp;&nbsp;nick = va_arg(va, char *);<br />
  46 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  47 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  48 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_STATUS_ERR_NO_SUCH_CHANNEL:<br />
  49 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  50 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  51 &nbsp;&nbsp;&nbsp;&nbsp;case SILC_STATUS_ERR_NO_SUCH_SERVER:<br />
  52 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  53 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  54 &nbsp;&nbsp;&nbsp;&nbsp;...<br />
  55 &nbsp;&nbsp;&nbsp;&nbsp;default:<br />
  56 &nbsp;&nbsp;&nbsp;&nbsp;break;<br />
  57 &nbsp;&nbsp;&nbsp;&nbsp;}
  58 </tt>
  59
  60
  61 <br />&nbsp;<br />&nbsp;<br />
  62 <b>Arguments</b>
  63
  64 <br />&nbsp;<br />
  65 The following table describes all status values and arguments that the client
  66 library sends in the 'command_reply' client operation to the application
  67 in case of error.  All arguments listed below are usually valid when
  68 returned by the library.  However applicationn must be able to handle that
  69 any of those arguments may be NULL.
  70
  71 <br />&nbsp;<br />
  72 The 'command_reply' arguments in case of error are 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="40%"><small>Error Arguments</td>
  81 </tr>
  82
  83 <tr>
  84 <td><small>SILC_STATUS_OK</td>
  85 <td><small>
  86 No error.
  87 </td>
  88 <td width="40%"><small>N/A
  89 </td>
  90 </tr>
  91
  92 <tr>
  93 <td><small>SILC_STATUS_ERR_NO_SUCH_NICK</td>
  94 <td><small>
  95 Requested nickname does not exist.  Argument is the unknown name.
  96 </td>
  97 <td width="40%"><small>const char *nickname
  98 </td>
  99 </tr>
 100
 101 <tr>
 102 <td><small>SILC_STATUS_ERR_NO_SUCH_CHANNEL</td>
 103 <td><small>
 104 The requested channel does not exist.  Argument is the unknown name.
 105 </td>
 106 <td width="40%"><small>const char *channel_name
 107 </td>
 108 </tr>
 109
 110 <tr>
 111 <td><small>SILC_STATUS_ERR_NO_SUCH_SERVER</td>
 112 <td><small>
 113 The requested server does not exist.  Argument is the unknown name.
 114 </td>
 115 <td width="40%"><small>const char *server_name
 116 </td>
 117 </tr>
 118
 119 <tr>
 120 <td><small>SILC_STATUS_ERR_NO_RECIPIENT</td>
 121 <td><small>
 122 Command required recipient but none was provided.  No arguments returned.
 123 <td width="40%"><small>N/A
 124 </td>
 125 </tr>
 126
 127 <tr>
 128 <td><small>SILC_STATUS_ERR_UNKNOWN_COMMAND</td>
 129 <td><small>
 130 Command sent to server is unknown or unsupported by the server.  No
 131 arguments returned.
 132 </td>
 133 <td width="40%"><small>N/A
 134 </td>
 135 </tr>
 136
 137 <tr>
 138 <td><small>SILC_STATUS_ERR_WILDCARDS</td>
 139 <td><small>
 140 Wildcards were provided by they were not permitted.  No arguments returned.
 141 </td>
 142 <td width="40%"><small>N/A
 143 </td>
 144 </tr>
 145
 146 <tr>
 147 <td><small>SILC_STATUS_ERR_NO_CLIENT_ID</td>
 148 <td><small>
 149 Client ID was expected as command parameter but was not found.  No
 150 arguments returned.
 151 </td>
 152 <td width="40%"><small>N/A
 153 </td>
 154 </tr>
 155
 156 <tr>
 157 <td><small>SILC_STATUS_ERR_NO_CHANNEL_ID</td>
 158 <td><small>
 159 Channel ID was expected as command parameter but was not found.  No
 160 arguments returned.
 161 </td>
 162 <td width="40%"><small>N/A
 163 </td>
 164 </tr>
 165
 166 <tr>
 167 <td><small>SILC_STATUS_ERR_NO_SERVER_ID</td>
 168 <td><small>
 169 Server ID was expected as command parameter but was not found.  No
 170 arguments returned.
 171 </td>
 172 <td width="40%"><small>N/A
 173 </td>
 174 </tr>
 175
 176 <tr>
 177 <td><small>SILC_STATUS_ERR_BAD_CLIENT_ID</td>
 178 <td><small>
 179 Client ID provided was malformed.  Returns the malformed ID.
 180 </td>
 181 <td width="40%"><small>const SilcClientID *client_id
 182 </td>
 183 </tr>
 184
 185 <tr>
 186 <td><small>SILC_STATUS_ERR_BAD_CHANNEL_ID</td>
 187 <td><small>
 188 Channel ID provided was malformed.  Returns the malformed ID.
 189 </td>
 190 <td width="40%"><small>const SilcChannelID *channel_id
 191 </td>
 192 </tr>
 193
 194 <tr>
 195 <td><small>SILC_STATUS_ERR_BAD_SERVER_ID</td>
 196 <td><small>
 197 Server ID provided was malformed.  Returns the malformed ID.
 198 </td>
 199 <td width="40%"><small>const SilcServerID *server_id
 200 </td>
 201 </tr>
 202
 203 <tr>
 204 <td><small>SILC_STATUS_ERR_NO_SUCH_CLIENT_ID</td>
 205 <td><small>
 206 Client ID provided does not exist.  The unknown ID is returned.
 207 </td>
 208 <td width="40%"><small>const SilcClientID *client_id
 209 </td>
 210 </tr>
 211
 212 <tr>
 213 <td><small>SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID</td>
 214 <td><small>
 215 Channel ID provided does not exist.  The unknown ID is returned.
 216 </td>
 217 <td width="40%"><small>const SilcChannelID *channel_id
 218 </td>
 219 </tr>
 220
 221 <tr>
 222 <td><small>SILC_STATUS_ERR_NO_SUCH_SERVER_ID</td>
 223 <td><small>
 224 Server ID provided does not exist.  The unknown ID is returned.
 225 </td>
 226 <td width="40%"><small>const SilcServerID *server_id
 227 </td>
 228 </tr>
 229
 230 <tr>
 231 <td><small>SILC_STATUS_ERR_NOT_ON_CHANNEL</td>
 232 <td><small>
 233 The command required for you to be on channel but you were not.
 234 The channel ID is returned.
 235 </td>
 236 <td width="40%"><small>const SilcChannelID *channel_id
 237 </td>
 238 </tr>
 239
 240 <tr>
 241 <td><small>SILC_STATUS_ERR_USER_NOT_ON_CHANNEL</td>
 242 <td><small>
 243 The requested target client is not on requested channel.  Returns the
 244 target client ID and channel ID.
 245 </td>
 246 <td width="40%"><small>const SilcClientID *client_id,
 247 const SilcChannelID *channel_id
 248 </td>
 249 </tr>
 250
 251 <tr>
 252 <td><small>SILC_STATUS_ERR_USER_ON_CHANNEL</td>
 253 <td><small>
 254 User were invited on channel they already are on.  Returns the
 255 target client ID and channel ID.
 256 </td>
 257 <td width="40%"><small>const SilcClientID *client_id,
 258 const SilcChannelID *channel_id
 259 </td>
 260 </tr>
 261
 262 <tr>
 263 <td><small>SILC_STATUS_ERR_NOT_REGISTERED</td>
 264 <td><small>
 265 User executed command that requires the client to be registered on the
 266 server before it may be executed.  No arguments returned.
 267 </td>
 268 <td width="40%"><small>N/A
 269 </td>
 270 </tr>
 271
 272 <tr>
 273 <td><small>SILC_STATUS_ERR_NOT_ENOUGH_PARAMS</td>
 274 <td><small>
 275 Command required more parameters than provided.  No arguments returned.
 276 </td>
 277 <td width="40%"><small>N/A
 278 </td>
 279 </tr>
 280
 281 <tr>
 282 <td><small>SILC_STATUS_ERR_TOO_MANY_PARAMS</td>
 283 <td><small>
 284 Too many parameters provided for the command.  No arguments returned.
 285 </td>
 286 <td width="40%"><small>N/A
 287 </td>
 288 </tr>
 289
 290 <tr>
 291 <td><small>SILC_STATUS_ERR_PERM_DENIED</td>
 292 <td><small>
 293 Generic permission denied error status, to indicat disallowed access.
 294 No arguments returned.
 295 </td>
 296 <td width="40%"><small>N/A
 297 </td>
 298 </tr>
 299
 300 <tr>
 301 <td><small>SILC_STATUS_ERR_BAD_PASSWORD</td>
 302 <td><small>
 303 Password provided for channel were not accepted.  Returns the channel ID.
 304 </td>
 305 <td width="40%"><small>const SilcChannelID *channel_id
 306 </td>
 307 </tr>
 308
 309 <tr>
 310 <td><small>SILC_STATUS_ERR_CHANNEL_IS_FULL</td>
 311 <td><small>
 312 The channel is full and client cannot join the channel.  Returns the
 313 channel ID.
 314 </td>
 315 <td width="40%"><small>const SilcChannelID *channel_id
 316 </td>
 317 </tr>
 318
 319 <tr>
 320 <td><small>SILC_STATUS_ERR_NOT_INVITED</td>
 321 <td><small>
 322 The channel is invite only channel and client has not been invited.
 323 Returns the channel ID.
 324 </td>
 325 <td width="40%"><small>const SilcChannelID *channel_id
 326 </td>
 327 </tr>
 328
 329 <tr>
 330 <td><small>SILC_STATUS_ERR_BANNED_FROM_CHANNEL</td>
 331 <td><small>
 332 The client has been banned from the channel.  Returns the channel ID.
 333 </td>
 334 <td width="40%"><small>const SilcChannelID *channel_id
 335 </td>
 336 </tr>
 337
 338 <tr>
 339 <td><small>SILC_STATUS_ERR_UNKNOWN_MODE</td>
 340 <td><small>
 341 Mode provided by the client was unknown to or unsupported by the server.
 342 No arguments returned.
 343 </td>
 344 <td width="40%"><small>N/A
 345 </td>
 346 </tr>
 347
 348 <tr>
 349 <td><small>SILC_STATUS_ERR_NOT_YOU</td>
 350 <td><small>
 351 User tried to change someone else's mode which is not allowed.
 352 No arguments returned.
 353 </td>
 354 <td width="40%"><small>N/A
 355 </td>
 356 </tr>
 357
 358 <tr>
 359 <td><small>SILC_STATUS_ERR_NO_CHANNEL_PRIV</td>
 360 <td><small>
 361 Command may be executed only by channel operator.  The next argument is
 362 the channel ID.
 363 </td>
 364 <td width="40%"><small>const SilcChannelID *channel_id
 365 </td>
 366 </tr>
 367
 368 <tr>
 369 <td><small>SILC_STATUS_ERR_NO_CHANNEL_FOPRIV</td>
 370 <td><small>
 371 Command may be executed only by channel founder.  The next argument is
 372 the channel ID.
 373 </td>
 374 <td width="40%"><small>const SilcChannelID *channel_id
 375 </td>
 376 </tr>
 377
 378 <tr>
 379 <td><small>SILC_STATUS_ERR_NO_SERVER_PRIV</td>
 380 <td><small>
 381 Command may be executed only by server operator.  No arguments returned.
 382 </td>
 383 <td width="40%"><small>N/A
 384 </td>
 385 </tr>
 386
 387 <tr>
 388 <td><small>SILC_STATUS_ERR_NO_ROUTER_PRIV</td>
 389 <td><small>
 390 Command may be executed only by router (SILC) operator.  No arguments returned.
 391 </td>
 392 <td width="40%"><small>N/A
 393 </td>
 394 </tr>
 395
 396 <tr>
 397 <td><small>SILC_STATUS_ERR_BAD_NICKNAME</td>
 398 <td><small>
 399 Nickname requested contained illegal characters or was malformed.  No
 400 arguments returned.
 401 </td>
 402 <td width="40%"><small>N/A
 403 </td>
 404 </tr>
 405
 406 <tr>
 407 <td><small>SILC_STATUS_ERR_BAD_CHANNEL</td>
 408 <td><small>
 409 Channel name requested contained illegal characters or was malformed.  No
 410 arguments returned.
 411 </td>
 412 <td width="40%"><small>N/A
 413 </td>
 414 </tr>
 415
 416 <tr>
 417 <td><small>SILC_STATUS_ERR_AUTH_FAILED</td>
 418 <td><small>
 419 The authentication data (passphrase or digital signature) sent as argument
 420 was wrong and thus authentication failed.  No arguments returned.
 421 </td>
 422 <td width="40%"><small>N/A
 423 </td>
 424 </tr>
 425
 426 <tr>
 427 <td><small>SILC_STATUS_ERR_UNKNOWN_ALGORITHM</td>
 428 <td><small>
 429 The server does not support requested algorithm.  Returns the unknown
 430 algorithm.
 431 </td>
 432 <td width="40%"><small>const char *alg_name
 433 </td>
 434 </tr>
 435
 436 <tr>
 437 <td><small>SILC_STATUS_ERR_RESOURCE_LIMIT</td>
 438 <td><small>
 439 Server cannot or will not accept the action due to resource limitations.
 440 No arguments returned.
 441 </td>
 442 <td width="40%"><small>N/A
 443 </td>
 444 </tr>
 445
 446 <tr>
 447 <td><small>SILC_STATUS_ERR_NO_SUCH_SERVICE</td>
 448 <td><small>
 449 Requestes service identifier is unknown.  Returns the unknown service
 450 identifier.
 451 </td>
 452 <td width="40%"><small>const char *service_identifier
 453 </td>
 454 </tr>
 455
 456 <tr>
 457 <td><small>SILC_STATUS_ERR_TIMEDOUT</td>
 458 <td><small>
 459 Operation (command execution) or service request timed out, and thus was
 460 not processed.  This usually happens due to network failure between servers
 461 and routers in the network.  No arguments returned.
 462 </td>
 463 <td width="40%"><small>N/A
 464 </td>
 465 </tr>
 466 <tr>
 467
 468 <td><small>SILC_STATUS_ERR_UNSUPPORTED_PUBLIC_KEY</td>
 469 <td><small>
 470 The public key or certificate type is not supported in ths implementation.
 471 No arguments returned.
 472 </td>
 473 <td width="40%"><small>N/A
 474 </td>
 475 </tr>
 476
 477 <td><small>SILC_STATUS_ERR_OPERATION_ALLOWED</td>
 478 <td><small>
 479 A operation, for example a command, is not allowed or it's execution is
 480 not allowed.  No arguments returned.
 481 </td>
 482 <td width="40%"><small>N/A
 483 </td>
 484 </tr>
 485
 486 </table>
 487
 488 <br />&nbsp;<br />
 489 SILC protocol defines some additional status types but those status
 490 types are not returned in `command_reply' client operation.  Only
 491 the status types listed above are delivered to application.