1.1 --- a/public/IHandleSys.h Fri Mar 28 06:21:34 2008 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,346 +0,0 @@
1.4 -/**
1.5 - * vim: set ts=4 :
1.6 - * =============================================================================
1.7 - * SourceMod
1.8 - * Copyright (C) 2004-2007 AlliedModders LLC. All rights reserved.
1.9 - * =============================================================================
1.10 - *
1.11 - * This program is free software; you can redistribute it and/or modify it under
1.12 - * the terms of the GNU General Public License, version 3.0, as published by the
1.13 - * Free Software Foundation.
1.14 - *
1.15 - * This program is distributed in the hope that it will be useful, but WITHOUT
1.16 - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.17 - * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.18 - * details.
1.19 - *
1.20 - * You should have received a copy of the GNU General Public License along with
1.21 - * this program. If not, see <http://www.gnu.org/licenses/>.
1.22 - *
1.23 - * As a special exception, AlliedModders LLC gives you permission to link the
1.24 - * code of this program (as well as its derivative works) to "Half-Life 2," the
1.25 - * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.26 - * by the Valve Corporation. You must obey the GNU General Public License in
1.27 - * all respects for all other code used. Additionally, AlliedModders LLC grants
1.28 - * this exception to all derivative works. AlliedModders LLC defines further
1.29 - * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.30 - * or <http://www.sourcemod.net/license.php>.
1.31 - *
1.32 - * Version: $Id$
1.33 - */
1.34 -
1.35 -#ifndef _INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_
1.36 -#define _INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_
1.37 -
1.38 -/**
1.39 - * @file IHandleSys.h
1.40 - * @brief Defines the interface for creating, reading, and removing Handles.
1.41 - *
1.42 - * The Handle system abstracts generic pointers into typed objects represented by
1.43 - * 32bit codes. This is extremely useful for verifying data integrity and cross-platform
1.44 - * support in SourcePawn scripts. When a Plugin unloads, all its Handles are freed, ensuring
1.45 - * that no memory leaks are present, They have reference counts and thus can be duplicated,
1.46 - * or cloned, and are safe to pass between Plugins even if one is unloaded.
1.47 - *
1.48 - * Handles are created with a given type (custom types may be created). They can have
1.49 - * per-Identity permissions for deletion, reading, and cloning. They also support generic
1.50 - * operations. For example, deleting a Handle will call that type's destructor on the generic
1.51 - * pointer, making cleanup easier for users and eliminating memory leaks.
1.52 - */
1.53 -
1.54 -#include <IShareSys.h>
1.55 -#include <sp_vm_types.h>
1.56 -
1.57 -#define SMINTERFACE_HANDLESYSTEM_NAME "IHandleSys"
1.58 -#define SMINTERFACE_HANDLESYSTEM_VERSION 2
1.59 -
1.60 -/** Specifies no Identity */
1.61 -#define DEFAULT_IDENTITY NULL
1.62 -/** Specifies no Type. This is invalid for everything but reading a Handle. */
1.63 -#define NO_HANDLE_TYPE 0
1.64 -/** Specifies an invalid/NULL Handle */
1.65 -#define BAD_HANDLE 0
1.66 -
1.67 -namespace SourceMod
1.68 -{
1.69 - /**
1.70 - * @brief Represents a Handle Type ID.
1.71 - */
1.72 - typedef unsigned int HandleType_t;
1.73 -
1.74 - /**
1.75 - * @brief Represents a Handle ID.
1.76 - */
1.77 - typedef unsigned int Handle_t;
1.78 -
1.79 -
1.80 - /*
1.81 - * About type checking:
1.82 - * Types can be inherited - a Parent type ("Supertype") can have child types.
1.83 - * When accessing handles, type checking is done. This table shows how this is resolved:
1.84 - *
1.85 - * HANDLE CHECK -> RESULT
1.86 - * ------ ----- ------
1.87 - * Parent Parent Success
1.88 - * Parent Child Fail
1.89 - * Child Parent Success
1.90 - * Child Child Success
1.91 - */
1.92 -
1.93 - /**
1.94 - * @brief Lists the possible handle error codes.
1.95 - */
1.96 - enum HandleError
1.97 - {
1.98 - HandleError_None = 0, /**< No error */
1.99 - HandleError_Changed, /**< The handle has been freed and reassigned */
1.100 - HandleError_Type, /**< The handle has a different type registered */
1.101 - HandleError_Freed, /**< The handle has been freed */
1.102 - HandleError_Index, /**< generic internal indexing error */
1.103 - HandleError_Access, /**< No access permitted to free this handle */
1.104 - HandleError_Limit, /**< The limited number of handles has been reached */
1.105 - HandleError_Identity, /**< The identity token was not usable */
1.106 - HandleError_Owner, /**< Owners do not match for this operation */
1.107 - HandleError_Version, /**< Unrecognized security structure version */
1.108 - HandleError_Parameter, /**< An invalid parameter was passed */
1.109 - HandleError_NoInherit, /**< This type cannot be inherited */
1.110 - };
1.111 -
1.112 - /**
1.113 - * @brief Lists access rights specific to a type.
1.114 - */
1.115 - enum HTypeAccessRight
1.116 - {
1.117 - HTypeAccess_Create = 0, /**< Handles of this type can be created (DEFAULT=false) */
1.118 - HTypeAccess_Inherit, /**< Sub-types can inherit this type (DEFAULT=false) */
1.119 - /* -------------- */
1.120 - HTypeAccess_TOTAL, /**< Total number of type access rights */
1.121 - };
1.122 -
1.123 - /**
1.124 - * @brief Lists access rights specific to a Handle.
1.125 - *
1.126 - * These rights are exclusive. For example, you do not need "read" access to delete or clone.
1.127 - */
1.128 - enum HandleAccessRight
1.129 - {
1.130 - HandleAccess_Read, /**< Can be read (DEFAULT=ident only) */
1.131 - HandleAccess_Delete, /**< Can be deleted (DEFAULT=owner only) */
1.132 - HandleAccess_Clone, /**< Can be cloned (DEFAULT=any) */
1.133 - /* ------------- */
1.134 - HandleAccess_TOTAL, /**< Total number of access rights */
1.135 - };
1.136 -
1.137 - /** Access is restricted to the identity */
1.138 - #define HANDLE_RESTRICT_IDENTITY (1<<0)
1.139 - /** Access is restricted to the owner */
1.140 - #define HANDLE_RESTRICT_OWNER (1<<1)
1.141 -
1.142 - /**
1.143 - * @brief This is used to define per-type access rights.
1.144 - */
1.145 - struct TypeAccess
1.146 - {
1.147 - /** Constructor */
1.148 - TypeAccess()
1.149 - {
1.150 - hsVersion = SMINTERFACE_HANDLESYSTEM_VERSION;
1.151 - }
1.152 - unsigned int hsVersion; /**< Handle API version */
1.153 - IdentityToken_t *ident; /**< Identity owning this type */
1.154 - bool access[HTypeAccess_TOTAL]; /**< Access array */
1.155 - };
1.156 -
1.157 - /**
1.158 - * @brief This is used to define per-Handle access rights.
1.159 - */
1.160 - struct HandleAccess
1.161 - {
1.162 - /** Constructor */
1.163 - HandleAccess()
1.164 - {
1.165 - hsVersion = SMINTERFACE_HANDLESYSTEM_VERSION;
1.166 - }
1.167 - unsigned int hsVersion; /**< Handle API version */
1.168 - unsigned int access[HandleAccess_TOTAL]; /**< Access array */
1.169 - };
1.170 -
1.171 - /**
1.172 - * @brief This pair of tokens is used for identification.
1.173 - */
1.174 - struct HandleSecurity
1.175 - {
1.176 - HandleSecurity()
1.177 - {
1.178 - }
1.179 - HandleSecurity(IdentityToken_t *owner, IdentityToken_t *identity)
1.180 - : pOwner(owner), pIdentity(identity)
1.181 - {
1.182 - }
1.183 - IdentityToken_t *pOwner; /**< Owner of the Handle */
1.184 - IdentityToken_t *pIdentity; /**< Owner of the Type */
1.185 - };
1.186 -
1.187 - /**
1.188 - * @brief Hooks type-specific Handle operations.
1.189 - */
1.190 - class IHandleTypeDispatch
1.191 - {
1.192 - public:
1.193 - /** Returns the Handle API version */
1.194 - virtual unsigned int GetDispatchVersion()
1.195 - {
1.196 - return SMINTERFACE_HANDLESYSTEM_VERSION;
1.197 - }
1.198 - public:
1.199 - /**
1.200 - * @brief Called when destroying a handle. Must be implemented.
1.201 - */
1.202 - virtual void OnHandleDestroy(HandleType_t type, void *object) =0;
1.203 - };
1.204 -
1.205 - /**
1.206 - * @brief Provides functions for managing Handles.
1.207 - */
1.208 - class IHandleSys : public SMInterface
1.209 - {
1.210 - public:
1.211 - virtual unsigned int GetInterfaceVersion()
1.212 - {
1.213 - return SMINTERFACE_HANDLESYSTEM_VERSION;
1.214 - }
1.215 - virtual const char *GetInterfaceName()
1.216 - {
1.217 - return SMINTERFACE_HANDLESYSTEM_NAME;
1.218 - }
1.219 - public:
1.220 - /**
1.221 - * @brief Creates a new Handle type.
1.222 - * NOTE: Currently, a child type may not have its own children.
1.223 - * NOTE: Handle names must be unique if not private.
1.224 - *
1.225 - * @param name Name of handle type (NULL or "" to be anonymous)
1.226 - * @param dispatch Pointer to a valid IHandleTypeDispatch object.
1.227 - * @param parent Parent handle to inherit from, 0 for none.
1.228 - * @param typeAccess Pointer to a TypeAccess object, NULL to use default
1.229 - * or inherited permissions. Pointer can be temporary.
1.230 - * @param hndlAccess Pointer to a HandleAccess object to define default
1.231 - * default permissions on each Handle. NULL to use default
1.232 - * permissions.
1.233 - * @param ident Security token for any permissions. If typeAccess is NULL, this
1.234 - * becomes the owning identity.
1.235 - * @param err Optional pointer to store an error code.
1.236 - * @return A new HandleType_t unique ID, or 0 on failure.
1.237 - */
1.238 - virtual HandleType_t CreateType(const char *name,
1.239 - IHandleTypeDispatch *dispatch,
1.240 - HandleType_t parent,
1.241 - const TypeAccess *typeAccess,
1.242 - const HandleAccess *hndlAccess,
1.243 - IdentityToken_t *ident,
1.244 - HandleError *err) =0;
1.245 -
1.246 - /**
1.247 - * @brief Removes a handle type.
1.248 - * NOTE: This removes all child types.
1.249 - *
1.250 - * @param type Type chain to remove.
1.251 - * @param ident Identity token. Removal fails if the token does not match.
1.252 - * @return True on success, false on failure.
1.253 - */
1.254 - virtual bool RemoveType(HandleType_t type, IdentityToken_t *ident) =0;
1.255 -
1.256 - /**
1.257 - * @brief Finds a handle type by name.
1.258 - *
1.259 - * @param name Name of handle type to find (anonymous not allowed).
1.260 - * @param type Address to store found handle in (if not found, undefined).
1.261 - * @return True if found, false otherwise.
1.262 - */
1.263 - virtual bool FindHandleType(const char *name, HandleType_t *type) =0;
1.264 -
1.265 - /**
1.266 - * @brief Creates a new handle.
1.267 - *
1.268 - * @param type Type to use on the handle.
1.269 - * @param object Object to bind to the handle.
1.270 - * @param owner Owner of the new Handle (may be NULL).
1.271 - * @param ident Identity for type access if needed (may be NULL).
1.272 - * @param err Optional pointer to store an error code.
1.273 - * @return A new Handle_t, or 0 on failure.
1.274 - */
1.275 - virtual Handle_t CreateHandle(HandleType_t type,
1.276 - void *object,
1.277 - IdentityToken_t *owner,
1.278 - IdentityToken_t *ident,
1.279 - HandleError *err) =0;
1.280 -
1.281 - /**
1.282 - * @brief Frees the memory associated with a handle and calls any destructors.
1.283 - * NOTE: This function will decrement the internal reference counter. It will
1.284 - * only perform any further action if the counter hits 0.
1.285 - *
1.286 - * @param handle Handle_t identifier to destroy.
1.287 - * @param pSecurity Security information struct (may be NULL).
1.288 - * @return A HandleError error code.
1.289 - */
1.290 - virtual HandleError FreeHandle(Handle_t handle, const HandleSecurity *pSecurity) =0;
1.291 -
1.292 - /**
1.293 - * @brief Clones a handle by adding to its internal reference count. Its data,
1.294 - * type, and security permissions remain the same.
1.295 - *
1.296 - * @param handle Handle to duplicate. Any non-free handle target is valid.
1.297 - * @param newhandle Stores the duplicated handle in the pointer (must not be NULL).
1.298 - * @param newOwner New owner of cloned handle.
1.299 - * @param pSecurity Security information struct (may be NULL).
1.300 - * @return A HandleError error code.
1.301 - */
1.302 - virtual HandleError CloneHandle(Handle_t handle,
1.303 - Handle_t *newhandle,
1.304 - IdentityToken_t *newOwner,
1.305 - const HandleSecurity *pSecurity) =0;
1.306 -
1.307 - /**
1.308 - * @brief Retrieves the contents of a handle.
1.309 - *
1.310 - * @param handle Handle_t from which to retrieve contents.
1.311 - * @param type Expected type to read as. 0 ignores typing rules.
1.312 - * @param pSecurity Security information struct (may be NULL).
1.313 - * @param object Optional address to store object in.
1.314 - * @return HandleError error code.
1.315 - */
1.316 - virtual HandleError ReadHandle(Handle_t handle,
1.317 - HandleType_t type,
1.318 - const HandleSecurity *pSecurity,
1.319 - void **object) =0;
1.320 -
1.321 - /**
1.322 - * @brief Sets access permissions on one or more structures.
1.323 - *
1.324 - * @param pTypeAccess Optional TypeAccess buffer to initialize with the default values.
1.325 - * @param pHandleAccess Optional HandleAccess buffer to initialize with the default values.
1.326 - * @return True on success, false if version is unsupported.
1.327 - */
1.328 - virtual bool InitAccessDefaults(TypeAccess *pTypeAccess, HandleAccess *pHandleAccess) =0;
1.329 -
1.330 - /**
1.331 - * @brief Creates a new handle.
1.332 - *
1.333 - * @param type Type to use on the handle.
1.334 - * @param object Object to bind to the handle.
1.335 - * @param pSec Security pointer; pOwner is written as the owner,
1.336 - * pIdent is used as the parent identity for authorization.
1.337 - * @param pAccess Access right descriptor for the Handle; NULL for type defaults.
1.338 - * @param err Optional pointer to store an error code.
1.339 - * @return A new Handle_t, or 0 on failure.
1.340 - */
1.341 - virtual Handle_t CreateHandleEx(HandleType_t type,
1.342 - void *object,
1.343 - const HandleSecurity *pSec,
1.344 - const HandleAccess *pAccess,
1.345 - HandleError *err) =0;
1.346 - };
1.347 -}
1.348 -
1.349 -#endif //_INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_
