1.1 --- a/core/interfaces/IHandleSys.h Fri Jan 19 05:25:43 2007 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,252 +0,0 @@
1.4 -#ifndef _INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_
1.5 -#define _INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_
1.6 -
1.7 -#include <IShareSys.h>
1.8 -#include <sp_vm_types.h>
1.9 -
1.10 -#define SMINTERFACE_HANDLESYSTEM_NAME "IHandleSys"
1.11 -#define SMINTERFACE_HANDLESYSTEM_VERSION 1
1.12 -
1.13 -#define DEFAULT_IDENTITY NULL
1.14 -
1.15 -namespace SourceMod
1.16 -{
1.17 - /**
1.18 - * Both of these types have invalid values of '0' for error checking.
1.19 - */
1.20 - typedef unsigned int HandleType_t;
1.21 - typedef unsigned int Handle_t;
1.22 -
1.23 - class SourcePawn::IPluginContext;
1.24 -
1.25 - /**
1.26 - * About type checking:
1.27 - * Types can be inherited - a Parent type ("Supertype") can have child types.
1.28 - * When accessing handles, type checking is done. This table shows how this is resolved:
1.29 - *
1.30 - * HANDLE CHECK -> RESULT
1.31 - * ------ ----- ------
1.32 - * Parent Parent Success
1.33 - * Parent Child Fail
1.34 - * Child Parent Success
1.35 - * Child Child Success
1.36 - */
1.37 -
1.38 - enum HandleError
1.39 - {
1.40 - HandleError_None = 0, /* No error */
1.41 - HandleError_Changed, /* The handle has been freed and reassigned */
1.42 - HandleError_Type, /* The handle has a different type registered */
1.43 - HandleError_Freed, /* The handle has been freed */
1.44 - HandleError_Index, /* generic internal indexing error */
1.45 - HandleError_Access, /* No access permitted to free this handle */
1.46 - HandleError_Limit, /* The limited number of handles has been reached */
1.47 - HandleError_Identity, /* The identity token was not usable */
1.48 - HandleError_Owner, /* Owners do not match for this operation */
1.49 - HandleError_Version, /* Unrecognized security structure version */
1.50 - HandleError_Parameter, /* An invalid parameter was passed */
1.51 - HandleError_NoInherit, /* This type cannot be inherited */
1.52 - };
1.53 -
1.54 - /**
1.55 - * Access rights specific to a type
1.56 - */
1.57 - enum HTypeAccessRight
1.58 - {
1.59 - HTypeAccess_Create = 0, /* Handles of this type can be created (DEFAULT=false) */
1.60 - HTypeAccess_Inherit, /* Sub-types can inherit this type (DEFAULT=false) */
1.61 - /* -------------- */
1.62 - HTypeAccess_TOTAL, /* Total number of type access rights */
1.63 - };
1.64 -
1.65 - /**
1.66 - * Access rights specific to a Handle. These rights are exclusive.
1.67 - * For example, you do not need "read" access to delete or clone.
1.68 - */
1.69 - enum HandleAccessRight
1.70 - {
1.71 - HandleAccess_Read, /* Can be read (DEFAULT=ident only) */
1.72 - HandleAccess_Delete, /* Can be deleted (DEFAULT=owner only) */
1.73 - HandleAccess_Clone, /* Can be cloned (DEFAULT=any) */
1.74 - /* ------------- */
1.75 - HandleAccess_TOTAL, /* Total number of access rights */
1.76 - };
1.77 -
1.78 - #define HANDLE_RESTRICT_IDENTITY (1<<0) /* Access is restricted to the identity */
1.79 - #define HANDLE_RESTRICT_OWNER (1<<1) /* Access is restricted to the owner */
1.80 -
1.81 - /**
1.82 - * This is used to define per-type access rights.
1.83 - */
1.84 - struct TypeAccess
1.85 - {
1.86 - TypeAccess()
1.87 - {
1.88 - hsVersion = SMINTERFACE_HANDLESYSTEM_VERSION;
1.89 - }
1.90 - unsigned int hsVersion;
1.91 - IdentityToken_t *ident;
1.92 - bool access[HTypeAccess_TOTAL];
1.93 - };
1.94 -
1.95 - /**
1.96 - * This is used to define per-Handle access rights.
1.97 - */
1.98 - struct HandleAccess
1.99 - {
1.100 - HandleAccess()
1.101 - {
1.102 - hsVersion = SMINTERFACE_HANDLESYSTEM_VERSION;
1.103 - }
1.104 - unsigned int hsVersion;
1.105 - unsigned int access[HandleAccess_TOTAL];
1.106 - };
1.107 -
1.108 - /**
1.109 - * This pair of tokens is used for identification.
1.110 - */
1.111 - struct HandleSecurity
1.112 - {
1.113 - IdentityToken_t *pOwner; /* Owner of the Handle */
1.114 - IdentityToken_t *pIdentity; /* Owner of the Type */
1.115 - };
1.116 -
1.117 - class IHandleTypeDispatch
1.118 - {
1.119 - public:
1.120 - virtual unsigned int GetDispatchVersion()
1.121 - {
1.122 - return SMINTERFACE_HANDLESYSTEM_VERSION;
1.123 - }
1.124 - public:
1.125 - /**
1.126 - * @brief Called when destroying a handle. Must be implemented.
1.127 - */
1.128 - virtual void OnHandleDestroy(HandleType_t type, void *object) =0;
1.129 - };
1.130 -
1.131 - class IHandleSys : public SMInterface
1.132 - {
1.133 - public:
1.134 - virtual unsigned int GetInterfaceVersion()
1.135 - {
1.136 - return SMINTERFACE_HANDLESYSTEM_VERSION;
1.137 - }
1.138 - virtual const char *GetInterfaceName()
1.139 - {
1.140 - return SMINTERFACE_HANDLESYSTEM_NAME;
1.141 - }
1.142 - public:
1.143 - /**
1.144 - * @brief Creates a new Handle type.
1.145 - * NOTE: Currently, a child type may not have its own children.
1.146 - * NOTE: Handle names must be unique if not private.
1.147 - *
1.148 - * @param name Name of handle type (NULL or "" to be anonymous)
1.149 - * @param dispatch Pointer to a valid IHandleTypeDispatch object.
1.150 - * @param parent Parent handle to inherit from, 0 for none.
1.151 - * @param typeAccess Pointer to a TypeAccess object, NULL to use default
1.152 - * or inherited permissions. Pointer can be temporary.
1.153 - * @param hndlAccess Pointer to a HandleAccess object to define default
1.154 - * default permissions on each Handle. NULL to use default
1.155 - * permissions.
1.156 - * @param ident Security token for any permissions. If typeAccess is NULL, this
1.157 - * becomes the owning identity.
1.158 - * @param err Optional pointer to store an error code.
1.159 - * @return A new HandleType_t unique ID, or 0 on failure.
1.160 - */
1.161 - virtual HandleType_t CreateType(const char *name,
1.162 - IHandleTypeDispatch *dispatch,
1.163 - HandleType_t parent,
1.164 - const TypeAccess *typeAccess,
1.165 - const HandleAccess *hndlAccess,
1.166 - IdentityToken_t *ident,
1.167 - HandleError *err) =0;
1.168 -
1.169 - /**
1.170 - * @brief Removes a handle type.
1.171 - * NOTE: This removes all child types.
1.172 - *
1.173 - * @param type Type chain to remove.
1.174 - * @param ident Identity token. Removal fails if the token does not match.
1.175 - * @return True on success, false on failure.
1.176 - */
1.177 - virtual bool RemoveType(HandleType_t type, IdentityToken_t *ident) =0;
1.178 -
1.179 - /**
1.180 - * @brief Finds a handle type by name.
1.181 - *
1.182 - * @param name Name of handle type to find (anonymous not allowed).
1.183 - * @param type Address to store found handle in (if not found, undefined).
1.184 - * @return True if found, false otherwise.
1.185 - */
1.186 - virtual bool FindHandleType(const char *name, HandleType_t *type) =0;
1.187 -
1.188 - /**
1.189 - * @brief Creates a new handle.
1.190 - *
1.191 - * @param type Type to use on the handle.
1.192 - * @param object Object to bind to the handle.
1.193 - * @param owner Owner of the new Handle (may be NULL).
1.194 - * @param ident Identity for type access if needed (may be NULL).
1.195 - * @param err Optional pointer to store an error code.
1.196 - * @return A new Handle_t, or 0 on failure.
1.197 - */
1.198 - virtual Handle_t CreateHandle(HandleType_t type,
1.199 - void *object,
1.200 - IdentityToken_t *owner,
1.201 - IdentityToken_t *ident,
1.202 - HandleError *err) =0;
1.203 -
1.204 - /**
1.205 - * @brief Frees the memory associated with a handle and calls any destructors.
1.206 - * NOTE: This function will decrement the internal reference counter. It will
1.207 - * only perform any further action if the counter hits 0.
1.208 - *
1.209 - * @param type Handle_t identifier to destroy.
1.210 - * @param pSecurity Security information struct (may be NULL).
1.211 - * @return A HandleError error code.
1.212 - */
1.213 - virtual HandleError FreeHandle(Handle_t handle, const HandleSecurity *pSecurity) =0;
1.214 -
1.215 - /**
1.216 - * @brief Clones a handle by adding to its internal reference count. Its data,
1.217 - * type, and security permissions remain the same.
1.218 - *
1.219 - * @param handle Handle to duplicate. Any non-free handle target is valid.
1.220 - * @param newhandle Stores the duplicated handle in the pointer (must not be NULL).
1.221 - * @param newOwner New owner of cloned handle.
1.222 - * @param pSecurity Security information struct (may be NULL).
1.223 - * @return A HandleError error code.
1.224 - */
1.225 - virtual HandleError CloneHandle(Handle_t handle,
1.226 - Handle_t *newhandle,
1.227 - IdentityToken_t *newOwner,
1.228 - const HandleSecurity *pSecurity) =0;
1.229 -
1.230 - /**
1.231 - * @brief Retrieves the contents of a handle.
1.232 - *
1.233 - * @param handle Handle_t from which to retrieve contents.
1.234 - * @param type Expected type to read as. 0 ignores typing rules.
1.235 - * @param pSecurity Security information struct (may be NULL).
1.236 - * @param object Optional address to store object in.
1.237 - * @return HandleError error code.
1.238 - */
1.239 - virtual HandleError ReadHandle(Handle_t handle,
1.240 - HandleType_t type,
1.241 - const HandleSecurity *pSecurity,
1.242 - void **object) =0;
1.243 -
1.244 - /**
1.245 - * @brief Sets access permissions on one or more structures.
1.246 - *
1.247 - * @param pTypeAccess Optional TypeAccess buffer to initialize with the default values.
1.248 - * @param pHandleAccess Optional HandleAccess buffer to initialize with the default values.
1.249 - * @return True on success, false if version is unsupported.
1.250 - */
1.251 - virtual bool InitAccessDefaults(TypeAccess *pTypeAccess, HandleAccess *pHandleAccess) =0;
1.252 - };
1.253 -};
1.254 -
1.255 -#endif //_INCLUDE_SOURCEMOD_HANDLESYSTEM_INTERFACE_H_
