include/ctables.h

   1 /*
   2  * InspIRCd -- Internet Relay Chat Daemon
   3  *
   4  *   Copyright (C) 2012-2015, 2018 Attila Molnar <attilamolnar@hush.com>
   5  *   Copyright (C) 2012-2013, 2017-2018 Sadie Powell <sadie@witchery.services>
   6  *   Copyright (C) 2012 Robby <robby@chatbelgie.be>
   7  *   Copyright (C) 2009-2010 Daniel De Graaf <danieldg@inspircd.org>
   8  *   Copyright (C) 2008 Thomas Stagner <aquanight@inspircd.org>
   9  *   Copyright (C) 2007-2008 Robin Burchell <robin+git@viroteck.net>
  10  *   Copyright (C) 2007 Dennis Friis <peavey@inspircd.org>
  11  *   Copyright (C) 2006-2010 Craig Edwards <brain@inspircd.org>
  12  *
  13  * This file is part of InspIRCd.  InspIRCd is free software: you can
  14  * redistribute it and/or modify it under the terms of the GNU General Public
  15  * License as published by the Free Software Foundation, version 2.
  16  *
  17  * This program is distributed in the hope that it will be useful, but WITHOUT
  18  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  19  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  20  * details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  24  */
  25
  26
  27 #pragma once
  28
  29 /** Used to indicate the result of trying to execute a command. */
  30 enum CmdResult
  31 {
  32         /** The command exists but its execution failed. */
  33         CMD_FAILURE = 0,
  34
  35         /** The command exists and its execution succeeded. */
  36         CMD_SUCCESS = 1,
  37
  38         /* The command does not exist. */
  39         CMD_INVALID = 2
  40 };
  41
  42 /** Flag for commands that are only allowed from servers */
  43 const char FLAG_SERVERONLY = 7; // technically anything nonzero below 'A' works
  44
  45 /** Translation types for translation of parameters to UIDs.
  46  * This allows the core commands to not have to be aware of how UIDs
  47  * work (making it still possible to write other linking modules which
  48  * do not use UID (but why would you want to?)
  49  */
  50 enum TranslateType
  51 {
  52         TR_TEXT,                /* Raw text, leave as-is */
  53         TR_NICK,                /* Nickname, translate to UUID for server->server */
  54         TR_CUSTOM               /* Custom translation handled by EncodeParameter/DecodeParameter */
  55 };
  56
  57 /** Routing types for a command. Any command which is created defaults
  58  * to having its command broadcasted on success. This behaviour may be
  59  * overridden to one of the route types shown below (see the #defines
  60  * below for more information on each one's behaviour)
  61  */
  62 enum RouteType
  63 {
  64         ROUTE_TYPE_LOCALONLY,
  65         ROUTE_TYPE_BROADCAST,
  66         ROUTE_TYPE_UNICAST,
  67         ROUTE_TYPE_MESSAGE,
  68         ROUTE_TYPE_OPT_BCAST,
  69         ROUTE_TYPE_OPT_UCAST
  70 };
  71
  72 /** Defines routing information for a command, containing a destination
  73  * server id (if applicable) and a routing type from the enum above.
  74  */
  75 struct RouteDescriptor
  76 {
  77         /** Routing type from the enum above
  78          */
  79         RouteType type;
  80         /** For unicast, the destination server's name
  81          */
  82         std::string serverdest;
  83
  84         /** For unicast, the destination Server
  85          */
  86         Server* server;
  87
  88         /** Create a RouteDescriptor
  89          */
  90         RouteDescriptor(RouteType t, const std::string &d)
  91                 : type(t), serverdest(d), server(NULL) { }
  92
  93         RouteDescriptor(RouteType t, Server* srv)
  94                 : type(t), server(srv) { }
  95 };
  96
  97 /** Do not route this command */
  98 #define ROUTE_LOCALONLY (RouteDescriptor(ROUTE_TYPE_LOCALONLY, ""))
  99 /** Route this command to all servers, fail if not understood */
 100 #define ROUTE_BROADCAST (RouteDescriptor(ROUTE_TYPE_BROADCAST, ""))
 101 /** Route this command to a single server (do nothing if own server name specified) */
 102 #define ROUTE_UNICAST(x) (RouteDescriptor(ROUTE_TYPE_UNICAST, x))
 103 /** Route this command as a message with the given target (any of user, #channel, @#channel, $servermask) */
 104 #define ROUTE_MESSAGE(x) (RouteDescriptor(ROUTE_TYPE_MESSAGE, x))
 105 /** Route this command to all servers wrapped via ENCAP, so ignored if not understood */
 106 #define ROUTE_OPT_BCAST (RouteDescriptor(ROUTE_TYPE_OPT_BCAST, ""))
 107 /** Route this command to a single server wrapped via ENCAP, so ignored if not understood */
 108 #define ROUTE_OPT_UCAST(x) (RouteDescriptor(ROUTE_TYPE_OPT_UCAST, x))
 109
 110 /** A structure that defines a command. Every command available
 111  * in InspIRCd must be defined as derived from Command.
 112  */
 113 class CoreExport CommandBase : public ServiceProvider
 114 {
 115  public:
 116         /** Encapsulates parameters to a command. */
 117         class Params : public std::vector<std::string>
 118         {
 119          private:
 120                 /* IRCv3 message tags. */
 121                 ClientProtocol::TagMap tags;
 122
 123          public:
 124                 /** Initializes a new instance from parameter and tag references.
 125                  * @param paramsref Message parameters.
 126                  * @param tagsref IRCv3 message tags.
 127                  */
 128                 Params(const std::vector<std::string>& paramsref, const ClientProtocol::TagMap& tagsref)
 129                         : std::vector<std::string>(paramsref)
 130                         , tags(tagsref)
 131                 {
 132                 }
 133
 134                 /** Initializes a new instance from parameter iterators.
 135                  * @param first The first element in the parameter array.
 136                  * @param last The last element in the parameter array.
 137                  */
 138                 template<typename Iterator>
 139                 Params(Iterator first, Iterator last)
 140                         : std::vector<std::string>(first, last)
 141                 {
 142                 }
 143
 144                 /** Initializes a new empty instance. */
 145                 Params() { }
 146
 147                 /** Retrieves the IRCv3 message tags. */
 148                 const ClientProtocol::TagMap& GetTags() const { return tags; }
 149         };
 150
 151         /** Minimum number of parameters command takes
 152         */
 153         const unsigned int min_params;
 154
 155         /** Maximum number of parameters command takes.
 156          * This is used by the command parser to join extra parameters into one last param.
 157          * If not set, no munging is done to this command.
 158          */
 159         const unsigned int max_params;
 160
 161         /** True if the command allows an empty last parameter.
 162          * When false and the last parameter is empty, it's popped BEFORE
 163          * checking there are enough params, etc. (i.e. the handler won't
 164          * be called if there aren't enough params after popping the empty
 165          * param).
 166          * True by default
 167          */
 168         bool allow_empty_last_param;
 169
 170         /** Translation type list for possible parameters, used to tokenize
 171          * parameters into UIDs and SIDs etc.
 172          */
 173         std::vector<TranslateType> translation;
 174
 175         /** Create a new command.
 176          * @param me The module which created this command.
 177          * @param cmd Command name. This must be UPPER CASE.
 178          * @param minpara Minimum parameters required for the command.
 179          * @param maxpara Maximum number of parameters this command may have - extra parameters
 180          * will be tossed into one last space-seperated param.
 181          */
 182         CommandBase(Module* me, const std::string& cmd, unsigned int minpara = 0, unsigned int maxpara = 0);
 183
 184         virtual RouteDescriptor GetRouting(User* user, const CommandBase::Params& parameters);
 185
 186         /** Encode a parameter for server->server transmission.
 187          * Used for parameters for which the translation type is TR_CUSTOM.
 188          * @param parameter The parameter to encode. Can be modified in place.
 189          * @param index The parameter index (0 == first parameter).
 190          */
 191         virtual void EncodeParameter(std::string& parameter, unsigned int index);
 192
 193         virtual ~CommandBase();
 194 };
 195
 196 class CoreExport Command : public CommandBase
 197 {
 198  protected:
 199         /** Initializes a new instance of the Command class.
 200          * @param me The module which created this instance.
 201          * @param cmd The name of the command.
 202          * @param minpara The minimum number of parameters that the command accepts.
 203          * @param maxpara The maximum number of parameters that the command accepts.
 204          */
 205         Command(Module* me, const std::string& cmd, unsigned int minpara = 0, unsigned int maxpara = 0);
 206
 207  public:
 208         /** Unregisters this command from the command parser. */
 209         ~Command() CXX11_OVERRIDE;
 210
 211         /** The user modes required to be able to execute this command. */
 212         unsigned char flags_needed;
 213
 214         /** Whether the command will not be forwarded by the linking module even if it comes via ENCAP. */
 215         bool force_manual_route;
 216
 217         /** The number of seconds worth of penalty that executing this command gives. */
 218         unsigned int Penalty;
 219
 220         /** The number of times this command has been executed. */
 221         unsigned long use_count;
 222
 223         /** If non-empty then the syntax of the parameter for this command. */
 224         std::string syntax;
 225
 226         /** Whether the command can be issued before registering. */
 227         bool works_before_reg;
 228
 229         /** Handle the command from a user.
 230          * @param user The user who issued the command.
 231          * @param parameters The parameters for the command.
 232          * @return Returns CMD_FAILURE on failure, CMD_SUCCESS on success, or CMD_INVALID
 233          *         if the command was malformed.
 234          */
 235         virtual CmdResult Handle(User* user, const Params& parameters) = 0;
 236
 237         /** Registers this command with the command parser. */
 238         void RegisterService() CXX11_OVERRIDE;
 239
 240         /** Tells the user they did not specify enough parameters.
 241          * @param user The user who issued the command.
 242          * @param parameters The parameters for the command.
 243          */
 244         virtual void TellNotEnoughParameters(LocalUser* user, const Params& parameters);
 245
 246         /** Tells the user they need to be registered to execute this command.
 247          * @param user The user who issued the command.
 248          * @param parameters The parameters for the command.
 249          */
 250         virtual void TellNotRegistered(LocalUser* user, const Params& parameters);
 251 };
 252
 253 class CoreExport SplitCommand : public Command
 254 {
 255 protected:
 256         /** Initializes a new instance of the SplitCommand class.
 257          * @param me The module which created this instance.
 258          * @param cmd The name of the command.
 259          * @param minpara The minimum number of parameters that the command accepts.
 260          * @param maxpara The maximum number of parameters that the command accepts.
 261          */
 262         SplitCommand(Module* me, const std::string& cmd, unsigned int minpara = 0, unsigned int maxpara = 0);
 263
 264  public:
 265         /** @copydoc Command::Handle */
 266         CmdResult Handle(User* user, const Params& parameters) CXX11_OVERRIDE;
 267
 268         /** Handle the command from a local user.
 269          * @param user The user who issued the command.
 270          * @param parameters The parameters for the command.
 271          * @return Returns CMD_FAILURE on failure, CMD_SUCCESS on success, or CMD_INVALID
 272          *         if the command was malformed.
 273          */
 274         virtual CmdResult HandleLocal(LocalUser* user, const Params& parameters);
 275
 276         /** Handle the command from a remote user.
 277          * @param user The user who issued the command.
 278          * @param parameters The parameters for the command.
 279          * @return Returns CMD_FAILURE on failure, CMD_SUCCESS on success, or CMD_INVALID
 280          *         if the command was malformed.
 281          */
 282         virtual CmdResult HandleRemote(RemoteUser* user, const Params& parameters);
 283
 284         /** Handle the command from a server user.
 285          * @param user The user who issued the command.
 286          * @param parameters The parameters for the command.
 287          * @return Returns CMD_FAILURE on failure, CMD_SUCCESS on success, or CMD_INVALID
 288          *         if the command was malformed.
 289          */
 290         virtual CmdResult HandleServer(FakeUser* user, const Params& parameters);
 291 };
 292
 293 /** Shortcut macros for defining translation lists
 294  */
 295 #define TRANSLATE1(x1)  translation.push_back(x1);
 296 #define TRANSLATE2(x1,x2)  translation.push_back(x1);translation.push_back(x2);
 297 #define TRANSLATE3(x1,x2,x3)  translation.push_back(x1);translation.push_back(x2);translation.push_back(x3);
 298 #define TRANSLATE4(x1,x2,x3,x4)  translation.push_back(x1);translation.push_back(x2);translation.push_back(x3);translation.push_back(x4);
 299 #define TRANSLATE5(x1,x2,x3,x4,x5)  translation.push_back(x1);translation.push_back(x2);translation.push_back(x3);translation.push_back(x4);\
 300         translation.push_back(x5);
 301 #define TRANSLATE6(x1,x2,x3,x4,x5,x6)  translation.push_back(x1);translation.push_back(x2);translation.push_back(x3);translation.push_back(x4);\
 302         translation.push_back(x5);translation.push_back(x6);
 303 #define TRANSLATE7(x1,x2,x3,x4,x5,x6,x7)  translation.push_back(x1);translation.push_back(x2);translation.push_back(x3);translation.push_back(x4);\
 304         translation.push_back(x5);translation.push_back(x6);translation.push_back(x7);
 305 #define TRANSLATE8(x1,x2,x3,x4,x5,x6,x7,x8)  translation.push_back(x1);translation.push_back(x2);translation.push_back(x3);translation.push_back(x4);\
 306         translation.push_back(x5);translation.push_back(x6);translation.push_back(x7);translation.push_back(x8);