include/extensible.h

   1 /*
   2  * InspIRCd -- Internet Relay Chat Daemon
   3  *
   4  *   Copyright (C) 2009 Daniel De Graaf <danieldg@inspircd.org>
   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 /** DEPRECATED: use {To,From}{Human,Internal,Network} instead. */
  23 enum SerializeFormat
  24 {
  25         FORMAT_USER,
  26         FORMAT_INTERNAL,
  27         FORMAT_NETWORK,
  28         FORMAT_PERSIST
  29 };
  30
  31 /** Base class for logic that extends an Extensible object. */
  32 class CoreExport ExtensionItem : public ServiceProvider, public usecountbase
  33 {
  34  public:
  35         /** Types of Extensible that an ExtensionItem can apply to. */
  36         enum ExtensibleType
  37         {
  38                 /** The ExtensionItem applies to a User object. */
  39                 EXT_USER,
  40
  41                 /** The ExtensionItem applies to a Channel object. */
  42                 EXT_CHANNEL,
  43
  44                 /** The ExtensionItem applies to a Membership object. */
  45                 EXT_MEMBERSHIP
  46         };
  47
  48         /** The type of Extensible that this ExtensionItem applies to. */
  49         const ExtensibleType type;
  50
  51         /** Initializes an instance of the ExtensionItem class.
  52          * @param key The name of the extension item (e.g. ssl_cert).
  53          * @param exttype The type of Extensible that this ExtensionItem applies to.
  54          * @param owner The module which created this ExtensionItem
  55          */
  56         ExtensionItem(const std::string& key, ExtensibleType exttype, Module* owner);
  57
  58         /** Destroys an instance of the ExtensionItem class. */
  59         virtual ~ExtensionItem();
  60
  61         /** Sets an ExtensionItem using a value in the internal format.
  62          * @param container A container the ExtensionItem should be set on.
  63          * @param value A value in the internal format.
  64          */
  65         virtual void FromInternal(Extensible* container, const std::string& value);
  66
  67         /** Sets an ExtensionItem using a value in the network format.
  68          * @param container A container the ExtensionItem should be set on.
  69          * @param value A value in the network format.
  70          */
  71         virtual void FromNetwork(Extensible* container, const std::string& value);
  72
  73         /** Gets an ExtensionItem's value in a human-readable format.
  74          * @param container The container the ExtensionItem is set on.
  75          * @param item The value to convert to a human-readable format.
  76          * @return The value specified in \p item in a human readable format.
  77          */
  78         virtual std::string ToHuman(const Extensible* container, void* item) const;
  79         /** Gets an ExtensionItem's value in the internal format.
  80          * @param container The container the ExtensionItem is set on.
  81          * @param item The value to convert to the internal format.
  82          * @return The value specified in \p item in the internal format.
  83          */
  84         virtual std::string ToInternal(const Extensible* container, void* item) const ;
  85
  86         /** Gets an ExtensionItem's value in the network format.
  87          * @param container The container the ExtensionItem is set on.
  88          * @param item The value to convert to the network format.
  89          * @return The value specified in \p item in the network format.
  90          */
  91         virtual std::string ToNetwork(const Extensible* container, void* item) const;
  92
  93         /** Deallocates the specified ExtensionItem value.
  94          * @param container The container that the ExtensionItem is set on.
  95          * @param item The item to deallocate.
  96          */
  97         virtual void free(Extensible* container, void* item) = 0;
  98
  99         /** Registers this object with the ExtensionManager. */
 100         void RegisterService() CXX11_OVERRIDE;
 101
 102         /** DEPRECATED: use To{Human,Internal,Network} instead. */
 103         DEPRECATED_METHOD(virtual std::string serialize(SerializeFormat format, const Extensible* container, void* item) const);
 104
 105         /** DEPRECATED: use From{Internal,Network} instead. */
 106         DEPRECATED_METHOD(virtual void unserialize(SerializeFormat format, Extensible* container, const std::string& value));
 107
 108  protected:
 109         /** Retrieves the value for this ExtensionItem from the internal map.
 110          * @param container The container that the ExtensionItem is set on.
 111          * @return Either the value of this ExtensionItem or NULL if it is not set.
 112          */
 113         void* get_raw(const Extensible* container) const;
 114
 115         /** Stores a value for this ExtensionItem in the internal map and returns the old value if one was set.
 116          * @param container A container the ExtensionItem should be set on.
 117          * @param value The value to set on the specified container.
 118          * @return Either the old value or NULL if one is not set.
 119          */
 120         void* set_raw(Extensible* container, void* value);
 121
 122         /** Removes the value for this ExtensionItem from the internal map and returns it.
 123          * @param container A container the ExtensionItem should be removed from.
 124          * @return Either the old value or NULL if one is not set.
 125         */
 126         void* unset_raw(Extensible* container);
 127 };
 128
 129 /** class Extensible is the parent class of many classes such as User and Channel.
 130  * class Extensible implements a system which allows modules to 'extend' the class by attaching data within
 131  * a map associated with the object. In this way modules can store their own custom information within user
 132  * objects, channel objects and server objects, without breaking other modules (this is more sensible than using
 133  * a flags variable, and each module defining bits within the flag as 'theirs' as it is less prone to conflict and
 134  * supports arbitary data storage).
 135  */
 136 class CoreExport Extensible : public classbase
 137 {
 138  public:
 139         typedef insp::flat_map<reference<ExtensionItem>, void*> ExtensibleStore;
 140
 141         // Friend access for the protected getter/setter
 142         friend class ExtensionItem;
 143  private:
 144         /** Private data store.
 145          * Holds all extensible metadata for the class.
 146          */
 147         ExtensibleStore extensions;
 148
 149         /** True if this Extensible has been culled.
 150          * A warning is generated if false on destruction.
 151          */
 152         unsigned int culled:1;
 153  public:
 154         /**
 155          * Get the extension items for iteraton (i.e. for metadata sync during netburst)
 156          */
 157         inline const ExtensibleStore& GetExtList() const { return extensions; }
 158
 159         Extensible();
 160         CullResult cull() CXX11_OVERRIDE;
 161         virtual ~Extensible();
 162         void doUnhookExtensions(const std::vector<reference<ExtensionItem> >& toRemove);
 163
 164         /**
 165          * Free all extension items attached to this Extensible
 166          */
 167         void FreeAllExtItems();
 168 };
 169
 170 class CoreExport ExtensionManager
 171 {
 172  public:
 173         typedef std::map<std::string, reference<ExtensionItem> > ExtMap;
 174
 175         bool Register(ExtensionItem* item);
 176         void BeginUnregister(Module* module, std::vector<reference<ExtensionItem> >& list);
 177         ExtensionItem* GetItem(const std::string& name);
 178
 179         /** Get all registered extensions keyed by their names
 180          * @return Const map of ExtensionItem pointers keyed by their names
 181          */
 182         const ExtMap& GetExts() const { return types; }
 183
 184  private:
 185         ExtMap types;
 186 };
 187
 188 /** DEPRECATED: use ExtensionItem instead. */
 189 typedef ExtensionItem LocalExtItem;
 190
 191 template <typename T, typename Del = stdalgo::defaultdeleter<T> >
 192 class SimpleExtItem : public ExtensionItem
 193 {
 194  public:
 195         SimpleExtItem(const std::string& Key, ExtensibleType exttype, Module* parent)
 196                 : ExtensionItem(Key, exttype, parent)
 197         {
 198         }
 199
 200         virtual ~SimpleExtItem()
 201         {
 202         }
 203
 204         inline T* get(const Extensible* container) const
 205         {
 206                 return static_cast<T*>(get_raw(container));
 207         }
 208
 209         inline void set(Extensible* container, const T& value)
 210         {
 211                 T* ptr = new T(value);
 212                 T* old = static_cast<T*>(set_raw(container, ptr));
 213                 free(container, old);
 214         }
 215
 216         inline void set(Extensible* container, T* value)
 217         {
 218                 T* old = static_cast<T*>(set_raw(container, value));
 219                 free(container, old);
 220         }
 221
 222         inline void unset(Extensible* container)
 223         {
 224                 T* old = static_cast<T*>(unset_raw(container));
 225                 free(container, old);
 226         }
 227
 228         void free(Extensible* container, void* item) CXX11_OVERRIDE
 229         {
 230                 Del del;
 231                 del(static_cast<T*>(item));
 232         }
 233 };
 234
 235 class CoreExport LocalStringExt : public SimpleExtItem<std::string>
 236 {
 237  public:
 238         LocalStringExt(const std::string& key, ExtensibleType exttype, Module* owner);
 239         virtual ~LocalStringExt();
 240         std::string ToInternal(const Extensible* container, void* item) const CXX11_OVERRIDE;
 241         void FromInternal(Extensible* container, const std::string& value) CXX11_OVERRIDE;
 242 };
 243
 244 class CoreExport LocalIntExt : public ExtensionItem
 245 {
 246  public:
 247         LocalIntExt(const std::string& key, ExtensibleType exttype, Module* owner);
 248         virtual ~LocalIntExt();
 249         std::string ToInternal(const Extensible* container, void* item) const CXX11_OVERRIDE;
 250         void FromInternal(Extensible* container, const std::string& value) CXX11_OVERRIDE;
 251         intptr_t get(const Extensible* container) const;
 252         intptr_t set(Extensible* container, intptr_t value);
 253         void unset(Extensible* container) { set(container, 0); }
 254         void free(Extensible* container, void* item) CXX11_OVERRIDE;
 255 };
 256
 257 class CoreExport StringExtItem : public ExtensionItem
 258 {
 259  public:
 260         StringExtItem(const std::string& key, ExtensibleType exttype, Module* owner);
 261         virtual ~StringExtItem();
 262         std::string* get(const Extensible* container) const;
 263         std::string ToNetwork(const Extensible* container, void* item) const CXX11_OVERRIDE;
 264         void FromNetwork(Extensible* container, const std::string& value) CXX11_OVERRIDE;
 265         void set(Extensible* container, const std::string& value);
 266         void unset(Extensible* container);
 267         void free(Extensible* container, void* item) CXX11_OVERRIDE;
 268 };