lib/silccore/silccommand.h

   1 /*
   2
   3   silccommand.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2001 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19 */
  20
  21 /****h* silccore/SilcCommandAPI
  22  *
  23  * DESCRIPTION
  24  *
  25  * Implementation of the Command Payload. The Command Payload is used to
  26  * send commands and also command replies usually between client and
  27  * server.
  28  *
  29  ***/
  30
  31 #ifndef SILCCOMMAND_H
  32 #define SILCCOMMAND_H
  33
  34 /****f* silccore/SilcCommandAPI/SilcCommandCb
  35  *
  36  * SYNOPSIS
  37  *
  38  *    typedef void (*SilcCommandCb)(void *context, void *context2);
  39  *
  40  * DESCRIPTION
  41  *
  42  *    Command function callback. The actual command function pointer.
  43  *    This is generic command callback that the application may choose to
  44  *    use with its command routines.  However, none of the generic
  45  *    routines depend on this callback so application may freely define
  46  *    their own command callback if desired.
  47  *
  48  ***/
  49 typedef void (*SilcCommandCb)(void *context, void *context2);
  50
  51 /****s* silccore/SilcCommandAPI/SilcCommandPayload
  52  *
  53  * NAME
  54  *
  55  *    typedef struct SilcCommandPayloadStruct *SilcCommandPayload;
  56  *
  57  * DESCRIPTION
  58  *
  59  *    This context is the actual Command Payload and is allocated
  60  *    by silc_command_payload_parse and given as argument usually to
  61  *    all silc_command_payload_* functions.  It is freed by the
  62  *    silc_command_payload_free function.
  63  *
  64  ***/
  65 typedef struct SilcCommandPayloadStruct *SilcCommandPayload;
  66
  67 /****d* silccore/SilcCommandAPI/SilcCommandFlags
  68  *
  69  * NAME
  70  *
  71  *    typedef enum { ... } SilcCommandFlags;
  72  *
  73  * DESCRIPTION
  74  *
  75  *    Command flags that set how the commands behave on different
  76  *    situations. These can be OR'es together to set multiple flags.
  77  *    The application is resoponsible of implementing the behaviour
  78  *    of these flags. These are here just to define generic flags.
  79  *    The server usually makes use of these flags.
  80  *
  81  * SOURCE
  82  */
  83 typedef enum {
  84   SILC_CF_NONE           = 0,
  85
  86   /* Command may only be used once per (about) 2 seconds. Bursts up
  87      to 5 commands are allowed though. */
  88   SILC_CF_LAG            = (1L << 1),
  89
  90   /* Command may only be used once per (about) 2 seconds. No bursts
  91      are allowed at all. */
  92   SILC_CF_LAG_STRICT     = (1L << 2),
  93
  94   /* Command is available for registered connections (connections
  95      whose ID has been created. */
  96   SILC_CF_REG            = (1L << 3),
  97
  98   /* Command is available only for server operators */
  99   SILC_CF_OPER           = (1L << 4),
 100
 101   /* Command is available only for SILC (router) operators. If this
 102      is set SILC_CF_OPER is not necessary to be set. */
 103   SILC_CF_SILC_OPER      = (1L << 5),
 104
 105 } SilcCommandFlag;
 106 /***/
 107
 108 /****d* silccore/SilcCommandAPI/SilcCommand
 109  *
 110  * NAME
 111  *
 112  *    typedef unsigned char SilcCommand;
 113  *
 114  * DESCRIPTION
 115  *
 116  *    The SilcCommand type definition and the commands. The commands
 117  *    listed here are the official SILC Commands and they have client
 118  *    and server counterparts.
 119  *
 120  * SOURCE
 121  */
 122 typedef unsigned char SilcCommand;
 123
 124 /* All SILC commands. These are commands that have client and server
 125    counterparts. */
 126 #define SILC_COMMAND_NONE               0
 127 #define SILC_COMMAND_WHOIS              1
 128 #define SILC_COMMAND_WHOWAS             2
 129 #define SILC_COMMAND_IDENTIFY           3
 130 #define SILC_COMMAND_NICK               4
 131 #define SILC_COMMAND_LIST               5
 132 #define SILC_COMMAND_TOPIC              6
 133 #define SILC_COMMAND_INVITE             7
 134 #define SILC_COMMAND_QUIT               8
 135 #define SILC_COMMAND_KILL               9
 136 #define SILC_COMMAND_INFO               10
 137 #define SILC_COMMAND_CONNECT            11
 138 #define SILC_COMMAND_PING               12
 139 #define SILC_COMMAND_OPER               13
 140 #define SILC_COMMAND_JOIN               14
 141 #define SILC_COMMAND_MOTD               15
 142 #define SILC_COMMAND_UMODE              16
 143 #define SILC_COMMAND_CMODE              17
 144 #define SILC_COMMAND_CUMODE             18
 145 #define SILC_COMMAND_KICK               19
 146 #define SILC_COMMAND_BAN                20
 147 #define SILC_COMMAND_CLOSE              21
 148 #define SILC_COMMAND_SHUTDOWN           22
 149 #define SILC_COMMAND_SILCOPER           23
 150 #define SILC_COMMAND_LEAVE              24
 151 #define SILC_COMMAND_USERS              25
 152 #define SILC_COMMAND_GETKEY             26
 153
 154 /* Reserved */
 155 #define SILC_COMMAND_RESERVED           255
 156 /***/
 157
 158 /****d* silccore/SilcCommandAPI/SilcCommandStatus
 159  *
 160  * NAME
 161  *
 162  *    typedef uint16 SilcCommandStatus;
 163  *
 164  * DESCRIPTION
 165  *
 166  *    The SilcCommandStatus type definition and the status defines.
 167  *    The server returns a status in each Command Payload indicating
 168  *    the status of the command.
 169  *
 170  * SOURCE
 171  */
 172 typedef uint16 SilcCommandStatus;
 173
 174 /* Command Status messages */
 175 #define SILC_STATUS_OK                      0
 176 #define SILC_STATUS_LIST_START              1
 177 #define SILC_STATUS_LIST_ITEM               2
 178 #define SILC_STATUS_LIST_END                3
 179 #define SILC_STATUS_ERR_NO_SUCH_NICK        10
 180 #define SILC_STATUS_ERR_NO_SUCH_CHANNEL     11
 181 #define SILC_STATUS_ERR_NO_SUCH_SERVER      12
 182 #define SILC_STATUS_ERR_TOO_MANY_TARGETS    13
 183 #define SILC_STATUS_ERR_NO_RECIPIENT        14
 184 #define SILC_STATUS_ERR_UNKNOWN_COMMAND     15
 185 #define SILC_STATUS_ERR_WILDCARDS           16
 186 #define SILC_STATUS_ERR_NO_CLIENT_ID        17
 187 #define SILC_STATUS_ERR_NO_CHANNEL_ID       18
 188 #define SILC_STATUS_ERR_NO_SERVER_ID        19
 189 #define SILC_STATUS_ERR_BAD_CLIENT_ID       20
 190 #define SILC_STATUS_ERR_BAD_CHANNEL_ID      21
 191 #define SILC_STATUS_ERR_NO_SUCH_CLIENT_ID   22
 192 #define SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID  23
 193 #define SILC_STATUS_ERR_NICKNAME_IN_USE     24
 194 #define SILC_STATUS_ERR_NOT_ON_CHANNEL      25
 195 #define SILC_STATUS_ERR_USER_NOT_ON_CHANNEL 26
 196 #define SILC_STATUS_ERR_USER_ON_CHANNEL     27
 197 #define SILC_STATUS_ERR_NOT_REGISTERED      28
 198 #define SILC_STATUS_ERR_NOT_ENOUGH_PARAMS   29
 199 #define SILC_STATUS_ERR_TOO_MANY_PARAMS     30
 200 #define SILC_STATUS_ERR_PERM_DENIED         31
 201 #define SILC_STATUS_ERR_BANNED_FROM_SERVER  32
 202 #define SILC_STATUS_ERR_BAD_PASSWORD        33
 203 #define SILC_STATUS_ERR_CHANNEL_IS_FULL     34
 204 #define SILC_STATUS_ERR_NOT_INVITED         35
 205 #define SILC_STATUS_ERR_BANNED_FROM_CHANNEL 36
 206 #define SILC_STATUS_ERR_UNKNOWN_MODE        37
 207 #define SILC_STATUS_ERR_NOT_YOU             38
 208 #define SILC_STATUS_ERR_NO_CHANNEL_PRIV     39
 209 #define SILC_STATUS_ERR_NO_CHANNEL_FOPRIV   40
 210 #define SILC_STATUS_ERR_NO_SERVER_PRIV      41
 211 #define SILC_STATUS_ERR_NO_ROUTER_PRIV      42
 212 #define SILC_STATUS_ERR_BAD_NICKNAME        43
 213 #define SILC_STATUS_ERR_BAD_CHANNEL         44
 214 #define SILC_STATUS_ERR_AUTH_FAILED         45
 215 #define SILC_STATUS_ERR_UNKNOWN_ALGORITHM   46
 216 #define SILC_STATUS_ERR_NO_SUCH_SERVER_ID   47
 217 /***/
 218
 219 /* Prototypes */
 220
 221 /****f* silccore/SilcCommandAPI/silc_command_payload_parse
 222  *
 223  * SYNOPSIS
 224  *
 225  *    SilcCommandPayload silc_command_payload_parse(SilcBuffer buffer);
 226  *
 227  * DESCRIPTION
 228  *
 229  *    Parses command payload returning new command payload structure. The
 230  *    `buffer' is the raw payload.
 231  *
 232  ***/
 233 SilcCommandPayload silc_command_payload_parse(SilcBuffer buffer);
 234
 235 /****f* silccore/SilcCommandAPI/silc_command_payload_encode
 236  *
 237  * SYNOPSIS
 238  *
 239  *    SilcBuffer silc_command_payload_encode(SilcCommand cmd,
 240  *                                           uint32 argc,
 241  *                                           unsigned char **argv,
 242  *                                           uint32 *argv_lens,
 243  *                                           uint32 *argv_types,
 244  *                                           uint16 ident);
 245  *
 246  * DESCRIPTION
 247  *
 248  *     Encodes Command Payload returning it to SilcBuffer.
 249  *
 250  ***/
 251 SilcBuffer silc_command_payload_encode(SilcCommand cmd,
 252                                        uint32 argc,
 253                                        unsigned char **argv,
 254                                        uint32 *argv_lens,
 255                                        uint32 *argv_types,
 256                                        uint16 ident);
 257
 258 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_payload
 259  *
 260  * SYNOPSIS
 261  *
 262  *    SilcBuffer
 263  *    silc_command_payload_encode_payload(SilcCommandPayload payload);
 264  *
 265  * DESCRIPTION
 266  *
 267  *    Same as silc_command_payload_encode but encodes the buffer from
 268  *    SilcCommandPayload structure instead of raw data.
 269  *
 270  ***/
 271 SilcBuffer silc_command_payload_encode_payload(SilcCommandPayload payload);
 272
 273 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_va
 274  *
 275  * SYNOPSIS
 276  *
 277  *    SilcBuffer silc_command_payload_encode_va(SilcCommand cmd,
 278  *                                              uint16 ident,
 279  *                                              uint32 argc, ...);
 280  *
 281  * DESCRIPTION
 282  *
 283  *    Encodes Command payload with variable argument list. The arguments
 284  *    must be: uint32, unsigned char *, unsigned int, ... One
 285  *    {uint32, unsigned char * and unsigned int} forms one argument,
 286  *    thus `argc' in case when sending one {uint32, unsigned char *
 287  *    and uint32} equals one (1) and when sending two of those it
 288  *    equals two (2), and so on. This has to be preserved or bad things
 289  *    will happen. The variable arguments is: {type, data, data_len}.
 290  *
 291  ***/
 292 SilcBuffer silc_command_payload_encode_va(SilcCommand cmd,
 293                                           uint16 ident,
 294                                           uint32 argc, ...);
 295
 296 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_vap
 297  *
 298  * SYNOPSIS
 299  *
 300  *    SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd,
 301  *                                               uint16 ident,
 302  *                                               uint32 argc, va_list ap);
 303  *
 304  * DESCRIPTION
 305  *
 306  *    This is equivalent to the silc_command_payload_encode_va except
 307  *    takes the va_list as argument.
 308  *
 309  ***/
 310 SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd,
 311                                            uint16 ident,
 312                                            uint32 argc, va_list ap);
 313
 314 /****f* silccore/SilcCommandAPI/silc_command_reply_payload_encode_va
 315  *
 316  * SYNOPSIS
 317  *
 318  *    SilcBuffer
 319  *    silc_command_reply_payload_encode_va(SilcCommand cmd,
 320  *                                         SilcCommandStatus status,
 321  *                                         uint16 ident,
 322  *                                         uint32 argc, ...);
 323  *
 324  * DESCRIPTION
 325  *
 326  *    Same as silc_command_payload_encode_va except that this is used to
 327  *    encode strictly command reply packets. The command status message
 328  *    to be returned is sent as extra argument to this function. The `argc'
 329  *    must not count `status' as on argument.
 330  *
 331  ***/
 332 SilcBuffer
 333 silc_command_reply_payload_encode_va(SilcCommand cmd,
 334                                      SilcCommandStatus status,
 335                                      uint16 ident,
 336                                      uint32 argc, ...);
 337
 338 /****f* silccore/SilcCommandAPI/silc_command_reply_payload_encode_vap
 339  *
 340  * SYNOPSIS
 341  *
 342  *    SilcBuffer
 343  *    silc_command_reply_payload_encode_vap(SilcCommand cmd,
 344  *                                          SilcCommandStatus status,
 345  *                                          uint16 ident, uint32 argc,
 346  *                                          va_list ap);
 347  *
 348  * DESCRIPTION
 349  *
 350  *    This is equivalent to the silc_command_reply_payload_encode_va except
 351  *    takes the va_list as argument.
 352  *
 353  ***/
 354 SilcBuffer
 355 silc_command_reply_payload_encode_vap(SilcCommand cmd,
 356                                       SilcCommandStatus status,
 357                                       uint16 ident, uint32 argc,
 358                                       va_list ap);
 359
 360 /****f* silccore/SilcCommandAPI/silc_command_free
 361  *
 362  * SYNOPSIS
 363  *
 364  *    void silc_command_payload_free(SilcCommandPayload payload);
 365  *
 366  * DESCRIPTION
 367  *
 368  *    Frees the Command Payload and all data in it.
 369  *
 370  ***/
 371 void silc_command_payload_free(SilcCommandPayload payload);
 372
 373 /****f* silccore/SilcCommandAPI/silc_command_get
 374  *
 375  * SYNOPSIS
 376  *
 377  *    SilcCommand silc_command_get(SilcCommandPayload payload);
 378  *
 379  * DESCRIPTION
 380  *
 381  *    Return the command from the payload.
 382  *
 383  ***/
 384 SilcCommand silc_command_get(SilcCommandPayload payload);
 385
 386 /****f* silccore/SilcCommandAPI/silc_command_get_args
 387  *
 388  * SYNOPSIS
 389  *
 390  *    SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload);
 391  *
 392  * DESCRIPTION
 393  *
 394  *    Return the Arguments Payload containing the arguments from the
 395  *    Command Payload. The caller must not free it.
 396  *
 397  ***/
 398 SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload);
 399
 400 /****f* silccore/SilcCommandAPI/silc_command_get_ident
 401  *
 402  * SYNOPSIS
 403  *
 404  *    uint16 silc_command_get_ident(SilcCommandPayload payload);
 405  *
 406  * DESCRIPTION
 407  *
 408  *    Return the command identifier from the payload. The identifier can
 409  *    be used to identify which command reply belongs to which command.
 410  *    The client sets the identifier to the payload and server must return
 411  *    the same identifier in the command reply.
 412  *
 413  ***/
 414 uint16 silc_command_get_ident(SilcCommandPayload payload);
 415
 416 /****f* silccore/SilcCommandAPI/silc_command_set_ident
 417  *
 418  * SYNOPSIS
 419  *
 420  *    void silc_command_set_ident(SilcCommandPayload payload, uint16 ident);
 421  *
 422  * DESCRIPTION
 423  *
 424  *    Function to set identifier to already allocated Command Payload. Command
 425  *    payloads are frequentlly resent in SILC and thusly this makes it easy
 426  *    to set the identifier without encoding new Command Payload.
 427  *
 428  ***/
 429 void silc_command_set_ident(SilcCommandPayload payload, uint16 ident);
 430
 431 /****f* silccore/SilcCommandAPI/silc_command_set_command
 432  *
 433  * SYNOPSIS
 434  *
 435  *    void silc_command_set_command(SilcCommandPayload payload,
 436  *                                  SilcCommand command);
 437  *
 438  * DESCRIPTION
 439  *
 440  *    Function to set the command to already allocated Command Payload. This
 441  *    makes it easy to change the command in the payload without encoding new
 442  *    Command Payload.
 443  *
 444  ***/
 445 void silc_command_set_command(SilcCommandPayload payload, SilcCommand command);
 446
 447 #endif