1.1 --- a/public/IHandleSys.h Fri Jul 11 06:51:21 2008 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,363 +0,0 @@
1.4 -/**
1.5 - * vim: set ts=4 :
1.6 - * =============================================================================
1.7 - * SourceMod
1.8 - * Copyright (C) 2004-2008 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 3
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 - * @param type Handle type.
1.203 - * @param object Handle internal object.
1.204 - */
1.205 - virtual void OnHandleDestroy(HandleType_t type, void *object) =0;
1.206 -
1.207 - /**
1.208 - * @brief Called to get the size of a handle's memory usage in bytes.
1.209 - * Implementation is optional.
1.210 - *
1.211 - * @param type Handle type.
1.212 - * @param object Handle internal object.
1.213 - * @param pSize Pointer to store the approximate memory usage in bytes.
1.214 - * @return True on success, false if not implemented.
1.215 - */
1.216 - virtual bool GetHandleApproxSize(HandleType_t type, void *object, unsigned int *pSize)
1.217 - {
1.218 - return false;
1.219 - }
1.220 - };
1.221 -
1.222 - /**
1.223 - * @brief Provides functions for managing Handles.
1.224 - */
1.225 - class IHandleSys : public SMInterface
1.226 - {
1.227 - public:
1.228 - virtual unsigned int GetInterfaceVersion()
1.229 - {
1.230 - return SMINTERFACE_HANDLESYSTEM_VERSION;
1.231 - }
1.232 - virtual const char *GetInterfaceName()
1.233 - {
1.234 - return SMINTERFACE_HANDLESYSTEM_NAME;
1.235 - }
1.236 - public:
1.237 - /**
1.238 - * @brief Creates a new Handle type.
1.239 - * NOTE: Currently, a child type may not have its own children.
1.240 - * NOTE: Handle names must be unique if not private.
1.241 - *
1.242 - * @param name Name of handle type (NULL or "" to be anonymous)
1.243 - * @param dispatch Pointer to a valid IHandleTypeDispatch object.
1.244 - * @param parent Parent handle to inherit from, 0 for none.
1.245 - * @param typeAccess Pointer to a TypeAccess object, NULL to use default
1.246 - * or inherited permissions. Pointer can be temporary.
1.247 - * @param hndlAccess Pointer to a HandleAccess object to define default
1.248 - * default permissions on each Handle. NULL to use default
1.249 - * permissions.
1.250 - * @param ident Security token for any permissions. If typeAccess is NULL, this
1.251 - * becomes the owning identity.
1.252 - * @param err Optional pointer to store an error code.
1.253 - * @return A new HandleType_t unique ID, or 0 on failure.
1.254 - */
1.255 - virtual HandleType_t CreateType(const char *name,
1.256 - IHandleTypeDispatch *dispatch,
1.257 - HandleType_t parent,
1.258 - const TypeAccess *typeAccess,
1.259 - const HandleAccess *hndlAccess,
1.260 - IdentityToken_t *ident,
1.261 - HandleError *err) =0;
1.262 -
1.263 - /**
1.264 - * @brief Removes a handle type.
1.265 - * NOTE: This removes all child types.
1.266 - *
1.267 - * @param type Type chain to remove.
1.268 - * @param ident Identity token. Removal fails if the token does not match.
1.269 - * @return True on success, false on failure.
1.270 - */
1.271 - virtual bool RemoveType(HandleType_t type, IdentityToken_t *ident) =0;
1.272 -
1.273 - /**
1.274 - * @brief Finds a handle type by name.
1.275 - *
1.276 - * @param name Name of handle type to find (anonymous not allowed).
1.277 - * @param type Address to store found handle in (if not found, undefined).
1.278 - * @return True if found, false otherwise.
1.279 - */
1.280 - virtual bool FindHandleType(const char *name, HandleType_t *type) =0;
1.281 -
1.282 - /**
1.283 - * @brief Creates a new handle.
1.284 - *
1.285 - * @param type Type to use on the handle.
1.286 - * @param object Object to bind to the handle.
1.287 - * @param owner Owner of the new Handle (may be NULL).
1.288 - * @param ident Identity for type access if needed (may be NULL).
1.289 - * @param err Optional pointer to store an error code.
1.290 - * @return A new Handle_t, or 0 on failure.
1.291 - */
1.292 - virtual Handle_t CreateHandle(HandleType_t type,
1.293 - void *object,
1.294 - IdentityToken_t *owner,
1.295 - IdentityToken_t *ident,
1.296 - HandleError *err) =0;
1.297 -
1.298 - /**
1.299 - * @brief Frees the memory associated with a handle and calls any destructors.
1.300 - * NOTE: This function will decrement the internal reference counter. It will
1.301 - * only perform any further action if the counter hits 0.
1.302 - *
1.303 - * @param handle Handle_t identifier to destroy.
1.304 - * @param pSecurity Security information struct (may be NULL).
1.305 - * @return A HandleError error code.
1.306 - */
1.307 - virtual HandleError FreeHandle(Handle_t handle, const HandleSecurity *pSecurity) =0;
1.308 -
1.309 - /**
1.310 - * @brief Clones a handle by adding to its internal reference count. Its data,
1.311 - * type, and security permissions remain the same.
1.312 - *
1.313 - * @param handle Handle to duplicate. Any non-free handle target is valid.
1.314 - * @param newhandle Stores the duplicated handle in the pointer (must not be NULL).
1.315 - * @param newOwner New owner of cloned handle.
1.316 - * @param pSecurity Security information struct (may be NULL).
1.317 - * @return A HandleError error code.
1.318 - */
1.319 - virtual HandleError CloneHandle(Handle_t handle,
1.320 - Handle_t *newhandle,
1.321 - IdentityToken_t *newOwner,
1.322 - const HandleSecurity *pSecurity) =0;
1.323 -
1.324 - /**
1.325 - * @brief Retrieves the contents of a handle.
1.326 - *
1.327 - * @param handle Handle_t from which to retrieve contents.
1.328 - * @param type Expected type to read as. 0 ignores typing rules.
1.329 - * @param pSecurity Security information struct (may be NULL).
1.330 - * @param object Optional address to store object in.
1.331 - * @return HandleError error code.
1.332 - */
1.333 - virtual HandleError ReadHandle(Handle_t handle,
1.334 - HandleType_t type,
1.335 - const HandleSecurity *pSecurity,
1.336 - void **object) =0;
1.337 -
1.338 - /**
1.339 - * @brief Sets access permissions on one or more structures.
1.340 - *
1.341 - * @param pTypeAccess Optional TypeAccess buffer to initialize with the default values.
1.342 - * @param pHandleAccess Optional HandleAccess buffer to initialize with the default values.
1.343 - * @return True on success, false if version is unsupported.
1.344 - */
1.345 - virtual bool InitAccessDefaults(TypeAccess *pTypeAccess, HandleAccess *pHandleAccess) =0;
1.346 -
1.347 - /**
1.348 - * @brief Creates a new handle.
1.349 - *
1.350 - * @param type Type to use on the handle.
1.351 - * @param object Object to bind to the handle.
1.352 - * @param pSec Security pointer; pOwner is written as the owner,
1.353 - * pIdent is used as the parent identity for authorization.
1.354 - * @param pAccess Access right descriptor for the Handle; NULL for type defaults.
1.355 - * @param err Optional pointer to store an error code.
1.356 - * @return A new Handle_t, or 0 on failure.
1.357 - */
1.358 - virtual Handle_t CreateHandleEx(HandleType_t type,
1.359 - void *object,
1.360 - const HandleSecurity *pSec,
1.361 - const HandleAccess *pAccess,
1.362 - HandleError *err) =0;
1.363 - };
1.364 -}
1.365 -
1.366 -#endif //_INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_
