AlliedModders Wiki - User contributions [en]

Optional Requirements (SourceMod Scripting)

2008-07-20T15:51:19Z

Zerak: /* Optional Natives */

Normally, if you use natives from an extension or another plugin, your plugin will not load unless those natives exist. However, it is possible to make your dependencies "optional." This article details how.

=Disabling Requirements=
==Extensions==
To disable an extension being marked as "required," remove the <tt>REQUIRE_EXTENSIONS</tt> define. For example:

<pawn>#include <sourcemod>
#undef REQUIRE_EXTENSIONS
#include <sdktools></pawn>

Note that any extensions included after the <tt>#undef</tt> will also be marked as not required. Thus, you may need to move the include down, or do something like:

<pawn>#include <sourcemod>
#undef REQUIRE_EXTENSIONS
#include <sdktools>
#define REQUIRE_EXTENSIONS</pawn>

==Plugins==
To disable an plugin being marked as "required," remove the <tt>REQUIRE_PLUGIN</tt> define. For example:

<pawn>#include <sourcemod>
#undef REQUIRE_PLUGIN
#include <ircrelay></pawn>

Note that any plugins included after the <tt>#undef</tt> will also be marked as not required. Thus, you may need to move the include down, or do something like:

<pawn>#include <sourcemod>
#undef REQUIRE_PLUGIN
#include <ircrelay>
#define REQUIRE_PLUGIN</pawn>

==Optional Natives==
To mark a native as optional, use <tt>MarkNativeAsOptional</tt>. It should be called in <tt>AskPluginLoad</tt>. For example:

<pawn>public bool:AskPluginLoad(Handle:myself, bool:late, String:error[], err_max)
{
MarkNativeAsOptional("SDKCall");
return true;
}</pawn>

=Checking Optional Dependencies=
If you use a plugin or extension as an optional dependency, you may need to check whether it exists. For example, let's say we're relying on a plugin with the library name of "ircrelay." The way to always know whether ircrelay is loaded (and working) is:

<pawn>new bool:ircrelay = false;

public OnPluginStart()
{
ircrelay = LibraryExists("ircrelay");
}

public OnLibraryRemoved(const String:name[])
{
if (StrEqual(name, "ircrelay"))
{
ircrelay = false;
}
}

public OnLibraryAdded(const String:name[])
{
if (StrEqual(name, "ircrelay"))
{
ircrelay = true;
}
}</pawn>

=Creating a Dependency=
Allowing other plugins to use your plugin as a library requires making an include file with two structures (the second of which is optional). The first structure must look like this:

<pawn>public SharedPlugin:__pl_myfile =
{
name = "myfile",
file = "myfile.smx",
#if defined REQUIRE_PLUGIN
required = 1,
#else
required = 0,
#endif
};</pawn>

The basic format is:
*The variable name MUST start with <tt>__pl_</tt> and must end with a unique string.
*The "name" portion is treated as the library name and must be unique.
*The filename must match the filename of the plugin implementing the library.
*The requirement portion should remain unchanged in order to maintain standards.

Additionally, you should expose a function which marks all of your natives as optional. You can do this by:
<pawn>public __pl_myfile_SetNTVOptional()
{
MarkNativeAsOptional("native1");
MarkNativeAsOptional("native2");
MarkNativeAsOptional("native3");
}</pawn>

This function will be secretly called before the plugin loads (if and only if the requirement is optional), thus allowing seamless optional usage by third party developers. Note that the <tt>__pl_</tt> and <tt>_SetNTVOptional</tt> portions must be present, and that everything in between must match the ending of <tt>__pl_</tt> for the <tt>SharedPlugin</tt> structure.

You also must register the library name with SourceMod -- again this should be the unique string. This is should be done inside the <code>OnPluginStart</code> function.

<pawn>
public OnPluginStart()
{
//... code here ...
RegPluginLibrary("myfile");
}
</pawn>

= Full Example =
;''Bounty: bounty.sp''
<pawn>
#include <sourcemod>
#undef REQUIRE_PLUGIN
#include <ircrelay>
</pawn>
;''Bounty: bounty.config.sp''
<pawn>
new bool:plugin_IrcRelay = LibraryExists("ircrelay");
if ((BountyIRC) && (plugin_IrcRelay))
{
RegisterIrcCommand("!bounty", "x", Irc_ViewBounty);
IrcMessage(CHAN_MASTER, "IRC Bounty Running!");
} else {
if ((BountyIRC) && (!plugin_IrcRelay))
{
BountyConsole_Debug("%t", "Bounty IRC Relay failed");
}
}
</pawn>
;''IRC Relay: ircrelay.sp''
<pawn>
public OnPluginStart()
{
//... code here ...
RegPluginLibrary("ircrelay");
}
</pawn>
;''IRC Relay: ircrelay.inc''
<pawn>
public SharedPlugin:__pl_ircrelay =
{
name = "ircrelay",
file = "ircrelay.smx",
#if defined REQUIRE_PLUGIN
required = 1,
#else
required = 0,
#endif
};

public __pl_ircrelay_SetNTVOptional()
{
MarkNativeAsOptional("IrcMessage");
MarkNativeAsOptional("RegisterIrcCommand");
MarkNativeAsOptional("IrcGetCmdArgc");
MarkNativeAsOptional("IrcGetCmdArgv");
}
</pawn>
The <code>name</code> value is what will be checked when you run <code>LibraryExists</code>. This allows the bounty script to fully work, even if the IRC relay plugin is not installed and/or running correctly on your server.

[[Category:SourceMod Scripting]]

Handle API (SourceMod)

2008-03-29T12:38:39Z

Zerak: "cannot" changed to "can also"

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 can also 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 ((err = 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]]