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
  29         typedef intptr_t Ext;
  30         typedef LocalIntExt ExtItem;
  31         class Capability;
  32
  33         enum Protocol
  34         {
  35                 /** Supports capability negotiation protocol v3.1, or none
  36                  */
  37                 CAP_LEGACY,
  38
  39                 /** Supports capability negotiation v3.2
  40                  */
  41                 CAP_302
  42         };
  43
  44         class Manager : public DataProvider
  45         {
  46          public:
  47                 Manager(Module* mod)
  48                         : DataProvider(mod, "capmanager")
  49                 {
  50                 }
  51
  52                 /** Register a client capability.
  53                  * Modules should call Capability::SetActive(true) instead of this method.
  54                  * @param cap Capability to register
  55                  */
  56                 virtual void AddCap(Capability* cap) = 0;
  57
  58                 /** Unregister a client capability.
  59                  * Modules should call Capability::SetActive(false) instead of this method.
  60                  * @param cap Capability to unregister
  61                  */
  62                 virtual void DelCap(Capability* cap) = 0;
  63
  64                 /** Find a capability by name
  65                  * @param name Capability to find
  66                  * @return Capability object pointer if found, NULL otherwise
  67                  */
  68                 virtual Capability* Find(const std::string& name) const = 0;
  69         };
  70
  71         /** Represents a client capability.
  72          *
  73          * Capabilities offer extensions to the client to server protocol. They must be negotiated with clients before they have any effect on the protocol.
  74          * Each cap must have a unique name that is used during capability negotiation.
  75          *
  76          * After construction the cap is ready to be used by clients without any further setup, like other InspIRCd services.
  77          * 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.
  78          *
  79          * 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.
  80          * The capability can be deactivated and reactivated with the SetActive() method. Deactivated caps behave as if they don't exist.
  81          *
  82          * It is possible to implement special behavior by inheriting from this class and overriding some of its methods.
  83          */
  84         class Capability : public ServiceProvider, private dynamic_reference_base::CaptureHook
  85         {
  86                 typedef size_t Bit;
  87
  88                 /** Bit allocated to this cap, undefined if the cap is unregistered
  89                  */
  90                 Bit bit;
  91
  92                 /** Extension containing all caps set by a user. NULL if the cap is unregistered.
  93                  */
  94                 ExtItem* extitem;
  95
  96                 /** True if the cap is active. Only active caps are registered in the manager.
  97                  */
  98                 bool active;
  99
 100                 /** Reference to the cap manager object
 101                  */
 102                 dynamic_reference<Manager> manager;
 103
 104                 void OnCapture() CXX11_OVERRIDE
 105                 {
 106                         if (active)
 107                                 SetActive(true);
 108                 }
 109
 110                 void Unregister()
 111                 {
 112                         bit = 0;
 113                         extitem = NULL;
 114                 }
 115
 116                 Ext AddToMask(Ext mask) const { return (mask | GetMask()); }
 117                 Ext DelFromMask(Ext mask) const { return (mask & (~GetMask())); }
 118                 Bit GetMask() const { return bit; }
 119
 120                 friend class ManagerImpl;
 121
 122          public:
 123                 /** Constructor, initializes the capability.
 124                  * Caps are active by default.
 125                  * @param mod Module providing the cap
 126                  * @param Name Raw name of the cap as used in the protocol (CAP LS, etc.)
 127                  */
 128                 Capability(Module* mod, const std::string& Name)
 129                         : ServiceProvider(mod, Name, SERVICE_CUSTOM)
 130                         , active(true)
 131                         , manager(mod, "capmanager")
 132                 {
 133                         Unregister();
 134                 }
 135
 136                 ~Capability()
 137                 {
 138                         SetActive(false);
 139                 }
 140
 141                 void RegisterService() CXX11_OVERRIDE
 142                 {
 143                         manager.SetCaptureHook(this);
 144                         SetActive(true);
 145                 }
 146
 147                 /** Check whether a user has the capability turned on.
 148                  * This method is safe to call if the cap is unregistered and will return false.
 149                  * @param user User to check
 150                  * @return True if the user is using this capability, false otherwise
 151                  */
 152                 bool get(User* user) const
 153                 {
 154                         if (!IsRegistered())
 155                                 return false;
 156                         Ext caps = extitem->get(user);
 157                         return (caps & GetMask());
 158                 }
 159
 160                 /** Turn the capability on/off for a user. If the cap is not registered this method has no effect.
 161                  * @param user User to turn the cap on/off for
 162                  * @param val True to turn the cap on, false to turn it off
 163                  */
 164                 void set(User* user, bool val)
 165                 {
 166                         if (!IsRegistered())
 167                                 return;
 168                         Ext curr = extitem->get(user);
 169                         extitem->set(user, (val ? AddToMask(curr) : DelFromMask(curr)));
 170                 }
 171
 172                 /** Activate or deactivate the capability.
 173                  * If activating, the cap is marked as active and if the manager is available the cap is registered in the manager.
 174                  * If deactivating, the cap is marked as inactive and if it is registered, it will be unregistered.
 175                  * Users who had the cap turned on will have it turned off automatically.
 176                  * @param activate True to activate the cap, false to deactivate it
 177                  */
 178                 void SetActive(bool activate)
 179                 {
 180                         active = activate;
 181                         if (manager)
 182                         {
 183                                 if (activate)
 184                                         manager->AddCap(this);
 185                                 else
 186                                         manager->DelCap(this);
 187                         }
 188                 }
 189
 190                 /** Get the name of the capability that's used in the protocol
 191                  * @return Name of the capability as used in the protocol
 192                  */
 193                 const std::string& GetName() const { return name; }
 194
 195                 /** Check whether the capability is active. The cap must be active and registered to be used by users.
 196                  * @return True if the cap is active, false if it has been deactivated
 197                  */
 198                 bool IsActive() const { return active; }
 199
 200                 /** Check whether the capability is registered
 201                  * The cap must be active and the manager must be available for a cap to be registered.
 202                  * @return True if the cap is registered in the manager, false otherwise
 203                  */
 204                 bool IsRegistered() const { return (extitem != NULL); }
 205
 206                 /** Get the CAP negotiation protocol version of a user.
 207                  * The cap must be registered for this to return anything other than CAP_LEGACY.
 208                  * @param user User whose negotiation protocol version to query
 209                  * @return One of the Capability::Protocol enum indicating the highest supported capability negotiation protocol version
 210                  */
 211                 Protocol GetProtocol(LocalUser* user) const
 212                 {
 213                         return ((IsRegistered() && (extitem->get(user) & CAP_302_BIT)) ? CAP_302 : CAP_LEGACY);
 214                 }
 215
 216                 /** Called when a user requests to turn this capability on or off.
 217                  * @param user User requesting to change the state of the cap
 218                  * @param add True if requesting to turn the cap on, false if requesting to turn it off
 219                  * @return True to allow the request, false to reject it
 220                  */
 221                 virtual bool OnRequest(LocalUser* user, bool add)
 222                 {
 223                         return true;
 224                 }
 225
 226                 /** Called when a user requests a list of all capabilities and this capability is about to be included in the list.
 227                  * The default behavior always includes the cap in the list.
 228                  * @param user User querying a list capabilities
 229                  * @return True to add this cap to the list sent to the user, false to not list it
 230                  */
 231                 virtual bool OnList(LocalUser* user)
 232                 {
 233                         return true;
 234                 }
 235         };
 236 }