AlliedModders Wiki - User contributions [en]

Handle API (SourceMod)

2007-06-08T14:41:41Z

Bennyboy: /* New Security Rules */

The SourceMod [[Handles (SourceMod Scripting)|Handle System]] marshals pointers into typed, unique, 32-bit integers. This makes coding in SourceMod more cross-platform compatible, type safe, and mistake safe than its predecessor, [[AMX Mod X]]. It also allows for safe object sharing and reference count based object destruction.

The fundamental aspect of Handles is that they encapsulate a single pointer. This pointer is private data, and can only be read by the Handle's creator. When the Handle is freed, the pointer is automatically freed (via a special interface), thus ensuring that memory is not leaked.

Handles also provide a simple "security" system for restricting which areas of SourceMod are allowed to directly call certain functions on Handles under a given type.

=Basic Types=
==Handle_t==
The <tt>Handle_t</tt> type is a 32bit integer. Currently, it is composed of two 16-bit integers, a serial number and a handle index. The serial number is private and used for integrity checking. The index is the internal ID of the Handle, which is tied to the encapsulated pointer and security information.

Each <tt>Handle_t</tt> is a unique Handle, however, there are ''cloned'' Handles which are copies of another Handle. They have their own unique signatures, but they refer to another Handle internally. Each Handle is also associated with a ''type'', explained below.

==HandleType_t==
The <tt>HandleType_t</tt> describes a type under which Handles can be created. Types can have up to 15 sub-types; sub-types cannot have their own sub-types, called child types. When Handles are being read, they are "type checked," to make sure they are being read under a given type. When a type is destroyed, all Handles under the type are destroyed. If the type has child types, each child type is also destroyed.

Handle types also allow overloading of various Handle operations. Currently, the only overloaded action is for overloading when a Handle is destroyed. This allows the encapsulated pointer to be safely destroyed by the type interface. The interface which overloads type operations is called <tt>IHandleTypeDispatch</tt>.

Lastly, types provide a "default security" system which lets programmers restrict which functions can be accessed by other areas in SourceMod. This is explained later.

=Security=
'''Note:''' Type defaults can be set via <tt>IHandleSys::InitAccessDefaults()</tt>.

==Type Security==
Often, extensions may want to share HandleType_t values with each other, so they can create Handles of external types. However, the owner of the handle type may not want other extensions to perform certain actions. Thus, types can be ''secured'' by an <tt>IdentityToken_t</tt> when created. Unless the same <tt>IdentityToken</tt> is provided, a function may fail if restricted.

Type permissions are declared in a <tt>TypeAccess</tt> struct, which has the following user-set members:
*<tt>ident</tt>: The <tt>IdentityToken_t</tt> owner of this type.
*<tt>access</tt>: An array where each index is a <tt>HTypeAccessRight</tt> enumeration member. If an index is set to false, functions requiring that right will fail unless the correct <tt>IdentityToken_t</tt> is passed in.

The <tt>HTypeAccessRight</tt> enumeration has the following values:
*<tt>HTypeAccess_Create</tt>: Handle creation using this type; default is false.
*<tt>HTypeAccess_Inherit</tt>: Inheriting this type for child types; default is false.

Below is a list of each Handle System function that requires type permissions, and which permissions may be required:
*<tt>CreateType</tt>: <tt>HTypeAccess_Inherit</tt> if a parent is specified
*<tt>RemoveType</tt>: (none, always secured)
*<tt>CreateHandle</tt>: <tt>HTypeAccess_Create</tt>

==Handle Security==
Handle security permissions inherit from their parent type unless given an alternate set of permissions. Handles are "secured" by two properties, unlike Handles, which just have one. When verifying your identity with a secured Handle function, you must use the <tt>HandleSecurity</tt> struct, which has two properties:
*<tt>pOwner</tt>: The owner of the Handle, which is usually a plugin <tt>IdentityToken_t</tt>.
*<tt>pIdentity</tt>: The owner of the Handle's type, or the <tt>IdentityToken_t</tt> securing its type.

Handle permissions are specified via the <tt>HandleAccess</tt> struct. It is passed either through <tt>CreateType</tt> for default settings in a given type, or through <tt>CreateHandleEx</tt> for explicit per-Handle permissions. This struct has the following members:
*<tt>access</tt>: An array where each index is a <tt>HandleAccessRight</tt> enumeration member. If set to 0, an access right is allowed without a <tt>HandleSecurity</tt> instance. Otherwise, the following bitwise flags are checked:
**<tt>HANDLE_RESTRICT_IDENTITY</tt>: If flagged, this access right is only granted if the <tt>pIdentity</tt> member of the <tt>HandleSecurity</tt> struct matches the Handle's '''type's''' owner.
**<tt>HANDLE_RESTRICT_OWNER</tt>: If flagged, this access right is onyl granted if the <tt>pOwner</tt> member of the <tt>Handlesecurity</tt> struct matches the Handle's owner.

The following access rights exist for Handles:
*<tt>HandleAccess_Read</tt>: This Handle's encapsulated pointer can be retrieved. Defaults to <tt>HANDLE_RESTRICT_IDENTITY</tt>.
*<tt>HandleAccess_Delete</tt>: This Handle can be removed or freed. Defaults to <tt>HANDLE_RESTRICT_OWNER</tt>.
*<tt>HandleAccess_Clone</tt>: This Handle can be cloned. Defaults to 0.

Below is a list of each Handle system function that requires permissions, and which permissions may be required:
*<tt>FreeHandle</tt>: <tt>HandleAccess_Delete</tt>
*<tt>CloneHandle/CloneHandleEx</tt>: <tt>HandleAccess_Clone</tt>
*<tt>ReadHandle</tt>: <tt>HandleAccess_Read</tt>

SourceMod's generic native wrappers assume follow these rules, however, they assume certain access rights, and will return <tt>INVALID_HANDLE</tt> or 0 if these rights are denied. Thus, you should make sure your permissions are compatible, unless you explicitly want to deny usage of these functions.
*<tt>CloneHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity</tt>, meaning <tt>HandleAccess_Clone</tt> must be 0.
*<tt>CloseHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity::pIdentity</tt>, and the plugin's <tt>IdentityToken_t</tt> for <tt>HandleSecurity::pOwner</tt/>. This means that at most, the only restriction can be <tt>HANDLE_RESTRICT_OWNER</tt> for <tt>HandleAccess_Delete</tt>.

=Usage Examples=
Here are some examples of Handle usages.

==Basic Handles==
The most basic use of Handles is to encapsulate a data structure and allow <tt>CloseHandle</tt> to universally destroy it. Let's say we want to implement two natives - <tt>CreateFile</tt> for creating an empty file, and <tt>WriteLine</tt> for writing a line to this file. How could we implement this using the Handle system?

After reading this, it is tempting to think, "Why can't we just return the <tt>FILE</tt> pointer as a <tt>cell_t</tt>?" The reason is that a <tt>cell_t</tt> is guaranteed to be a 32bit integer. There is no guarantee that a pointer will always be this size, however, and thus casting on future platforms could break. This problem happened in [[AMX Mod X]] and greatly restricted flexibility.

===Creating the type===
First, we have to create the type and its Dispatch interface.
<cpp>HandleType_t g_FileType = 0; /* Holds the HandleType ID */

class FileTypeHandler : public IHandleTypeDispatch
{
public:
void OnHandleDestroy(HandleType_t type, void *object)
{
/* :TODO: implement this */
}
};

/* Create an instance of the handler */
FileTypeHandler g_FileTypeHandler;

Initialize()
{
/* Register the type with default security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
NULL,
myself->GetIdentity(),
NULL);
}

Shutdown()
{
/* Remove the type on shutdown */
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());
}</cpp>

===Creating Handles===
Creating the Handles is fairly easy once we have a valid pointer to stuff in it.
<cpp>/* native CreateFile(const String:file[]) */
static cell_t sm_CreateFile(IPluginContext *pContext, const cell_t *params)
{
char path[PLATFORM_MAX_PATH];
char *filename;

/* Get the filename */
pContext->LocalToString(params[1], &filename);
/* Build a full path */
g_pSM->BuildPath(Path_SM, path, sizeof(path), "%s", filename);

/* Open for writing */
FILE *fp = fopen(path, "wt");
if (!fp)
{
return BAD_HANDLE;
}

/* Create the Handle with our type, the FILE pointer, the plugin's identity, and our identity */
return g_pHandleSys->CreateHandle(g_FileType,
fp,
pContext->GetIdentity(),
myself->GetIdentity(),
NULL);
}</cpp>

===Reading/Checking Handles===
Handles aren't very useful unless you have natives to use them. Let's say we want to write lines of text to our File type.
<cpp>/* native WriteLine(Handle:hndl, const String:line[]); */
static cell_t sm_WriteLine(IPluginContext *pContext, const cell_t *params)
{
Handle_t hndl = static_cast<Handle_t>(params[1]);
HandleError err;
HandleSecurity sec;

/* Build our security descriptor */
sec.pOwner = NULL; /* Not needed, owner access is not checked */
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */

/* Attempt to read the given handle as our type, using our security info.
* Note that we read the pointer directly in with a little cast.
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.
*/
FILE *fp;
if ((herr = g_pHandleSys->ReadHandle(hndl, g_FileType, &sec, (void **)&fp))
!= HandleError_None)
{
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);
}

/* Get the text */
char *text;
pContext->LocalToString(params[2], &text);

/* Write it */
fputs(text, fp);

return 1;
}</cpp>

===CloseHandle Support===
Lastly, we need to make it so <tt>CloseHandle()</tt> or <tt>FreeHandle()</tt> will close our file pointer when removing the Handle, which we skipped before.
<cpp>class FileTypeHandler : public IHandleTypeDispatch
{
public:
void OnHandleDestroy(HandleType_t type, void *object)
{
fclose( (FILE *)object );
}
};</cpp>

==Restricting CloseHandle==
Let's say that, for various reasons, you don't want users to be able to call CloseHandle(). An example of this might be a data type that is non-temporary, or is being called from a forward, and thus should not be touched. Or, you might have a special deconstructor that takes extra parameters, and thus you need a separate destroy function.

For example, let's create a separate function called <tt>CloseFile</tt>. It doesn't do anything particularly special, but we are going to force its usage over CloseHandle().

===New Security Rules===
<cpp>Initialize()
{
/* Create default access rights */
HandleAccess rules;
g_pHandleSys->InitAccessDefaults(NULL, &rules);

/* Restrict delete to only our identity */
rules.access[HandleAccess_Delete] = HANDLE_RESTRICT_IDENTITY;

/* Register the type with our security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
&rules,
myself->GetIdentity(),
NULL);
}</cpp>

===Implementing the Native===
<cpp>/* native Closefile(Handle:hndl); */
static cell_t sm_CloseFile(IPluginContext *pContext, const cell_t *params)
{
Handle_t hndl = static_cast<Handle_t>(params[1]);
HandleError err;
HandleSecurity sec;

/* Build our security descriptor */
sec.pOwner = pContext->GetIdentity(); /* Needed, HANDLE_RESTRICT_OWNER is default */
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */

/* Attempt to read the given handle as our type, using our security info.
* Note that we read the pointer directly in with a little cast.
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.
*/
FILE *fp;
if ((herr = g_pHandleSys->FreeHandle(hndl, &src))
!= HandleError_None)
{
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);
}

return 1;
}</cpp>

==Restricting CloseHandle Per-Handle==
Taking our above example, it is possible that we might want some Handles to be closed via CloseHandle(), but others not. Again, this is useful if you wish to pass a Handle as read-only to a plugin, commonly done when using non-temporary structures or Handles used in Forwards.

In this example, we'll create a global instance of our file type, and this instance will be denied access to CloseHandle(), whereas files returned by OpenFile() will not.

===Implementation===
<cpp>Handle_t g_GlobalFile;

Initialize()
{
/* Register the type with default security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
NULL,
myself->GetIdentity(),
NULL);

/* Create our 'global' file */
FILE *fp = tmpfile();

/* Set up the security descriptor */
HandleSecurity sec;
sec.pOwner = NULL; /* No owner for this Handle */
sec.pIdentity = myself->GetIdentity(); /* Only this identity will be allowed */

/* Set up the access permissions */
HandleAccess rules;
g_pHandleSys->InitAccessDefaults(NULL, &rules);
rules.access[HandleAccess_Delete] |= HANDLE_RESTRICT_IDENTITY;

/* Finally, create the Handle with our rules */
g_GlobalFile = g_pHandleSys->CreateHandleEx(g_FileType, fp, &sec, &rules, NULL);
}

Shutdown()
{
/* Remove our global Handle (not needed, but we do it for clarity */
HandleSecurity sec;
sec.pOwner = NULL;
sec.pIdentity = myself->GetIdentity();

g_pHandleSys->FreeHandle(g_GlobalFile, &sec);

/* Remove the type on shutdown */
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());
}</cpp>

[[Category:SourceMod Development]]

Handle API (SourceMod)

2007-06-08T14:38:18Z

Bennyboy: HandleSecurity changed to HandleAccess

The SourceMod [[Handles (SourceMod Scripting)|Handle System]] marshals pointers into typed, unique, 32-bit integers. This makes coding in SourceMod more cross-platform compatible, type safe, and mistake safe than its predecessor, [[AMX Mod X]]. It also allows for safe object sharing and reference count based object destruction.

The fundamental aspect of Handles is that they encapsulate a single pointer. This pointer is private data, and can only be read by the Handle's creator. When the Handle is freed, the pointer is automatically freed (via a special interface), thus ensuring that memory is not leaked.

Handles also provide a simple "security" system for restricting which areas of SourceMod are allowed to directly call certain functions on Handles under a given type.

=Basic Types=
==Handle_t==
The <tt>Handle_t</tt> type is a 32bit integer. Currently, it is composed of two 16-bit integers, a serial number and a handle index. The serial number is private and used for integrity checking. The index is the internal ID of the Handle, which is tied to the encapsulated pointer and security information.

Each <tt>Handle_t</tt> is a unique Handle, however, there are ''cloned'' Handles which are copies of another Handle. They have their own unique signatures, but they refer to another Handle internally. Each Handle is also associated with a ''type'', explained below.

==HandleType_t==
The <tt>HandleType_t</tt> describes a type under which Handles can be created. Types can have up to 15 sub-types; sub-types cannot have their own sub-types, called child types. When Handles are being read, they are "type checked," to make sure they are being read under a given type. When a type is destroyed, all Handles under the type are destroyed. If the type has child types, each child type is also destroyed.

Handle types also allow overloading of various Handle operations. Currently, the only overloaded action is for overloading when a Handle is destroyed. This allows the encapsulated pointer to be safely destroyed by the type interface. The interface which overloads type operations is called <tt>IHandleTypeDispatch</tt>.

Lastly, types provide a "default security" system which lets programmers restrict which functions can be accessed by other areas in SourceMod. This is explained later.

=Security=
'''Note:''' Type defaults can be set via <tt>IHandleSys::InitAccessDefaults()</tt>.

==Type Security==
Often, extensions may want to share HandleType_t values with each other, so they can create Handles of external types. However, the owner of the handle type may not want other extensions to perform certain actions. Thus, types can be ''secured'' by an <tt>IdentityToken_t</tt> when created. Unless the same <tt>IdentityToken</tt> is provided, a function may fail if restricted.

Type permissions are declared in a <tt>TypeAccess</tt> struct, which has the following user-set members:
*<tt>ident</tt>: The <tt>IdentityToken_t</tt> owner of this type.
*<tt>access</tt>: An array where each index is a <tt>HTypeAccessRight</tt> enumeration member. If an index is set to false, functions requiring that right will fail unless the correct <tt>IdentityToken_t</tt> is passed in.

The <tt>HTypeAccessRight</tt> enumeration has the following values:
*<tt>HTypeAccess_Create</tt>: Handle creation using this type; default is false.
*<tt>HTypeAccess_Inherit</tt>: Inheriting this type for child types; default is false.

Below is a list of each Handle System function that requires type permissions, and which permissions may be required:
*<tt>CreateType</tt>: <tt>HTypeAccess_Inherit</tt> if a parent is specified
*<tt>RemoveType</tt>: (none, always secured)
*<tt>CreateHandle</tt>: <tt>HTypeAccess_Create</tt>

==Handle Security==
Handle security permissions inherit from their parent type unless given an alternate set of permissions. Handles are "secured" by two properties, unlike Handles, which just have one. When verifying your identity with a secured Handle function, you must use the <tt>HandleSecurity</tt> struct, which has two properties:
*<tt>pOwner</tt>: The owner of the Handle, which is usually a plugin <tt>IdentityToken_t</tt>.
*<tt>pIdentity</tt>: The owner of the Handle's type, or the <tt>IdentityToken_t</tt> securing its type.

Handle permissions are specified via the <tt>HandleAccess</tt> struct. It is passed either through <tt>CreateType</tt> for default settings in a given type, or through <tt>CreateHandleEx</tt> for explicit per-Handle permissions. This struct has the following members:
*<tt>access</tt>: An array where each index is a <tt>HandleAccessRight</tt> enumeration member. If set to 0, an access right is allowed without a <tt>HandleSecurity</tt> instance. Otherwise, the following bitwise flags are checked:
**<tt>HANDLE_RESTRICT_IDENTITY</tt>: If flagged, this access right is only granted if the <tt>pIdentity</tt> member of the <tt>HandleSecurity</tt> struct matches the Handle's '''type's''' owner.
**<tt>HANDLE_RESTRICT_OWNER</tt>: If flagged, this access right is onyl granted if the <tt>pOwner</tt> member of the <tt>Handlesecurity</tt> struct matches the Handle's owner.

The following access rights exist for Handles:
*<tt>HandleAccess_Read</tt>: This Handle's encapsulated pointer can be retrieved. Defaults to <tt>HANDLE_RESTRICT_IDENTITY</tt>.
*<tt>HandleAccess_Delete</tt>: This Handle can be removed or freed. Defaults to <tt>HANDLE_RESTRICT_OWNER</tt>.
*<tt>HandleAccess_Clone</tt>: This Handle can be cloned. Defaults to 0.

Below is a list of each Handle system function that requires permissions, and which permissions may be required:
*<tt>FreeHandle</tt>: <tt>HandleAccess_Delete</tt>
*<tt>CloneHandle/CloneHandleEx</tt>: <tt>HandleAccess_Clone</tt>
*<tt>ReadHandle</tt>: <tt>HandleAccess_Read</tt>

SourceMod's generic native wrappers assume follow these rules, however, they assume certain access rights, and will return <tt>INVALID_HANDLE</tt> or 0 if these rights are denied. Thus, you should make sure your permissions are compatible, unless you explicitly want to deny usage of these functions.
*<tt>CloneHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity</tt>, meaning <tt>HandleAccess_Clone</tt> must be 0.
*<tt>CloseHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity::pIdentity</tt>, and the plugin's <tt>IdentityToken_t</tt> for <tt>HandleSecurity::pOwner</tt/>. This means that at most, the only restriction can be <tt>HANDLE_RESTRICT_OWNER</tt> for <tt>HandleAccess_Delete</tt>.

=Usage Examples=
Here are some examples of Handle usages.

==Basic Handles==
The most basic use of Handles is to encapsulate a data structure and allow <tt>CloseHandle</tt> to universally destroy it. Let's say we want to implement two natives - <tt>CreateFile</tt> for creating an empty file, and <tt>WriteLine</tt> for writing a line to this file. How could we implement this using the Handle system?

After reading this, it is tempting to think, "Why can't we just return the <tt>FILE</tt> pointer as a <tt>cell_t</tt>?" The reason is that a <tt>cell_t</tt> is guaranteed to be a 32bit integer. There is no guarantee that a pointer will always be this size, however, and thus casting on future platforms could break. This problem happened in [[AMX Mod X]] and greatly restricted flexibility.

===Creating the type===
First, we have to create the type and its Dispatch interface.
<cpp>HandleType_t g_FileType = 0; /* Holds the HandleType ID */

class FileTypeHandler : public IHandleTypeDispatch
{
public:
void OnHandleDestroy(HandleType_t type, void *object)
{
/* :TODO: implement this */
}
};

/* Create an instance of the handler */
FileTypeHandler g_FileTypeHandler;

Initialize()
{
/* Register the type with default security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
NULL,
myself->GetIdentity(),
NULL);
}

Shutdown()
{
/* Remove the type on shutdown */
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());
}</cpp>

===Creating Handles===
Creating the Handles is fairly easy once we have a valid pointer to stuff in it.
<cpp>/* native CreateFile(const String:file[]) */
static cell_t sm_CreateFile(IPluginContext *pContext, const cell_t *params)
{
char path[PLATFORM_MAX_PATH];
char *filename;

/* Get the filename */
pContext->LocalToString(params[1], &filename);
/* Build a full path */
g_pSM->BuildPath(Path_SM, path, sizeof(path), "%s", filename);

/* Open for writing */
FILE *fp = fopen(path, "wt");
if (!fp)
{
return BAD_HANDLE;
}

/* Create the Handle with our type, the FILE pointer, the plugin's identity, and our identity */
return g_pHandleSys->CreateHandle(g_FileType,
fp,
pContext->GetIdentity(),
myself->GetIdentity(),
NULL);
}</cpp>

===Reading/Checking Handles===
Handles aren't very useful unless you have natives to use them. Let's say we want to write lines of text to our File type.
<cpp>/* native WriteLine(Handle:hndl, const String:line[]); */
static cell_t sm_WriteLine(IPluginContext *pContext, const cell_t *params)
{
Handle_t hndl = static_cast<Handle_t>(params[1]);
HandleError err;
HandleSecurity sec;

/* Build our security descriptor */
sec.pOwner = NULL; /* Not needed, owner access is not checked */
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */

/* Attempt to read the given handle as our type, using our security info.
* Note that we read the pointer directly in with a little cast.
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.
*/
FILE *fp;
if ((herr = g_pHandleSys->ReadHandle(hndl, g_FileType, &sec, (void **)&fp))
!= HandleError_None)
{
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);
}

/* Get the text */
char *text;
pContext->LocalToString(params[2], &text);

/* Write it */
fputs(text, fp);

return 1;
}</cpp>

===CloseHandle Support===
Lastly, we need to make it so <tt>CloseHandle()</tt> or <tt>FreeHandle()</tt> will close our file pointer when removing the Handle, which we skipped before.
<cpp>class FileTypeHandler : public IHandleTypeDispatch
{
public:
void OnHandleDestroy(HandleType_t type, void *object)
{
fclose( (FILE *)object );
}
};</cpp>

==Restricting CloseHandle==
Let's say that, for various reasons, you don't want users to be able to call CloseHandle(). An example of this might be a data type that is non-temporary, or is being called from a forward, and thus should not be touched. Or, you might have a special deconstructor that takes extra parameters, and thus you need a separate destroy function.

For example, let's create a separate function called <tt>CloseFile</tt>. It doesn't do anything particularly special, but we are going to force its usage over CloseHandle().

===New Security Rules===
<cpp>Initialize()
{
/* Create default access rights */
HandleAccess acc;
g_pHandleSys->InitAccessDefaults(NULL, &acc);

/* Restrict delete to only our identity */
acc.access[HandleAccess_Delete] = HANDLE_RESTRICT_IDENTITY;

/* Register the type with our security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
&acc,
myself->GetIdentity(),
NULL);
}</cpp>

===Implementing the Native===
<cpp>/* native Closefile(Handle:hndl); */
static cell_t sm_CloseFile(IPluginContext *pContext, const cell_t *params)
{
Handle_t hndl = static_cast<Handle_t>(params[1]);
HandleError err;
HandleSecurity sec;

/* Build our security descriptor */
sec.pOwner = pContext->GetIdentity(); /* Needed, HANDLE_RESTRICT_OWNER is default */
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */

/* Attempt to read the given handle as our type, using our security info.
* Note that we read the pointer directly in with a little cast.
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.
*/
FILE *fp;
if ((herr = g_pHandleSys->FreeHandle(hndl, &src))
!= HandleError_None)
{
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);
}

return 1;
}</cpp>

==Restricting CloseHandle Per-Handle==
Taking our above example, it is possible that we might want some Handles to be closed via CloseHandle(), but others not. Again, this is useful if you wish to pass a Handle as read-only to a plugin, commonly done when using non-temporary structures or Handles used in Forwards.

In this example, we'll create a global instance of our file type, and this instance will be denied access to CloseHandle(), whereas files returned by OpenFile() will not.

===Implementation===
<cpp>Handle_t g_GlobalFile;

Initialize()
{
/* Register the type with default security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
NULL,
myself->GetIdentity(),
NULL);

/* Create our 'global' file */
FILE *fp = tmpfile();

/* Set up the security descriptor */
HandleSecurity sec;
sec.pOwner = NULL; /* No owner for this Handle */
sec.pIdentity = myself->GetIdentity(); /* Only this identity will be allowed */

/* Set up the access permissions */
HandleAccess rules;
g_pHandleSys->InitAccessDefaults(NULL, &rules);
rules.access[HandleAccess_Delete] |= HANDLE_RESTRICT_IDENTITY;

/* Finally, create the Handle with our rules */
g_GlobalFile = g_pHandleSys->CreateHandleEx(g_FileType, fp, &sec, &rules, NULL);
}

Shutdown()
{
/* Remove our global Handle (not needed, but we do it for clarity */
HandleSecurity sec;
sec.pOwner = NULL;
sec.pIdentity = myself->GetIdentity();

g_pHandleSys->FreeHandle(g_GlobalFile, &sec);

/* Remove the type on shutdown */
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());
}</cpp>

[[Category:SourceMod Development]]

Timers (SourceMod Scripting)

2007-06-08T14:27:37Z

Bennyboy: /* Data Packs */

Timers in [[SourceMod]] are timed events that occur once or repeatedly at a given interval.

=Introduction=
Timers allow you to set an interval, a function to use as the event callback, and an optional Handle to pass through the callback. This is useful for saving data asynchronously.

All timer functions are in <tt>plugins/include/timers.inc</tt>.

=Basic Usage=
==One-Time Timers==
One-time timers are timers that only execute once. An example of a one-time timer might look like:

<pawn>public OnPluginStart()
{
CreateTimer(5.0, LoadStuff)
}

public Action:LoadStuff(Handle:timer)
{
PrintToServer("Loading stuff!")
}</pawn>

This code will print "Loading stuff!" to the server console five seconds after the map loads. The return value has no meaning for one-time timers.

==Repeatable Timers==
Repeatable timers execute infinitely many times, once every interval. Based on the return value, they either continue or cancel.

For example, say you want to display a message five times, once every three seconds:
<pawn>
DoMessage()
{
CreateTimer(3.0, PrintMsg, _, TIMER_REPEAT)
}

public Action:PrintMsg(Handle:timer)
{
static NumPrinted = 0
if (NumPrinted++ >= 5)
{
PrintToServer("Warning! This is a message.")
NumPrinted = 0

return Plugin_Stop
}

return Plugin_Continue
}</pawn>

Note that <tt>Plugin_Stop</tt> stops the timer, and <tt>Plugin_Continue</tt> allows it to continue repeating.

=Passing Data=
==Simple Values==
As mentioned earlier, timers let you pass values on to the callback function. This value can be any type. For example, let's say we want to print a message to a player fifteen seconds after they connect. However, we want to cancel the timer if the player disconnects. Implementing this is very easy:

<pawn>#define MAX_PLAYERS 256

new Handle:WelcomeTimers[MAX_PLAYERS+1]

public OnClientPutInServer(client)
{
WelcomeTimers[client] = CreateTimer(15.0, WelcomePlayer, client)
}

public OnClientDisconnect(client)
{
if (WelcomeTimers[client] != INVALID_HANDLE)
{
KillTimer(WelcomeTimers[client])
WelcomeTimers[client] = INVALID_HANDLE
}
}

public Action:WelcomePlayer(Handle:timer, client)
{
PrintToConsole(client, "Welcome to the server!")
WelcomeTimers[client] = INVALID_HANDLE
}</pawn>

==Handles==
If you want to pass a Handle as a value, you have the option of using <tt>TIMER_HNDL_CLOSE</tt>, which will automatically call <tt>CloseHandle()</tt> for you once the timer dies.

==Data Packs==
Data packs are packable structures that can be used to hold asynchronous data (data that must be saved and unpacked for later). They are especially useful for timers, and thus there exists a helper function, called <tt>CreateDataTimer()</tt>, which creates a timer using a data pack handle. The handle is created and closed automatically for you.

The above example could be rewritten as:
<pawn>#define MAX_PLAYERS 256

new Handle:WelcomeTimers[MAX_PLAYERS+1]

public OnClientPutInServer(client)
{
new Handle:pack = CreateDataPack();
WelcomeTimers[client] = CreateDataTimer(15.0, WelcomePlayer, pack)
WritePackCell(pack, client)
WritePackString(pack, "Welcome to the server!")
}

public OnClientDisconnect(client)
{
if (WelcomeTimers[client] != INVALID_HANDLE)
{
KillTimer(WelcomeTimers[client])
WelcomeTimers[client] = INVALID_HANDLE
}
}

public Action:WelcomePlayer(Handle:timer, Handle:pack)
{
decl String:str[128]
new client

/* Set to the beginning and unpack it */
ResetPack(pack)
client = ReadPackCell(pack)
ReadPackString(pack, str, sizeof(str))

PrintToConsole(client, "%s", str)
WelcomeTimers[client] = INVALID_HANDLE
}</pawn>

=Notes=
==Accuracy==
The smallest possible interval is 0.1 seconds. Timers have high precision (floating point) but low accuracy, as the current time is based on the in-game tick count, not the system clock. This has two implications:
*If the server is paused (not ticking), timers will not run.
*The server will not always tick at an exact interval.

For example, a 1.234 second interval timer starting from time <tt>t</tt> might not tick until <tt>t+1.242</tt> at a tickrate of 66 ticks per second.

==Timer Death==
All timers are guaranteed to die either by:
*<tt>CloseHandle()</tt> being called (or on plugin unload);
*<tt>KillTimer()</tt> being called;
*<tt>Plugin_Stop</tt> being returned from a repeatable timer;
*<tt>TriggerTimer()</tt> being called on a one-time timer;
*Execution of a one-time timer finishes.

When a timer dies, if <tt>TIMER_HNDL_CLOSE</tt> is set, the Handle will always be closed with the permissions that <tt>CloseHandle()</tt> uses by default. Since timers cannot be cloned, there should be no ownership issues.

==Changing Intervals==
The interval of a timer cannot be changed as of this writing. The timer must be killed and a new one created.

==AMX Mod X==
Unlike [[AMX Mod X]]'s <tt>set_task</tt> function, you cannot pass arrays using <tt>CreateTimer</tt>. To accomplish this, you should use the data pack functionality explained above.

Similarly, there are no flags for counted repeats (non-infinite loops) or timers based on the map start or end. These must be done manually.

=External Links=
*[http://www.sourcemod.net/devlog/?p=130 On Timer Design, Part 3] (SourceMod DevLog)
*[http://www.sourcemod.net/devlog/?p=119 On Timer Design, Part 2] (SourceMod DevLog)
*[http://www.sourcemod.net/devlog/?p=118 On Timer Design, Part 1] (SourceMod DevLog)

[[Category:SourceMod Scripting]]
[[Category:SourceMod Development]]