include/modules/cap.h

   1 /*
   2  * InspIRCd -- Internet Relay Chat Daemon
   3  *
   4  *   Copyright (C) 2015 Attila Molnar <attilamolnar@hush.com>
   5  *
   6  * This file is part of InspIRCd.  InspIRCd is free software: you can
   7  * redistribute it and/or modify it under the terms of the GNU General Public
   8  * License as published by the Free Software Foundation, version 2.
   9  *
  10  * This program is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  12  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  13  * details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19
  20 #pragma once
  21
  22 #include "event.h"
  23
  24 namespace Cap
  25 {
  26         static const unsigned int MAX_CAPS = (sizeof(intptr_t) * 8) - 1;
  27         static const intptr_t CAP_302_BIT = (intptr_t)1 << MAX_CAPS;
  28         static const unsigned int MAX_VALUE_LENGTH = 100;
  29
  30         typedef intptr_t Ext;
  31         typedef LocalIntExt ExtItem;
  32         class Capability;
  33
  34         enum Protocol
  35         {
  36                 /** Supports capability negotiation protocol v3.1, or none
  37                  */
  38                 CAP_LEGACY,
  39
  40                 /** Supports capability negotiation v3.2
  41                  */
  42                 CAP_302
  43         };
  44
  45         class EventListener : public Events::ModuleEventListener
  46         {
  47          public:
  48                 EventListener(Module* mod)
  49                         : ModuleEventListener(mod, "event/cap")
  50                 {
  51                 }
  52
  53                 /** Called whenever a new client capability becomes available or unavailable
  54                  * @param cap Capability being added or removed
  55                  * @param add If true, the capability is being added, otherwise its being removed
  56                  */
  57                 virtual void OnCapAddDel(Capability* cap, bool add) = 0;
  58         };
  59
  60         class Manager : public DataProvider
  61         {
  62          public:
  63                 Manager(Module* mod)
  64                         : DataProvider(mod, "capmanager")
  65                 {
  66                 }
  67
  68                 /** Register a client capability.
  69                  * Modules should call Capability::SetActive(true) instead of this method.
  70                  * @param cap Capability to register
  71                  */
  72                 virtual void AddCap(Capability* cap) = 0;
  73
  74                 /** Unregister a client capability.
  75                  * Modules should call Capability::SetActive(false) instead of this method.
  76                  * @param cap Capability to unregister
  77                  */
  78                 virtual void DelCap(Capability* cap) = 0;
  79
  80                 /** Find a capability by name
  81                  * @param name Capability to find
  82                  * @return Capability object pointer if found, NULL otherwise
  83                  */
  84                 virtual Capability* Find(const std::string& name) const = 0;
  85         };
  86
  87         /** Represents a client capability.
  88          *
  89          * Capabilities offer extensions to the client to server protocol. They must be negotiated with clients before they have any effect on the protocol.
  90          * Each cap must have a unique name that is used during capability negotiation.
  91          *
  92          * After construction the cap is ready to be used by clients without any further setup, like other InspIRCd services.
  93          * The get() method accepts a user as parameter and can be used to check whether that user has negotiated usage of the cap. This is only known for local users.
  94          *
  95          * The cap module must be loaded for the capability to work. The IsRegistered() method can be used to query whether the cap is actually online or not.
  96          * The capability can be deactivated and reactivated with the SetActive() method. Deactivated caps behave as if they don't exist.
  97          *
  98          * It is possible to implement special behavior by inheriting from this class and overriding some of its methods.
  99          */
 100         class Capability : public ServiceProvider, private dynamic_reference_base::CaptureHook
 101         {
 102                 typedef size_t Bit;
 103
 104                 /** Bit allocated to this cap, undefined if the cap is unregistered
 105                  */
 106                 Bit bit;
 107
 108                 /** Extension containing all caps set by a user. NULL if the cap is unregistered.
 109                  */
 110                 ExtItem* extitem;
 111
 112                 /** True if the cap is active. Only active caps are registered in the manager.
 113                  */
 114                 bool active;
 115
 116                 /** Reference to the cap manager object
 117                  */
 118                 dynamic_reference<Manager> manager;
 119
 120                 void OnCapture() CXX11_OVERRIDE
 121                 {
 122                         if (active)
 123                                 SetActive(true);
 124                 }
 125
 126                 void Unregister()
 127                 {
 128                         bit = 0;
 129                         extitem = NULL;
 130                 }
 131
 132                 Ext AddToMask(Ext mask) const { return (mask | GetMask()); }
 133                 Ext DelFromMask(Ext mask) const { return (mask & (~GetMask())); }
 134                 Bit GetMask() const { return bit; }
 135
 136                 friend class ManagerImpl;
 137
 138          public:
 139                 /** Constructor, initializes the capability.
 140                  * Caps are active by default.
 141                  * @param mod Module providing the cap
 142                  * @param Name Raw name of the cap as used in the protocol (CAP LS, etc.)
 143                  */
 144                 Capability(Module* mod, const std::string& Name)
 145                         : ServiceProvider(mod, Name, SERVICE_CUSTOM)
 146                         , active(true)
 147                         , manager(mod, "capmanager")
 148                 {
 149                         Unregister();
 150                 }
 151
 152                 ~Capability()
 153                 {
 154                         SetActive(false);
 155                 }
 156
 157                 void RegisterService() CXX11_OVERRIDE
 158                 {
 159                         manager.SetCaptureHook(this);
 160                         SetActive(true);
 161                 }
 162
 163                 /** Check whether a user has the capability turned on.
 164                  * This method is safe to call if the cap is unregistered and will return false.
 165                  * @param user User to check
 166                  * @return True if the user is using this capability, false otherwise
 167                  */
 168                 bool get(User* user) const
 169                 {
 170                         if (!IsRegistered())
 171                                 return false;
 172                         Ext caps = extitem->get(user);
 173                         return (caps & GetMask());
 174                 }
 175
 176                 /** Turn the capability on/off for a user. If the cap is not registered this method has no effect.
 177                  * @param user User to turn the cap on/off for
 178                  * @param val True to turn the cap on, false to turn it off
 179                  */
 180                 void set(User* user, bool val)
 181                 {
 182                         if (!IsRegistered())
 183                                 return;
 184                         Ext curr = extitem->get(user);
 185                         extitem->set(user, (val ? AddToMask(curr) : DelFromMask(curr)));
 186                 }
 187
 188                 /** Activate or deactivate the capability.
 189                  * If activating, the cap is marked as active and if the manager is available the cap is registered in the manager.
 190                  * If deactivating, the cap is marked as inactive and if it is registered, it will be unregistered.
 191                  * Users who had the cap turned on will have it turned off automatically.
 192                  * @param activate True to activate the cap, false to deactivate it
 193                  */
 194                 void SetActive(bool activate)
 195                 {
 196                         active = activate;
 197                         if (manager)
 198                         {
 199                                 if (activate)
 200                                         manager->AddCap(this);
 201                                 else
 202                                         manager->DelCap(this);
 203                         }
 204                 }
 205
 206                 /** Get the name of the capability that's used in the protocol
 207                  * @return Name of the capability as used in the protocol
 208                  */
 209                 const std::string& GetName() const { return name; }
 210
 211                 /** Check whether the capability is active. The cap must be active and registered to be used by users.
 212                  * @return True if the cap is active, false if it has been deactivated
 213                  */
 214                 bool IsActive() const { return active; }
 215
 216                 /** Check whether the capability is registered
 217                  * The cap must be active and the manager must be available for a cap to be registered.
 218                  * @return True if the cap is registered in the manager, false otherwise
 219                  */
 220                 bool IsRegistered() const { return (extitem != NULL); }
 221
 222                 /** Get the CAP negotiation protocol version of a user.
 223                  * The cap must be registered for this to return anything other than CAP_LEGACY.
 224                  * @param user User whose negotiation protocol version to query
 225                  * @return One of the Capability::Protocol enum indicating the highest supported capability negotiation protocol version
 226                  */
 227                 Protocol GetProtocol(LocalUser* user) const
 228                 {
 229                         return ((IsRegistered() && (extitem->get(user) & CAP_302_BIT)) ? CAP_302 : CAP_LEGACY);
 230                 }
 231
 232                 /** Called when a user requests to turn this capability on or off.
 233                  * @param user User requesting to change the state of the cap
 234                  * @param add True if requesting to turn the cap on, false if requesting to turn it off
 235                  * @return True to allow the request, false to reject it
 236                  */
 237                 virtual bool OnRequest(LocalUser* user, bool add)
 238                 {
 239                         return true;
 240                 }
 241
 242                 /** Called when a user requests a list of all capabilities and this capability is about to be included in the list.
 243                  * The default behavior always includes the cap in the list.
 244                  * @param user User querying a list capabilities
 245                  * @return True to add this cap to the list sent to the user, false to not list it
 246                  */
 247                 virtual bool OnList(LocalUser* user)
 248                 {
 249                         return true;
 250                 }
 251
 252                 /** Query the value of this capability for a user
 253                  * @param user User who will get the value of the capability
 254                  * @return Value to show to the user. If NULL, the capability has no value (default).
 255                  */
 256                 virtual const std::string* GetValue(LocalUser* user) const
 257                 {
 258                         return NULL;
 259                 }
 260         };
 261 }