lib/silccore/silccommand.h

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