dvander@372: /**
dvander@375:  * vim: set ts=4 :
dvander@372:  * ===============================================================
dvander@376:  * SourceMod, Copyright (C) 2004-2007 AlliedModders LLC. 
dvander@376:  * All rights reserved.
dvander@372:  * ===============================================================
dvander@372:  *
dvander@379:  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be 
dvander@379:  * used or modified under the Terms and Conditions of its License Agreement, 
dvander@379:  * which is found in public/licenses/LICENSE.txt.  As of this notice, derivative 
dvander@379:  * works must be licensed under the GNU General Public License (version 2 or 
dvander@379:  * greater).  A copy of the GPL is included under public/licenses/GPL.txt.
dvander@379:  * 
dvander@379:  * To view the latest information, see: http://www.sourcemod.net/license.php
dvander@372:  *
dvander@372:  * Version: $Id$
dvander@372:  */
dvander@372: 
dvander@324: #ifndef _INCLUDE_SOURCEMOD_IFACE_SHARE_SYS_H_
dvander@324: #define _INCLUDE_SOURCEMOD_IFACE_SHARE_SYS_H_
dvander@324: 
dvander@372: /**
dvander@372:  * @file IShareSys.h
dvander@372:  * @brief Defines the Share System, responsible for shared resources and dependencies.
dvander@372:  *
dvander@372:  *  The Share System also manages the Identity_t data type, although this is internally
dvander@372:  * implemented with the Handle System.
dvander@372:  */
dvander@372: 
dvander@324: #include <sp_vm_types.h>
dvander@324: 
dvander@324: 
dvander@324: namespace SourceMod
dvander@324: {
dvander@324: 	class IExtension;
dvander@324: 	struct IdentityToken_t;
dvander@372: 
dvander@372: 	/** Forward declaration from IHandleSys.h */
dvander@324: 	typedef unsigned int		HandleType_t;
dvander@372: 
dvander@372: 	/** Forward declaration from IHandleSys.h */
dvander@324: 	typedef HandleType_t		IdentityType_t;
dvander@372: 
dvander@324: 	/**
dvander@324: 	 * @brief Defines the base functionality required by a shared interface.
dvander@324: 	 */
dvander@324: 	class SMInterface
dvander@324: 	{
dvander@324: 	public:
dvander@324: 		/**
dvander@324: 		 * @brief Must return an integer defining the interface's version.
dvander@324: 		 */
dvander@324: 		virtual unsigned int GetInterfaceVersion() =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Must return a string defining the interface's unique name.
dvander@324: 		 */
dvander@324: 		virtual const char *GetInterfaceName() =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Must return whether the requested version number is backwards comaptible.
dvander@324: 		 * Note: This can be overridden for breaking changes or custom versioning.
dvander@324: 		 * 
dvander@324: 		 * @param version		Version number to compare against.
dvander@324: 		 * @return				True if compatible, false otherwise.
dvander@324: 		 */
dvander@324: 		virtual bool IsVersionCompatible(unsigned int version)
dvander@324: 		{
dvander@324: 			if (version > GetInterfaceVersion())
dvander@324: 			{
dvander@324: 				return false;
dvander@324: 			}
dvander@324: 
dvander@324: 			return true;
dvander@324: 		}
dvander@324: 	};
dvander@324: 
dvander@324: 	/**
dvander@324: 	 * @brief Tracks dependencies and fires dependency listeners.
dvander@324: 	 */
dvander@324: 	class IShareSys
dvander@324: 	{
dvander@324: 	public:
dvander@324: 		/**
dvander@324: 		 * @brief Adds an interface to the global interface system.
dvander@324: 		 *
dvander@324: 		 * @param myself		Object adding this interface, in order to track dependencies.
dvander@324: 		 * @param iface			Interface pointer (must be unique).
dvander@324: 		 * @return				True on success, false otherwise.
dvander@324: 		 */
dvander@324: 		virtual bool AddInterface(IExtension *myself, SMInterface *iface) =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Requests an interface from the global interface system.
dvander@324: 		 * If found, the interface's internal reference count will be increased.
dvander@324: 		 *
dvander@324: 		 * @param iface_name	Interface name.
dvander@324: 		 * @param iface_vers	Interface version to attempt to match.
dvander@324: 		 * @param myself		Object requesting this interface, in order to track dependencies.
dvander@324: 		 * @param pIface		Pointer to store the return value in.
dvander@324: 		 */
dvander@324: 		virtual bool RequestInterface(const char *iface_name, 
dvander@324: 										unsigned int iface_vers,
dvander@324: 										IExtension *myself,
dvander@324: 										SMInterface **pIface) =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Adds a list of natives to the global native pool, to be bound on plugin load.
dvander@324: 		 * NOTE: Adding natives currently does not bind them to any loaded plugins.
dvander@324: 		 * You must manually bind late natives.
dvander@324: 		 * 
dvander@372: 		 * @param myself		Identity token of parent object.
dvander@324: 		 * @param natives		Array of natives to add.  The last entry must have NULL members.
dvander@324: 		 */
dvander@324: 		virtual void AddNatives(IExtension *myself, const sp_nativeinfo_t *natives) =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Creates a new identity type.
dvander@324: 		 * NOTE: Module authors should never need to use this.  Due to the current implementation,
dvander@324: 		 * there is a hardcoded limit of 15 types.  Core uses up a few, so think carefully!
dvander@324: 		 *
dvander@324: 		 * @param name			String containing type name.  Must not be empty or NULL.
dvander@324: 		 * @return				A new HandleType_t identifier, or 0 on failure.
dvander@324: 		 */
dvander@324: 		virtual IdentityType_t CreateIdentType(const char *name) =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Finds an identity type by name.
dvander@324: 		 * DEFAULT IDENTITY TYPES:
dvander@324: 		 *  "PLUGIN"	- An IPlugin object.
dvander@324: 		 *  "MODULE"	- An IModule object.
dvander@324: 		 *  "CORE"		- An SMGlobalClass or other singleton.
dvander@324: 		 * 
dvander@324: 		 * @param name			String containing type name to search for.
dvander@324: 		 * @return				A HandleType_t identifier if found, 0 otherwise.
dvander@324: 		 */
dvander@324: 		virtual IdentityType_t FindIdentType(const char *name) =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Creates a new identity token.  This token is guaranteed to be unique
dvander@324: 		 * amongst all other open identities.
dvander@324: 		 *
dvander@324: 		 * @param type			Identity type.
dvander@324: 		 * @return				A new IdentityToken_t identifier.
dvander@324: 		 */
dvander@324: 		virtual IdentityToken_t *CreateIdentity(IdentityType_t type) =0;
dvander@324: 
dvander@324: 		/** 
dvander@324: 		 * @brief Destroys an identity type.  Note that this will delete any identities
dvander@324: 		 * that are under this type.  
dvander@324: 		 *
dvander@324: 		 * @param type			Identity type.
dvander@324: 		 */
dvander@324: 		virtual void DestroyIdentType(IdentityType_t type) =0;
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Destroys an identity token.  Any handles being owned by this token, or
dvander@324: 		 * any handles being 
dvander@324: 		 *
dvander@324: 		 * @param identity		Identity to remove.
dvander@324: 		 */
dvander@324: 		virtual void DestroyIdentity(IdentityToken_t *identity) =0;
dvander@324: 
dvander@324: 
dvander@324: 		/**
dvander@324: 		 * @brief Requires an extension.  This tells SourceMod that without this extension,
dvander@324: 		 * your extension should not be loaded.  The name should not include the ".dll" or
dvander@324: 		 * the ".so" part of the file name.
dvander@324: 		 *
dvander@324: 		 * @param myself		IExtension pointer to yourself.
dvander@324: 		 * @param filename		File of extension to require.
dvander@324: 		 * @param require		Whether or not this extension is a required dependency.
dvander@324: 		 * @param autoload		Whether or not to autoload this extension.
dvander@324: 		 */
dvander@324: 		virtual void AddDependency(IExtension *myself, const char *filename, bool require, bool autoload) =0;
dvander@324: 	};
ds@432: }
dvander@324: 
dvander@324: #endif //_INCLUDE_SOURCEMOD_IFACE_SHARE_SYS_H_