X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilccore%2Fsilccommand.h;h=bbd1fcf46f8589e8a0a6f2469beb1a1bde4be407;hb=a818c5b5411bbc4436d1c5f011236985c96bb787;hp=bdca206b0dfa84b029fa69dc8bb4eb4a37193a6d;hpb=4d35af3be05cacf69ca4bd634973cdcd25118e98;p=silc.git diff --git a/lib/silccore/silccommand.h b/lib/silccore/silccommand.h index bdca206b..bbd1fcf4 100644 --- a/lib/silccore/silccommand.h +++ b/lib/silccore/silccommand.h @@ -1,16 +1,16 @@ /* - + silccommand.h - - Author: Pekka Riikonen - - Copyright (C) 1997 - 2000 Pekka Riikonen - + + Author: Pekka Riikonen + + Copyright (C) 1997 - 2001 Pekka Riikonen + This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. - + This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -18,42 +18,111 @@ */ +/****h* silccore/SilcCommandAPI + * + * DESCRIPTION + * + * Implementation of the Command Payload. The Command Payload is used to + * send commands and also command replies usually between client and + * server. + * + ***/ + #ifndef SILCCOMMAND_H #define SILCCOMMAND_H -/* Command function callback. The actual command function pointer. */ -typedef void (*SilcCommandCb)(void *context); - -/* Typedefinition for SILC commands. */ -typedef unsigned char SilcCommand; +/****f* silccore/SilcCommandAPI/SilcCommandCb + * + * SYNOPSIS + * + * typedef void (*SilcCommandCb)(void *context, void *context2); + * + * DESCRIPTION + * + * Command function callback. The actual command function pointer. + * This is generic command callback that the application may choose to + * use with its command routines. However, none of the generic + * routines depend on this callback so application may freely define + * their own command callback if desired. + * + ***/ +typedef void (*SilcCommandCb)(void *context, void *context2); -/* Forward declaration for Command Payload parsed from packet. The - actual structure is defined in source file and is private data. */ +/****s* silccore/SilcCommandAPI/SilcCommandPayload + * + * NAME + * + * typedef struct SilcCommandPayloadStruct *SilcCommandPayload; + * + * DESCRIPTION + * + * This context is the actual Command Payload and is allocated + * by silc_command_payload_parse and given as argument usually to + * all silc_command_payload_* functions. It is freed by the + * silc_command_payload_free function. + * + ***/ typedef struct SilcCommandPayloadStruct *SilcCommandPayload; -/* Command flags. These set how the commands behave on different - situations. These can be OR'ed together to set multiple flags. */ +/****d* silccore/SilcCommandAPI/SilcCommandFlags + * + * NAME + * + * typedef enum { ... } SilcCommandFlags; + * + * DESCRIPTION + * + * Command flags that set how the commands behave on different + * situations. These can be OR'es together to set multiple flags. + * The application is resoponsible of implementing the behaviour + * of these flags. These are here just to define generic flags. + * The server usually makes use of these flags. + * + * SOURCE + */ typedef enum { SILC_CF_NONE = 0, - /* Command may only be used once per (about) 2 seconds */ + /* Command may only be used once per (about) 2 seconds. Bursts up + to 5 commands are allowed though. */ SILC_CF_LAG = (1L << 1), + /* Command may only be used once per (about) 2 seconds. No bursts + are allowed at all. */ + SILC_CF_LAG_STRICT = (1L << 2), + /* Command is available for registered connections (connections whose ID has been created. */ - SILC_CF_REG = (1L << 2), + SILC_CF_REG = (1L << 3), /* Command is available only for server operators */ - SILC_CF_OPER = (1L << 3), + SILC_CF_OPER = (1L << 4), /* Command is available only for SILC (router) operators. If this is set SILC_CF_OPER is not necessary to be set. */ - SILC_CF_SILC_OPER = (1L << 4), + SILC_CF_SILC_OPER = (1L << 5), } SilcCommandFlag; +/***/ + +/****d* silccore/SilcCommandAPI/SilcCommand + * + * NAME + * + * typedef unsigned char SilcCommand; + * + * DESCRIPTION + * + * The SilcCommand type definition and the commands. The commands + * listed here are the official SILC Commands and they have client + * and server counterparts. + * + * SOURCE + */ +typedef unsigned char SilcCommand; /* All SILC commands. These are commands that have client and server - counterparts. These are pretty much the same as in IRC. */ + counterparts. */ #define SILC_COMMAND_NONE 0 #define SILC_COMMAND_WHOIS 1 #define SILC_COMMAND_WHOWAS 2 @@ -74,18 +143,33 @@ typedef enum { #define SILC_COMMAND_CMODE 17 #define SILC_COMMAND_CUMODE 18 #define SILC_COMMAND_KICK 19 -#define SILC_COMMAND_RESTART 20 +#define SILC_COMMAND_BAN 20 #define SILC_COMMAND_CLOSE 21 -#define SILC_COMMAND_DIE 22 +#define SILC_COMMAND_SHUTDOWN 22 #define SILC_COMMAND_SILCOPER 23 #define SILC_COMMAND_LEAVE 24 -#define SILC_COMMAND_NAMES 25 +#define SILC_COMMAND_USERS 25 +#define SILC_COMMAND_GETKEY 26 /* Reserved */ #define SILC_COMMAND_RESERVED 255 +/***/ -/* Command Status type */ -typedef unsigned short SilcCommandStatus; +/****d* silccore/SilcCommandAPI/SilcCommandStatus + * + * NAME + * + * typedef SilcUInt16 SilcCommandStatus; + * + * DESCRIPTION + * + * The SilcCommandStatus type definition and the status defines. + * The server returns a status in each Command Payload indicating + * the status of the command. + * + * SOURCE + */ +typedef SilcUInt16 SilcCommandStatus; /* Command Status messages */ #define SILC_STATUS_OK 0 @@ -122,34 +206,245 @@ typedef unsigned short SilcCommandStatus; #define SILC_STATUS_ERR_UNKNOWN_MODE 37 #define SILC_STATUS_ERR_NOT_YOU 38 #define SILC_STATUS_ERR_NO_CHANNEL_PRIV 39 -#define SILC_STATUS_ERR_NO_SERVER_PRIV 40 -#define SILC_STATUS_ERR_NO_ROUTER_PRIV 41 -#define SILC_STATUS_ERR_BAD_NICKNAME 42 -#define SILC_STATUS_ERR_BAD_CHANNEL 43 -#define SILC_STATUS_ERR_AUTH_FAILED 44 +#define SILC_STATUS_ERR_NO_CHANNEL_FOPRIV 40 +#define SILC_STATUS_ERR_NO_SERVER_PRIV 41 +#define SILC_STATUS_ERR_NO_ROUTER_PRIV 42 +#define SILC_STATUS_ERR_BAD_NICKNAME 43 +#define SILC_STATUS_ERR_BAD_CHANNEL 44 +#define SILC_STATUS_ERR_AUTH_FAILED 45 +#define SILC_STATUS_ERR_UNKNOWN_ALGORITHM 46 +#define SILC_STATUS_ERR_NO_SUCH_SERVER_ID 47 +/***/ /* Prototypes */ -SilcCommandPayload silc_command_payload_parse(SilcBuffer buffer); + +/****f* silccore/SilcCommandAPI/silc_command_payload_parse + * + * SYNOPSIS + * + * SilcCommandPayload + * silc_command_payload_parse(const unsigned char *payload, + * SilcUInt32 payload_len); + * + * DESCRIPTION + * + * Parses command payload returning new command payload structure. The + * `buffer' is the raw payload. + * + ***/ +SilcCommandPayload silc_command_payload_parse(const unsigned char *payload, + SilcUInt32 payload_len); + +/****f* silccore/SilcCommandAPI/silc_command_payload_encode + * + * SYNOPSIS + * + * SilcBuffer silc_command_payload_encode(SilcCommand cmd, + * SilcUInt32 argc, + * unsigned char **argv, + * SilcUInt32 *argv_lens, + * SilcUInt32 *argv_types, + * SilcUInt16 ident); + * + * DESCRIPTION + * + * Encodes Command Payload returning it to SilcBuffer. + * + ***/ SilcBuffer silc_command_payload_encode(SilcCommand cmd, - unsigned int argc, + SilcUInt32 argc, unsigned char **argv, - unsigned int *argv_lens, - unsigned int *argv_types, - unsigned short ident); + SilcUInt32 *argv_lens, + SilcUInt32 *argv_types, + SilcUInt16 ident); + +/****f* silccore/SilcCommandAPI/silc_command_payload_encode_payload + * + * SYNOPSIS + * + * SilcBuffer + * silc_command_payload_encode_payload(SilcCommandPayload payload); + * + * DESCRIPTION + * + * Same as silc_command_payload_encode but encodes the buffer from + * SilcCommandPayload structure instead of raw data. + * + ***/ +SilcBuffer silc_command_payload_encode_payload(SilcCommandPayload payload); + +/****f* silccore/SilcCommandAPI/silc_command_payload_encode_va + * + * SYNOPSIS + * + * SilcBuffer silc_command_payload_encode_va(SilcCommand cmd, + * SilcUInt16 ident, + * SilcUInt32 argc, ...); + * + * DESCRIPTION + * + * Encodes Command payload with variable argument list. The arguments + * must be: SilcUInt32, unsigned char *, unsigned int, ... One + * {SilcUInt32, unsigned char * and unsigned int} forms one argument, + * thus `argc' in case when sending one {SilcUInt32, unsigned char * + * and SilcUInt32} equals one (1) and when sending two of those it + * equals two (2), and so on. This has to be preserved or bad things + * will happen. The variable arguments is: {type, data, data_len}. + * + ***/ SilcBuffer silc_command_payload_encode_va(SilcCommand cmd, - unsigned short ident, - unsigned int argc, ...); + SilcUInt16 ident, + SilcUInt32 argc, ...); + +/****f* silccore/SilcCommandAPI/silc_command_payload_encode_vap + * + * SYNOPSIS + * + * SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd, + * SilcUInt16 ident, + * SilcUInt32 argc, va_list ap); + * + * DESCRIPTION + * + * This is equivalent to the silc_command_payload_encode_va except + * takes the va_list as argument. + * + ***/ SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd, - unsigned short ident, - unsigned int argc, va_list ap); + SilcUInt16 ident, + SilcUInt32 argc, va_list ap); + +/****f* silccore/SilcCommandAPI/silc_command_reply_payload_encode_va + * + * SYNOPSIS + * + * SilcBuffer + * silc_command_reply_payload_encode_va(SilcCommand cmd, + * SilcCommandStatus status, + * SilcUInt16 ident, + * SilcUInt32 argc, ...); + * + * DESCRIPTION + * + * Same as silc_command_payload_encode_va except that this is used to + * encode strictly command reply packets. The command status message + * to be returned is sent as extra argument to this function. The `argc' + * must not count `status' as on argument. + * + ***/ SilcBuffer silc_command_reply_payload_encode_va(SilcCommand cmd, SilcCommandStatus status, - unsigned short ident, - unsigned int argc, ...); -void silc_command_free_payload(SilcCommandPayload payload); + SilcUInt16 ident, + SilcUInt32 argc, ...); + +/****f* silccore/SilcCommandAPI/silc_command_reply_payload_encode_vap + * + * SYNOPSIS + * + * SilcBuffer + * silc_command_reply_payload_encode_vap(SilcCommand cmd, + * SilcCommandStatus status, + * SilcUInt16 ident, SilcUInt32 argc, + * va_list ap); + * + * DESCRIPTION + * + * This is equivalent to the silc_command_reply_payload_encode_va except + * takes the va_list as argument. + * + ***/ +SilcBuffer +silc_command_reply_payload_encode_vap(SilcCommand cmd, + SilcCommandStatus status, + SilcUInt16 ident, SilcUInt32 argc, + va_list ap); + +/****f* silccore/SilcCommandAPI/silc_command_free + * + * SYNOPSIS + * + * void silc_command_payload_free(SilcCommandPayload payload); + * + * DESCRIPTION + * + * Frees the Command Payload and all data in it. + * + ***/ +void silc_command_payload_free(SilcCommandPayload payload); + +/****f* silccore/SilcCommandAPI/silc_command_get + * + * SYNOPSIS + * + * SilcCommand silc_command_get(SilcCommandPayload payload); + * + * DESCRIPTION + * + * Return the command from the payload. + * + ***/ SilcCommand silc_command_get(SilcCommandPayload payload); + +/****f* silccore/SilcCommandAPI/silc_command_get_args + * + * SYNOPSIS + * + * SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload); + * + * DESCRIPTION + * + * Return the Arguments Payload containing the arguments from the + * Command Payload. The caller must not free it. + * + ***/ SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload); -unsigned short silc_command_get_ident(SilcCommandPayload payload); + +/****f* silccore/SilcCommandAPI/silc_command_get_ident + * + * SYNOPSIS + * + * SilcUInt16 silc_command_get_ident(SilcCommandPayload payload); + * + * DESCRIPTION + * + * Return the command identifier from the payload. The identifier can + * be used to identify which command reply belongs to which command. + * The client sets the identifier to the payload and server must return + * the same identifier in the command reply. + * + ***/ +SilcUInt16 silc_command_get_ident(SilcCommandPayload payload); + +/****f* silccore/SilcCommandAPI/silc_command_set_ident + * + * SYNOPSIS + * + * void silc_command_set_ident(SilcCommandPayload payload, SilcUInt16 ident); + * + * DESCRIPTION + * + * Function to set identifier to already allocated Command Payload. Command + * payloads are frequentlly resent in SILC and thusly this makes it easy + * to set the identifier without encoding new Command Payload. + * + ***/ +void silc_command_set_ident(SilcCommandPayload payload, SilcUInt16 ident); + +/****f* silccore/SilcCommandAPI/silc_command_set_command + * + * SYNOPSIS + * + * void silc_command_set_command(SilcCommandPayload payload, + * SilcCommand command); + * + * DESCRIPTION + * + * Function to set the command to already allocated Command Payload. This + * makes it easy to change the command in the payload without encoding new + * Command Payload. + * + ***/ +void silc_command_set_command(SilcCommandPayload payload, SilcCommand command); #endif