00001 /** 00002 * vim: set ts=4 : 00003 * ============================================================================= 00004 * SourceMod 00005 * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved. 00006 * ============================================================================= 00007 * 00008 * This program is free software; you can redistribute it and/or modify it under 00009 * the terms of the GNU General Public License, version 3.0, as published by the 00010 * Free Software Foundation. 00011 * 00012 * This program is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00014 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 00015 * details. 00016 * 00017 * You should have received a copy of the GNU General Public License along with 00018 * this program. If not, see <http://www.gnu.org/licenses/>. 00019 * 00020 * As a special exception, AlliedModders LLC gives you permission to link the 00021 * code of this program (as well as its derivative works) to "Half-Life 2," the 00022 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software 00023 * by the Valve Corporation. You must obey the GNU General Public License in 00024 * all respects for all other code used. Additionally, AlliedModders LLC grants 00025 * this exception to all derivative works. AlliedModders LLC defines further 00026 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007), 00027 * or <http://www.sourcemod.net/license.php>. 00028 * 00029 * Version: $Id$ 00030 */ 00031 00032 #ifndef _INCLUDE_SOURCEMOD_IFACE_SHARE_SYS_H_ 00033 #define _INCLUDE_SOURCEMOD_IFACE_SHARE_SYS_H_ 00034 00035 /** 00036 * @file IShareSys.h 00037 * @brief Defines the Share System, responsible for shared resources and dependencies. 00038 */ 00039 00040 #include <sp_vm_types.h> 00041 00042 00043 namespace SourceMod 00044 { 00045 class IExtension; 00046 struct IdentityToken_t; 00047 00048 /** Forward declaration from IHandleSys.h */ 00049 typedef unsigned int HandleType_t; 00050 00051 /** Forward declaration from IHandleSys.h */ 00052 typedef HandleType_t IdentityType_t; 00053 00054 /** 00055 * @brief Types of features. 00056 */ 00057 enum FeatureType 00058 { 00059 FeatureType_Native, /**< Native functions for plugins. */ 00060 FeatureType_Capability /**< Named capabilities. */ 00061 }; 00062 00063 /** 00064 * @brief Feature presence status codes. 00065 */ 00066 enum FeatureStatus 00067 { 00068 FeatureStatus_Available = 0, /**< Feature is available for use. */ 00069 FeatureStatus_Unavailable, /**< Feature is unavailable, but known. */ 00070 FeatureStatus_Unknown /**< Feature is not known. */ 00071 }; 00072 00073 /** 00074 * @brief Provides a capability feature. 00075 */ 00076 class IFeatureProvider 00077 { 00078 public: 00079 /** 00080 * @brief Must return whether a capability is present. 00081 * 00082 * @param type Feature type (FeatureType_Capability right now). 00083 * @param name Feature name. 00084 * @return Feature status code. 00085 */ 00086 virtual FeatureStatus GetFeatureStatus(FeatureType type, const char *name) = 0; 00087 }; 00088 00089 /** 00090 * @brief Defines the base functionality required by a shared interface. 00091 */ 00092 class SMInterface 00093 { 00094 public: 00095 /** 00096 * @brief Must return an integer defining the interface's version. 00097 */ 00098 virtual unsigned int GetInterfaceVersion() =0; 00099 00100 /** 00101 * @brief Must return a string defining the interface's unique name. 00102 */ 00103 virtual const char *GetInterfaceName() =0; 00104 00105 /** 00106 * @brief Must return whether the requested version number is backwards compatible. 00107 * Note: This can be overridden for breaking changes or custom versioning. 00108 * 00109 * @param version Version number to compare against. 00110 * @return True if compatible, false otherwise. 00111 */ 00112 virtual bool IsVersionCompatible(unsigned int version) 00113 { 00114 if (version > GetInterfaceVersion()) 00115 { 00116 return false; 00117 } 00118 00119 return true; 00120 } 00121 }; 00122 00123 /** 00124 * @brief Tracks dependencies and fires dependency listeners. 00125 */ 00126 class IShareSys 00127 { 00128 public: 00129 /** 00130 * @brief Adds an interface to the global interface system. 00131 * 00132 * @param myself Object adding this interface, in order to track dependencies. 00133 * @param iface Interface pointer (must be unique). 00134 * @return True on success, false otherwise. 00135 */ 00136 virtual bool AddInterface(IExtension *myself, SMInterface *iface) =0; 00137 00138 /** 00139 * @brief Requests an interface from the global interface system. 00140 * If found, the interface's internal reference count will be increased. 00141 * 00142 * @param iface_name Interface name. 00143 * @param iface_vers Interface version to attempt to match. 00144 * @param myself Object requesting this interface, in order to track dependencies. 00145 * @param pIface Pointer to store the return value in. 00146 */ 00147 virtual bool RequestInterface(const char *iface_name, 00148 unsigned int iface_vers, 00149 IExtension *myself, 00150 SMInterface **pIface) =0; 00151 00152 /** 00153 * @brief Adds a list of natives to the global native pool, to be 00154 * bound on plugin load. 00155 * 00156 * Adding natives does not bind them to any loaded plugins; the 00157 * plugins must be reloaded for new natives to take effect. 00158 * 00159 * @param myself Identity token of parent object. 00160 * @param natives Array of natives to add. The last entry in 00161 * the array must be filled with NULLs to 00162 * terminate the array. The array must be static 00163 * as Core will cache the pointer for the 00164 * lifetime of the extension. 00165 */ 00166 virtual void AddNatives(IExtension *myself, const sp_nativeinfo_t *natives) =0; 00167 00168 /** 00169 * @brief Creates a new identity type. 00170 * NOTE: Module authors should never need to use this. Due to the current implementation, 00171 * there is a hardcoded limit of 15 types. Core uses up a few, so think carefully! 00172 * 00173 * @param name String containing type name. Must not be empty or NULL. 00174 * @return A new HandleType_t identifier, or 0 on failure. 00175 */ 00176 virtual IdentityType_t CreateIdentType(const char *name) =0; 00177 00178 /** 00179 * @brief Finds an identity type by name. 00180 * DEFAULT IDENTITY TYPES: 00181 * "PLUGIN" - An IPlugin object. 00182 * "MODULE" - An IModule object. 00183 * "CORE" - An SMGlobalClass or other singleton. 00184 * 00185 * @param name String containing type name to search for. 00186 * @return A HandleType_t identifier if found, 0 otherwise. 00187 */ 00188 virtual IdentityType_t FindIdentType(const char *name) =0; 00189 00190 /** 00191 * @brief Creates a new identity token. This token is guaranteed to be 00192 * unique amongst all other open identities. 00193 * 00194 * @param type Identity type. 00195 * @param ptr Private data pointer (cannot be NULL). 00196 * @return A new IdentityToken_t pointer, or NULL on failure. 00197 */ 00198 virtual IdentityToken_t *CreateIdentity(IdentityType_t type, void *ptr) =0; 00199 00200 /** 00201 * @brief Destroys an identity type. Note that this will delete any identities 00202 * that are under this type. 00203 * 00204 * @param type Identity type. 00205 */ 00206 virtual void DestroyIdentType(IdentityType_t type) =0; 00207 00208 /** 00209 * @brief Destroys an identity token. Any handles being owned by this token, or 00210 * any handles being 00211 * 00212 * @param identity Identity to remove. 00213 */ 00214 virtual void DestroyIdentity(IdentityToken_t *identity) =0; 00215 00216 /** 00217 * @brief Requires an extension. This tells SourceMod that without this extension, 00218 * your extension should not be loaded. The name should not include the ".dll" or 00219 * the ".so" part of the file name. 00220 * 00221 * @param myself IExtension pointer to yourself. 00222 * @param filename File of extension to require. 00223 * @param require Whether or not this extension is a required dependency. 00224 * @param autoload Whether or not to autoload this extension. 00225 */ 00226 virtual void AddDependency(IExtension *myself, const char *filename, bool require, bool autoload) =0; 00227 00228 /** 00229 * @brief Registers a library name to an extension. 00230 * 00231 * @param myself Extension to register library to. 00232 * @param name Library name. 00233 */ 00234 virtual void RegisterLibrary(IExtension *myself, const char *name) =0; 00235 00236 /** 00237 * @brief Adds natives that will override Core natives when called. 00238 * 00239 * A Core version of each native must exist. If one does not, then 00240 * Core will simply ignore that entry. No more than one override 00241 * can exist on a given native. 00242 * 00243 * Override natives represent a weak coupling. If the extension is 00244 * unloaded, the native will be re-bound to the Core version. If 00245 * the extension is loaded after plugins are loaded, the override 00246 * will not take effect until those plugins are reloaded. 00247 * 00248 * @param myself Identity token of parent object. 00249 * @param natives Array of natives to add. The last entry in 00250 * the array must be filled with NULLs to 00251 * terminate the array. The array must be static 00252 * as Core will cache the pointer for the 00253 * lifetime of the extension. 00254 */ 00255 virtual void OverrideNatives(IExtension *myself, const sp_nativeinfo_t *natives) =0; 00256 00257 /** 00258 * @brief Adds a capability provider. Feature providers are used by 00259 * plugins to determine if a feature exists at runtime. This is 00260 * distinctly different from checking for a native, because natives 00261 * may be backed by underlying functionality which is not available. 00262 * 00263 * @param myself Extension. 00264 * @param provider Feature provider implementation. 00265 * @param name Capibility name. 00266 */ 00267 virtual void AddCapabilityProvider(IExtension *myself, 00268 IFeatureProvider *provider, 00269 const char *name) =0; 00270 00271 /** 00272 * @brief Drops a previously added cap provider. 00273 * 00274 * @param myself Extension. 00275 * @param provider Feature provider implementation. 00276 * @param name Capibility name. 00277 */ 00278 virtual void DropCapabilityProvider(IExtension *myself, 00279 IFeatureProvider *provider, 00280 const char *name) =0; 00281 }; 00282 } 00283 00284 #endif //_INCLUDE_SOURCEMOD_IFACE_SHARE_SYS_H_
1.7.1