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/SILC Command Interface
  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 SilcUInt8 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 SilcUInt8 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_STATS              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_DETACH             21
 148 #define SILC_COMMAND_WATCH              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 #define SILC_COMMAND_SERVICE            27
 154
 155 /* Private range start */
 156 #define SILC_COMMAND_PRIVATE            200
 157 #define SILC_COMMAND_PRIV_CONNECT       200
 158 #define SILC_COMMAND_PRIV_CLOSE         201
 159 #define SILC_COMMAND_PRIV_SHUTDOWN      202
 160
 161 /* Reserved */
 162 #define SILC_COMMAND_RESERVED           255
 163 /***/
 164
 165 /* Prototypes */
 166
 167 /****f* silccore/SilcCommandAPI/silc_command_payload_parse
 168  *
 169  * SYNOPSIS
 170  *
 171  *    SilcCommandPayload
 172  *    silc_command_payload_parse(const unsigned char *payload,
 173  *                               SilcUInt32 payload_len);
 174  *
 175  * DESCRIPTION
 176  *
 177  *    Parses command payload returning new command payload structure. The
 178  *    `buffer' is the raw payload.
 179  *
 180  ***/
 181 SilcCommandPayload silc_command_payload_parse(const unsigned char *payload,
 182                                               SilcUInt32 payload_len);
 183
 184 /****f* silccore/SilcCommandAPI/silc_command_payload_encode
 185  *
 186  * SYNOPSIS
 187  *
 188  *    SilcBuffer silc_command_payload_encode(SilcCommand cmd,
 189  *                                           SilcUInt32 argc,
 190  *                                           unsigned char **argv,
 191  *                                           SilcUInt32 *argv_lens,
 192  *                                           SilcUInt32 *argv_types,
 193  *                                           SilcUInt16 ident);
 194  *
 195  * DESCRIPTION
 196  *
 197  *     Encodes Command Payload returning it to SilcBuffer.
 198  *
 199  ***/
 200 SilcBuffer silc_command_payload_encode(SilcCommand cmd,
 201                                        SilcUInt32 argc,
 202                                        unsigned char **argv,
 203                                        SilcUInt32 *argv_lens,
 204                                        SilcUInt32 *argv_types,
 205                                        SilcUInt16 ident);
 206
 207 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_payload
 208  *
 209  * SYNOPSIS
 210  *
 211  *    SilcBuffer
 212  *    silc_command_payload_encode_payload(SilcCommandPayload payload);
 213  *
 214  * DESCRIPTION
 215  *
 216  *    Same as silc_command_payload_encode but encodes the buffer from
 217  *    SilcCommandPayload structure instead of raw data.
 218  *
 219  ***/
 220 SilcBuffer silc_command_payload_encode_payload(SilcCommandPayload payload);
 221
 222 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_va
 223  *
 224  * SYNOPSIS
 225  *
 226  *    SilcBuffer silc_command_payload_encode_va(SilcCommand cmd,
 227  *                                              SilcUInt16 ident,
 228  *                                              SilcUInt32 argc, ...);
 229  *
 230  * DESCRIPTION
 231  *
 232  *    Encodes Command payload with variable argument list. The arguments
 233  *    must be: SilcUInt32, unsigned char *, unsigned int, ... One
 234  *    {SilcUInt32, unsigned char * and unsigned int} forms one argument,
 235  *    thus `argc' in case when sending one {SilcUInt32, unsigned char *
 236  *    and SilcUInt32} equals one (1) and when sending two of those it
 237  *    equals two (2), and so on. This has to be preserved or bad things
 238  *    will happen. The variable arguments is: {type, data, data_len}.
 239  *
 240  ***/
 241 SilcBuffer silc_command_payload_encode_va(SilcCommand cmd,
 242                                           SilcUInt16 ident,
 243                                           SilcUInt32 argc, ...);
 244
 245 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_vap
 246  *
 247  * SYNOPSIS
 248  *
 249  *    SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd,
 250  *                                               SilcUInt16 ident,
 251  *                                               SilcUInt32 argc, va_list ap);
 252  *
 253  * DESCRIPTION
 254  *
 255  *    This is equivalent to the silc_command_payload_encode_va except
 256  *    takes the va_list as argument.
 257  *
 258  ***/
 259 SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd,
 260                                            SilcUInt16 ident,
 261                                            SilcUInt32 argc, va_list ap);
 262
 263 /****f* silccore/SilcCommandAPI/silc_command_reply_payload_encode_va
 264  *
 265  * SYNOPSIS
 266  *
 267  *    SilcBuffer
 268  *    silc_command_reply_payload_encode_va(SilcCommand cmd,
 269  *                                         SilcStatus status,
 270  *                                         SilcStatus error,
 271  *                                         SilcUInt16 ident,
 272  *                                         SilcUInt32 argc, ...);
 273  *
 274  * DESCRIPTION
 275  *
 276  *    Same as silc_command_payload_encode_va except that this is used to
 277  *    encode strictly command reply packets.  The `argc' must not count
 278  *    `status' and `error' as arguments.  The `status' includes the
 279  *    command reply status.  If single reply will be sent then it includes
 280  *    SILC_STATUS_OK if error did not occur.  It includes an error value
 281  *    if error did occur.  In this case `error' field is ignored.  If
 282  *    there will be multiple successful command replies then the `status'
 283  *    includes a list value and `error' is ignored.  If there will
 284  *    multiple error replies the `status' includes a list value, and
 285  *    the `error' includes an error value.  Thus, the `error' value is
 286  *    specified only if there will be list of errors.
 287  *
 288  * NOTES
 289  *
 290  *    Protocol defines that it is possible to send both list of successful
 291  *    and list of error replies at the same time, as long as the error
 292  *    replies are sent after the successful replies.
 293  *
 294  ***/
 295 SilcBuffer
 296 silc_command_reply_payload_encode_va(SilcCommand cmd,
 297                                      SilcStatus status,
 298                                      SilcStatus error,
 299                                      SilcUInt16 ident,
 300                                      SilcUInt32 argc, ...);
 301
 302 /****f* silccore/SilcCommandAPI/silc_command_reply_payload_encode_vap
 303  *
 304  * SYNOPSIS
 305  *
 306  *    SilcBuffer
 307  *    silc_command_reply_payload_encode_vap(SilcCommand cmd,
 308  *                                          SilcStatus status,
 309  *                                          SilcStatus error,
 310  *                                          SilcUInt16 ident, SilcUInt32 argc,
 311  *                                          va_list ap);
 312  *
 313  * DESCRIPTION
 314  *
 315  *    This is equivalent to the silc_command_reply_payload_encode_va except
 316  *    takes the va_list as argument.
 317  *
 318  ***/
 319 SilcBuffer
 320 silc_command_reply_payload_encode_vap(SilcCommand cmd,
 321                                       SilcStatus status,
 322                                       SilcStatus error,
 323                                       SilcUInt16 ident, SilcUInt32 argc,
 324                                       va_list ap);
 325
 326 /****f* silccore/SilcCommandAPI/silc_command_free
 327  *
 328  * SYNOPSIS
 329  *
 330  *    void silc_command_payload_free(SilcCommandPayload payload);
 331  *
 332  * DESCRIPTION
 333  *
 334  *    Frees the Command Payload and all data in it.
 335  *
 336  ***/
 337 void silc_command_payload_free(SilcCommandPayload payload);
 338
 339 /****f* silccore/SilcCommandAPI/silc_command_get
 340  *
 341  * SYNOPSIS
 342  *
 343  *    SilcCommand silc_command_get(SilcCommandPayload payload);
 344  *
 345  * DESCRIPTION
 346  *
 347  *    Return the command from the payload.
 348  *
 349  ***/
 350 SilcCommand silc_command_get(SilcCommandPayload payload);
 351
 352 /****f* silccore/SilcCommandAPI/silc_command_get_args
 353  *
 354  * SYNOPSIS
 355  *
 356  *    SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload);
 357  *
 358  * DESCRIPTION
 359  *
 360  *    Return the Arguments Payload containing the arguments from the
 361  *    Command Payload. The caller must not free it.
 362  *
 363  ***/
 364 SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload);
 365
 366 /****f* silccore/SilcCommandAPI/silc_command_get_ident
 367  *
 368  * SYNOPSIS
 369  *
 370  *    SilcUInt16 silc_command_get_ident(SilcCommandPayload payload);
 371  *
 372  * DESCRIPTION
 373  *
 374  *    Return the command identifier from the payload. The identifier can
 375  *    be used to identify which command reply belongs to which command.
 376  *    The client sets the identifier to the payload and server must return
 377  *    the same identifier in the command reply.
 378  *
 379  ***/
 380 SilcUInt16 silc_command_get_ident(SilcCommandPayload payload);
 381
 382 /****f* silccore/SilcCommandAPI/silc_command_get_status
 383  *
 384  * SYNOPSIS
 385  *
 386  *    bool silc_command_get_status(SilcCommandPayload payload,
 387  *                                 SilcStatus *status,
 388  *                                 SilcStatus *error);
 389  *
 390  * DESCRIPTION
 391  *
 392  *    This function returns the command reply status into `status' and
 393  *    error status, if error occurred into the `error'.  The function
 394  *    returns TRUE if command reply status is not error, and FALSE if
 395  *    error occurred.  In this case the `error' will include the actual
 396  *    error status.  The `status' can be in this case some list value
 397  *    which indicates that there will be list of errors.
 398  *
 399  ***/
 400 bool silc_command_get_status(SilcCommandPayload payload,
 401                              SilcStatus *status,
 402                              SilcStatus *error);
 403
 404 /****f* silccore/SilcCommandAPI/silc_command_set_ident
 405  *
 406  * SYNOPSIS
 407  *
 408  *    void silc_command_set_ident(SilcCommandPayload payload,
 409  *                                SilcUInt16 ident);
 410  *
 411  * DESCRIPTION
 412  *
 413  *    Function to set identifier to already allocated Command Payload. Command
 414  *    payloads are frequentlly resent in SILC and thusly this makes it easy
 415  *    to set the identifier without encoding new Command Payload.
 416  *
 417  ***/
 418 void silc_command_set_ident(SilcCommandPayload payload, SilcUInt16 ident);
 419
 420 /****f* silccore/SilcCommandAPI/silc_command_set_command
 421  *
 422  * SYNOPSIS
 423  *
 424  *    void silc_command_set_command(SilcCommandPayload payload,
 425  *                                  SilcCommand command);
 426  *
 427  * DESCRIPTION
 428  *
 429  *    Function to set the command to already allocated Command Payload. This
 430  *    makes it easy to change the command in the payload without encoding new
 431  *    Command Payload.
 432  *
 433  ***/
 434 void silc_command_set_command(SilcCommandPayload payload, SilcCommand command);
 435
 436 #endif