3 * =============================================================================
5 * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved.
6 * =============================================================================
8 * This program is free software; you can redistribute it and/or modify it under
9 * the terms of the GNU General Public License, version 3.0, as published by the
10 * Free Software Foundation.
12 * This program is distributed in the hope that it will be useful, but WITHOUT
13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
14 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
17 * You should have received a copy of the GNU General Public License along with
18 * this program. If not, see <http://www.gnu.org/licenses/>.
20 * As a special exception, AlliedModders LLC gives you permission to link the
21 * code of this program (as well as its derivative works) to "Half-Life 2," the
22 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
23 * by the Valve Corporation. You must obey the GNU General Public License in
24 * all respects for all other code used. Additionally, AlliedModders LLC grants
25 * this exception to all derivative works. AlliedModders LLC defines further
26 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
27 * or <http://www.sourcemod.net/license.php>.
32 #ifndef _INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_
33 #define _INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_
37 * @brief Defines the interface for creating, reading, and removing Handles.
39 * The Handle system abstracts generic pointers into typed objects represented by
40 * 32bit codes. This is extremely useful for verifying data integrity and cross-platform
41 * support in SourcePawn scripts. When a Plugin unloads, all its Handles are freed, ensuring
42 * that no memory leaks are present, They have reference counts and thus can be duplicated,
43 * or cloned, and are safe to pass between Plugins even if one is unloaded.
45 * Handles are created with a given type (custom types may be created). They can have
46 * per-Identity permissions for deletion, reading, and cloning. They also support generic
47 * operations. For example, deleting a Handle will call that type's destructor on the generic
48 * pointer, making cleanup easier for users and eliminating memory leaks.
51 #include <IShareSys.h>
52 #include <sp_vm_types.h>
54 #define SMINTERFACE_HANDLESYSTEM_NAME "IHandleSys"
55 #define SMINTERFACE_HANDLESYSTEM_VERSION 5
57 /** Specifies no Identity */
58 #define DEFAULT_IDENTITY NULL
59 /** Specifies no Type. This is invalid for everything but reading a Handle. */
60 #define NO_HANDLE_TYPE 0
61 /** Specifies an invalid/NULL Handle */
67 * @brief Represents a Handle Type ID.
69 typedef unsigned int HandleType_t;
72 * @brief Represents a Handle ID.
74 typedef unsigned int Handle_t;
78 * About type checking:
79 * Types can be inherited - a Parent type ("Supertype") can have child types.
80 * When accessing handles, type checking is done. This table shows how this is resolved:
82 * HANDLE CHECK -> RESULT
84 * Parent Parent Success
86 * Child Parent Success
91 * @brief Lists the possible handle error codes.
95 HandleError_None = 0, /**< No error */
96 HandleError_Changed, /**< The handle has been freed and reassigned */
97 HandleError_Type, /**< The handle has a different type registered */
98 HandleError_Freed, /**< The handle has been freed */
99 HandleError_Index, /**< generic internal indexing error */
100 HandleError_Access, /**< No access permitted to free this handle */
101 HandleError_Limit, /**< The limited number of handles has been reached */
102 HandleError_Identity, /**< The identity token was not usable */
103 HandleError_Owner, /**< Owners do not match for this operation */
104 HandleError_Version, /**< Unrecognized security structure version */
105 HandleError_Parameter, /**< An invalid parameter was passed */
106 HandleError_NoInherit, /**< This type cannot be inherited */
110 * @brief Lists access rights specific to a type.
112 enum HTypeAccessRight
114 HTypeAccess_Create = 0, /**< Handles of this type can be created (DEFAULT=false) */
115 HTypeAccess_Inherit, /**< Sub-types can inherit this type (DEFAULT=false) */
117 HTypeAccess_TOTAL, /**< Total number of type access rights */
121 * @brief Lists access rights specific to a Handle.
123 * These rights are exclusive. For example, you do not need "read" access to delete or clone.
125 enum HandleAccessRight
127 HandleAccess_Read, /**< Can be read (DEFAULT=ident only) */
128 HandleAccess_Delete, /**< Can be deleted (DEFAULT=owner only) */
129 HandleAccess_Clone, /**< Can be cloned (DEFAULT=any) */
131 HandleAccess_TOTAL, /**< Total number of access rights */
134 /** Access is restricted to the identity */
135 #define HANDLE_RESTRICT_IDENTITY (1<<0)
136 /** Access is restricted to the owner */
137 #define HANDLE_RESTRICT_OWNER (1<<1)
140 * @brief This is used to define per-type access rights.
147 hsVersion = SMINTERFACE_HANDLESYSTEM_VERSION;
149 unsigned int hsVersion; /**< Handle API version */
150 IdentityToken_t *ident; /**< Identity owning this type */
151 bool access[HTypeAccess_TOTAL]; /**< Access array */
155 * @brief This is used to define per-Handle access rights.
162 hsVersion = SMINTERFACE_HANDLESYSTEM_VERSION;
164 unsigned int hsVersion; /**< Handle API version */
165 unsigned int access[HandleAccess_TOTAL]; /**< Access array */
169 * @brief This pair of tokens is used for identification.
171 struct HandleSecurity
176 HandleSecurity(IdentityToken_t *owner, IdentityToken_t *identity)
177 : pOwner(owner), pIdentity(identity)
180 IdentityToken_t *pOwner; /**< Owner of the Handle */
181 IdentityToken_t *pIdentity; /**< Owner of the Type */
185 * @brief Hooks type-specific Handle operations.
187 class IHandleTypeDispatch
190 /** Returns the Handle API version */
191 virtual unsigned int GetDispatchVersion()
193 return SMINTERFACE_HANDLESYSTEM_VERSION;
197 * @brief Called when destroying a handle. Must be implemented.
199 * @param type Handle type.
200 * @param object Handle internal object.
202 virtual void OnHandleDestroy(HandleType_t type, void *object) =0;
205 * @brief Called to get the size of a handle's memory usage in bytes.
206 * Implementation is optional.
208 * @param type Handle type.
209 * @param object Handle internal object.
210 * @param pSize Pointer to store the approximate memory usage in bytes.
211 * @return True on success, false if not implemented.
213 virtual bool GetHandleApproxSize(HandleType_t type, void *object, unsigned int *pSize)
220 * @brief Provides functions for managing Handles.
222 class IHandleSys : public SMInterface
225 virtual unsigned int GetInterfaceVersion()
227 return SMINTERFACE_HANDLESYSTEM_VERSION;
229 virtual const char *GetInterfaceName()
231 return SMINTERFACE_HANDLESYSTEM_NAME;
235 * @brief Creates a new Handle type.
236 * NOTE: Currently, a child type may not have its own children.
237 * NOTE: Handle names must be unique if not private.
239 * @param name Name of handle type (NULL or "" to be anonymous)
240 * @param dispatch Pointer to a valid IHandleTypeDispatch object.
241 * @param parent Parent handle to inherit from, 0 for none.
242 * @param typeAccess Pointer to a TypeAccess object, NULL to use default
243 * or inherited permissions. Pointer can be temporary.
244 * @param hndlAccess Pointer to a HandleAccess object to define default
245 * default permissions on each Handle. NULL to use default
247 * @param ident Security token for any permissions. If typeAccess is NULL, this
248 * becomes the owning identity.
249 * @param err Optional pointer to store an error code on failure (undefined on success).
250 * @return A new HandleType_t unique ID, or 0 on failure.
252 virtual HandleType_t CreateType(const char *name,
253 IHandleTypeDispatch *dispatch,
255 const TypeAccess *typeAccess,
256 const HandleAccess *hndlAccess,
257 IdentityToken_t *ident,
258 HandleError *err) =0;
261 * @brief Removes a handle type.
262 * NOTE: This removes all child types.
264 * @param type Type chain to remove.
265 * @param ident Identity token. Removal fails if the token does not match.
266 * @return True on success, false on failure.
268 virtual bool RemoveType(HandleType_t type, IdentityToken_t *ident) =0;
271 * @brief Finds a handle type by name.
273 * @param name Name of handle type to find (anonymous not allowed).
274 * @param type Address to store found handle in (if not found, undefined).
275 * @return True if found, false otherwise.
277 virtual bool FindHandleType(const char *name, HandleType_t *type) =0;
280 * @brief Creates a new handle.
282 * @param type Type to use on the handle.
283 * @param object Object to bind to the handle.
284 * @param owner Owner of the new Handle (may be NULL).
285 * @param ident Identity for type access if needed (may be NULL).
286 * @param err Optional pointer to store an error code on failure (undefined on success).
287 * @return A new Handle_t, or 0 on failure.
289 virtual Handle_t CreateHandle(HandleType_t type,
291 IdentityToken_t *owner,
292 IdentityToken_t *ident,
293 HandleError *err) =0;
296 * @brief Frees the memory associated with a handle and calls any destructors.
297 * NOTE: This function will decrement the internal reference counter. It will
298 * only perform any further action if the counter hits 0.
300 * @param handle Handle_t identifier to destroy.
301 * @param pSecurity Security information struct (may be NULL).
302 * @return A HandleError error code.
304 virtual HandleError FreeHandle(Handle_t handle, const HandleSecurity *pSecurity) =0;
307 * @brief Clones a handle by adding to its internal reference count. Its data,
308 * type, and security permissions remain the same.
310 * @param handle Handle to duplicate. Any non-free handle target is valid.
311 * @param newhandle Stores the duplicated handle in the pointer (must not be NULL).
312 * @param newOwner New owner of cloned handle.
313 * @param pSecurity Security information struct (may be NULL).
314 * @return A HandleError error code.
316 virtual HandleError CloneHandle(Handle_t handle,
318 IdentityToken_t *newOwner,
319 const HandleSecurity *pSecurity) =0;
322 * @brief Retrieves the contents of a handle.
324 * @param handle Handle_t from which to retrieve contents.
325 * @param type Expected type to read as. 0 ignores typing rules.
326 * @param pSecurity Security information struct (may be NULL).
327 * @param object Optional address to store object in.
328 * @return HandleError error code.
330 virtual HandleError ReadHandle(Handle_t handle,
332 const HandleSecurity *pSecurity,
336 * @brief Sets access permissions on one or more structures.
338 * @param pTypeAccess Optional TypeAccess buffer to initialize with the default values.
339 * @param pHandleAccess Optional HandleAccess buffer to initialize with the default values.
340 * @return True on success, false if version is unsupported.
342 virtual bool InitAccessDefaults(TypeAccess *pTypeAccess, HandleAccess *pHandleAccess) =0;
345 * @brief Creates a new handle.
347 * @param type Type to use on the handle.
348 * @param object Object to bind to the handle.
349 * @param pSec Security pointer; pOwner is written as the owner,
350 * pIdent is used as the parent identity for authorization.
351 * @param pAccess Access right descriptor for the Handle; NULL for type defaults.
352 * @param err Optional pointer to store an error code on failure (undefined on success).
353 * @return A new Handle_t, or 0 on failure.
355 virtual Handle_t CreateHandleEx(HandleType_t type,
357 const HandleSecurity *pSec,
358 const HandleAccess *pAccess,
359 HandleError *err) =0;
362 * @brief Clones a handle, bypassing security checks.
364 * @return A new Handle_t, or 0 on failure.
366 virtual Handle_t FastCloneHandle(Handle_t hndl) =0;
369 * @brief Type checks two handles.
371 * @param given Type to test.
372 * @param actual Type to check for.
373 * @return True if "given" is a subtype of "actual", false otherwise.
375 virtual bool TypeCheck(HandleType_t given, HandleType_t actual) = 0;
379 #endif //_INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_
