UNLOZE/sourcemod
10
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update dhooks.inc documentation for consistency (#1658)

Browse Source 
* Update dhooks.inc documentation for consistency

- Modifies whitespace (change tabs to spaces for non initial indents, fix alignments, create consistency with rest of SM docs)
- Change `/*` to `/**` for consistency and to indicate comment doc
- Removes incorrect `@noreturn` doc

* Split long comments across multiple lines

* Remove `@noreturn` in IGameConfigs.h

* Remove `@noreturn` from IGameHelpers.h

* Remove `@noreturn` from asm.c

* Add `@noreturn` to ThrowError

* Add `@noreturn` and `@error` to ThrowNativeError
This commit is contained in:
Arron Vinyard 2022-02-01 12:46:59 -05:00 committed by Your Name
parent 370fa8209b
commit 210219030e
6 changed files with 363 additions and 337 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

199
plugins/include/dhooks.inc
View File

@ -119,18 +119,18 @@ enum CallingConvention
enum HookMode
{
Hook_Pre, // Callback will be executed BEFORE the original function.
Hook_Post // Callback will be executed AFTER the original function.
Hook_Pre, /**< Callback will be executed BEFORE the original function. */
Hook_Post /**< Callback will be executed AFTER the original function. */
};
enum MRESReturn
{
MRES_ChangedHandled = -2, // Use changed values and return MRES_Handled
MRES_ChangedOverride, // Use changed values and return MRES_Override
MRES_Ignored, // plugin didn't take any action
MRES_Handled, // plugin did something, but real function should still be called
MRES_Override, // call real function, but use my return value
MRES_Supercede // skip real function; use my return value
MRES_ChangedHandled = -2, /**< Use changed values and return MRES_Handled */
MRES_ChangedOverride, /**< Use changed values and return MRES_Override */
MRES_Ignored, /**< plugin didn't take any action */
MRES_Handled, /**< plugin did something, but real function should still be called */
MRES_Override, /**< call real function, but use my return value */
MRES_Supercede /**< skip real function; use my return value */
};
enum DHookPassFlag
@ -194,6 +194,7 @@ typeset DHookRemovalCB
{
function void (int hookid);
};
typeset DHookCallback
{
// Function Example: void Ham::Test() with this pointer ignore
@ -368,16 +369,17 @@ methodmap DHookParam < Handle
//
// @param num Parameter number to check, starting at 1.
//
// @return True if null, false otherwise.
// @return true if null, false otherwise.
// @error Non-pointer parameter.
public native bool IsNull(int num);
// Get param address (Use only for ptr param types)
//
// @param num Param number to get. (Example if the function has 2 params and you need the value of the first param num would be 1.)
// @param num Param number to get. (Example if the function has 2 params and you need the value
// of the first param num would be 1.)
//
// @return Address of the parameter.
// @error Invalid handle. Invalid param number. Invalid param type.
// @return address of the parameter.
public native Address GetAddress(int num);
};
@ -449,7 +451,7 @@ methodmap DHookSetup < Handle
// @param source Whether to look in Offsets, Signatures, or Addresses.
// @param name Name of the property to find.
//
// @return True on success, false if nothing was found.
// @return true on success, false if nothing was found.
// @error Invalid setup or gamedata handle.
public native bool SetFromConf(Handle gameconf, SDKFuncConfSource source, const char[] name);
@ -549,7 +551,7 @@ methodmap DynamicHook < DHookSetup
//
// @param hookid Hook id to remove.
//
// @return True on success, false otherwise
// @return true on success, false otherwise
public static native bool RemoveHook(int hookid);
};
@ -600,7 +602,7 @@ methodmap DynamicDetour < DHookSetup
// You can access the parameters and get/set the return value.
// @param callback Callback function.
//
// @return True if detour was enabled, false otherwise.
// @return true if detour was enabled, false otherwise.
// @error Hook handle is not setup for a detour.
public native bool Enable(HookMode mode, DHookCallback callback);
@ -609,30 +611,31 @@ methodmap DynamicDetour < DHookSetup
// @param mode The hook mode to disable - pre or post.
// @param callback Callback function.
//
// @return True if detour was disabled, false otherwise.
// @return true if detour was disabled, false otherwise.
// @error Hook handle is not setup for a detour or function is not detoured.
public native bool Disable(HookMode mode, DHookCallback callback);
};
/* Adds an entity listener hook
/**
* Adds an entity listener hook
*
* @param type Type of listener to add
* @param callback Callback to use
*
* @noreturn
*/
native void DHookAddEntityListener(ListenType type, ListenCB callback);
/* Removes an entity listener hook
/**
* Removes an entity listener hook
*
* @param type Type of listener to remove
* @param callback Callback this listener was using
*
* @return True if one was removed false otherwise.
* @return true if one was removed, false otherwise
*/
native bool DHookRemoveEntityListener(ListenType type, ListenCB callback);
/* Creates a hook
/**
* Creates a hook
*
* @param offset vtable offset of function to hook
* @param hooktype Type of hook
@ -666,7 +669,8 @@ native DynamicDetour DHookCreateDetour(Address funcaddr, CallingConvention callC
* @param name Name of the function in the gamedata to load.
*
* @return Setup handle for the detour or INVALID_HANDLE if offset/signature/address wasn't found.
* @error Failed to create detour setup handle, invalid gamedata handle, invalid callback function or failed to find function in gamedata.
* @error Failed to create detour setup handle, invalid gamedata handle, invalid callback function or
* failed to find function in gamedata.
*/
native DHookSetup DHookCreateFromConf(Handle gameconf, const char[] name);
@ -678,7 +682,7 @@ native DHookSetup DHookCreateFromConf(Handle gameconf, const char[] name);
* @param source Whether to look in Offsets or Signatures.
* @param name Name of the property to find.
*
* @return True on success, false if nothing was found.
* @return true on success, false if nothing was found.
* @error Invalid setup or gamedata handle.
*/
native bool DHookSetFromConf(Handle setup, Handle gameconf, SDKFuncConfSource source, const char[] name);
@ -687,10 +691,11 @@ native bool DHookSetFromConf(Handle setup, Handle gameconf, SDKFuncConfSource so
* Enable the detour of the function described in the hook setup handle.
*
* @param setup Hook setup handle
* @param post True to make the hook a post hook. (If you need to change the retunr value or need the return value use a post hook! If you need to change params and return use a pre and post hook!)
* @param post true to make the hook a post hook. (If you need to change the return value or need the return
* value use a post hook! If you need to change params and return use a pre and post hook!)
* @param callback Callback function
*
* @return True if detour was enabled, false otherwise.
* @return true if detour was enabled, false otherwise.
* @error Hook handle is not setup for a detour.
*/
native bool DHookEnableDetour(Handle setup, bool post, DHookCallback callback);
@ -699,15 +704,16 @@ native bool DHookEnableDetour(Handle setup, bool post, DHookCallback callback);
* Disable the detour of the function described in the hook setup handle.
*
* @param setup Hook setup handle
* @param post True to disable a post hook.
* @param post true to disable a post hook.
* @param callback Callback function
*
* @return True if detour was disabled, false otherwise.
* @return true if detour was disabled, false otherwise.
* @error Hook handle is not setup for a detour or function is not detoured.
*/
native bool DHookDisableDetour(Handle setup, bool post, DHookCallback callback);
/* Adds param to a hook setup
/**
* Adds param to a hook setup
*
* @param setup Setup handle to add the param to.
* @param type Param type
@ -716,124 +722,141 @@ native bool DHookDisableDetour(Handle setup, bool post, DHookCallback callback);
* @param custom_register The register this argument is passed in instead of the stack.
*
* @error Invalid setup handle or too many params added (request upping the max in thread)
* @noreturn
*/
native void DHookAddParam(Handle setup, HookParamType type, int size=-1, DHookPassFlag flag=DHookPass_ByVal, DHookRegister custom_register=DHookRegister_Default);
/* Hook entity
/**
* Hook entity
*
* @param setup Setup handle to use to add the hook.
* @param post True to make the hook a post hook. (If you need to change the return value or need the return value use a post hook! If you need to change params and return use a pre and post hook!)
* @param post true to make the hook a post hook. (If you need to change the return value or need the return
* value use a post hook! If you need to change params and return use a pre and post hook!)
* @param entity Entity index to hook on.
* @param removalcb Callback for when the hook is removed (Entity hooks are auto-removed on entity destroyed and will call this callback)
* @param removalcb Callback for when the hook is removed (Entity hooks are auto-removed on entity destroyed and
* will call this callback)
* @param callback Optional callback function, if not set here must be set when creating the hook.
*
* @error Invalid setup handle, invalid address, invalid hook type or invalid callback.
* @return INVALID_HOOK_ID on fail a hookid on success
* @error Invalid setup handle, invalid address, invalid hook type or invalid callback.
*/
native int DHookEntity(Handle setup, bool post, int entity, DHookRemovalCB removalcb=INVALID_FUNCTION, DHookCallback callback=INVALID_FUNCTION);
/* Hook gamerules
/**
* Hook gamerules
*
* @param setup Setup handle to use to add the hook.
* @param post True to make the hook a post hook. (If you need to change the return value or need the return value use a post hook! If you need to change params and return use a pre and post hook!)
* @param removalcb Callback for when the hook is removed (Game rules hooks are auto-removed on map end and will call this callback)
* @param post true to make the hook a post hook. (If you need to change the return value or need the return
* value use a post hook! If you need to change params and return use a pre and post hook!)
* @param removalcb Callback for when the hook is removed (Game rules hooks are auto-removed on map end and will
* call this callback)
* @param callback Optional callback function, if not set here must be set when creating the hook.
*
* @error Invalid setup handle, invalid address, invalid hook type or invalid callback.
* @return INVALID_HOOK_ID on fail a hookid on success
* @error Invalid setup handle, invalid address, invalid hook type or invalid callback.
*/
native int DHookGamerules(Handle setup, bool post, DHookRemovalCB removalcb=INVALID_FUNCTION, DHookCallback callback=INVALID_FUNCTION);
/* Hook a raw pointer
/**
* Hook a raw pointer
*
* @param setup Setup handle to use to add the hook.
* @param post True to make the hook a post hook. (If you need to change the return value or need the return value use a post hook! If you need to change params and return use a pre and post hook!)
* @param post true to make the hook a post hook. (If you need to change the return value or need the return
* alue use a post hook! If you need to change params and return use a pre and post hook!)
* @param addr This pointer address.
* @param removalcb Callback for when the hook is removed (Entity hooks are auto-removed on entity destroyed and will call this callback)
* @param removalcb Callback for when the hook is removed (Entity hooks are auto-removed on entity destroyed and
* will call this callback)
* @param callback Optional callback function, if not set here must be set when creating the hook.
*
* @error Invalid setup handle, invalid address, invalid hook type or invalid callback.
* @return INVALID_HOOK_ID on fail a hookid on success
* @error Invalid setup handle, invalid address, invalid hook type or invalid callback.
*/
native int DHookRaw(Handle setup, bool post, Address addr, DHookRemovalCB removalcb=INVALID_FUNCTION, DHookCallback callback=INVALID_FUNCTION);
/* Remove hook by hook id
/**
* Remove hook by hook id
*
* @param hookid Hook id to remove
*
* @return true on success false otherwise
* @return true on success, false otherwise
* @note This will not fire the removal callback!
*/
native bool DHookRemoveHookID(int hookid);
/* Get param value (Use only for: int, entity, bool or float param types)
/**
* Get param value (Use only for: int, entity, bool or float param types)
*
* @param hParams Handle to params structure
* @param num Param number to get. (Example if the function has 2 params and you need the value of the first param num would be 1. 0 Will return the number of params stored)
* @param num Param number to get. (Example if the function has 2 params and you need the value of the first
* param num would be 1. 0 Will return the number of params stored)
*
* @error Invalid handle. Invalid param number. Invalid param type.
* @return value if num greater than 0. If 0 returns paramcount.
* @error Invalid handle. Invalid param number. Invalid param type.
*/
native any DHookGetParam(Handle hParams, int num);
/* Get vector param value
/**
* Get vector param value
*
* @param hParams Handle to params structure
* @param num Param number to get. (Example if the function has 2 params and you need the value of the first param num would be 1.)
* @param num Param number to get. (Example if the function has 2 params and you need the value of the first
* param num would be 1.)
* @param vec Vector buffer to store result.
*
* @error Invalid handle. Invalid param number. Invalid param type.
* @noreturn
*/
native void DHookGetParamVector(Handle hParams, int num, float vec[3]);
/* Get string param value
/**
* Get string param value
*
* @param hParams Handle to params structure
* @param num Param number to get. (Example if the function has 2 params and you need the value of the first param num would be 1.)
* @param num Param number to get. (Example if the function has 2 params and you need the value of the first
* param num would be 1.)
* @param buffer String buffer to store result
* @param size Buffer size
*
* @error Invalid handle. Invalid param number. Invalid param type.
* @noreturn
*/
native void DHookGetParamString(Handle hParams, int num, char[] buffer, int size);
/* Set param value (Use only for: int, entity, bool or float param types)
/**
* Set param value (Use only for: int, entity, bool or float param types)
*
* @param hParams Handle to params structure
* @param num Param number to set (Example if the function has 2 params and you need to set the value of the first param num would be 1.)
* @param num Param number to set (Example if the function has 2 params and you need to set the value of the
* first param num would be 1.)
* @param value Value to set it as (only pass int, bool, float or entity index)
*
* @error Invalid handle. Invalid param number. Invalid param type.
* @noreturn
*/
native void DHookSetParam(Handle hParams, int num, any value);
/* Set vector param value
/**
* Set vector param value
*
* @param hParams Handle to params structure
* @param num Param number to set (Example if the function has 2 params and you need to set the value of the first param num would be 1.)
* @param num Param number to set (Example if the function has 2 params and you need to set the value of the
* first param num would be 1.)
* @param vec Value to set vector as.
*
* @error Invalid handle. Invalid param number. Invalid param type.
* @noreturn
*/
native void DHookSetParamVector(Handle hParams, int num, float vec[3]);
/* Set string param value
/**
* Set string param value
*
* @param hParams Handle to params structure
* @param num Param number to set (Example if the function has 2 params and you need to set the value of the first param num would be 1.)
* @param num Param number to set (Example if the function has 2 params and you need to set the value of the
* first param num would be 1.)
* @param value Value to set string as.
*
* @error Invalid handle. Invalid param number. Invalid param type.
* @noreturn
*/
native void DHookSetParamString(Handle hParams, int num, char[] value);
/* Get return value (Use only for: int, entity, bool or float return types)
/**
* Get return value (Use only for: int, entity, bool or float return types)
*
* @param hReturn Handle to return structure
*
@ -842,60 +865,61 @@ native void DHookSetParamString(Handle hParams, int num, char[] value);
*/
native any DHookGetReturn(Handle hReturn);
/* Get return vector value
/**
* Get return vector value
*
* @param hReturn Handle to return structure
* @param vec Vector buffer to store result in. (In pre hooks will be default value (0.0,0.0,0.0))
*
* @error Invalid Handle, invalid type.
* @noreturn
*/
native void DHookGetReturnVector(Handle hReturn, float vec[3]);
/* Get return string value
/**
* Get return string value
*
* @param hReturn Handle to return structure
* @param buffer String buffer to store result in. (In pre hooks will be default value "")
* @param size String buffer size
*
* @error Invalid Handle, invalid type.
* @noreturn
*/
native void DHookGetReturnString(Handle hReturn, char[] buffer, int size);
/* Set return value (Use only for: int, entity, bool or float return types)
/**
* Set return value (Use only for: int, entity, bool or float return types)
*
* @param hReturn Handle to return structure
* @param value Value to set return as
*
* @error Invalid Handle, invalid type.
* @noreturn
*/
native void DHookSetReturn(Handle hReturn, any value);
/* Set return vector value
/**
* Set return vector value
*
* @param hReturn Handle to return structure
* @param vec Value to set return vector as
*
* @error Invalid Handle, invalid type.
* @noreturn
*/
native void DHookSetReturnVector(Handle hReturn, float vec[3]);
/* Set return string value
/**
* Set return string value
*
* @param hReturn Handle to return structure
* @param value Value to set return string as
*
* @error Invalid Handle, invalid type.
* @noreturn
*/
native void DHookSetReturnString(Handle hReturn, char[] value);
//WE SHOULD WRAP THESE AROUND STOCKS FOR NON PTR AS WE SUPPORT BOTH WITH THESE NATIVE'S
/* Gets an objects variable value
/**
* Gets an objects variable value
*
* @param hParams Handle to params structure
* @param num Param number to get.
@ -907,7 +931,8 @@ native void DHookSetReturnString(Handle hReturn, char[] value);
*/
native any DHookGetParamObjectPtrVar(Handle hParams, int num, int offset, ObjectValueType type);
/* Sets an objects variable value
/**
* Sets an objects variable value
*
* @param hParams Handle to params structure
* @param num Param number to set.
@ -916,11 +941,11 @@ native any DHookGetParamObjectPtrVar(Handle hParams, int num, int offset, Object
* @param value The value to set the var to.
*
* @error Invalid handle. Invalid param number. Invalid param type. Invalid Object type.
* @noreturn
*/
native void DHookSetParamObjectPtrVar(Handle hParams, int num, int offset, ObjectValueType type, any value);
/* Gets an objects vector variable value
/**
* Gets an objects vector variable value
*
* @param hParams Handle to params structure
* @param num Param number to get.
@ -929,11 +954,11 @@ native void DHookSetParamObjectPtrVar(Handle hParams, int num, int offset, Objec
* @param buffer Buffer to store the result vector
*
* @error Invalid handle. Invalid param number. Invalid param type. Invalid Object type.
* @noreturn
*/
native void DHookGetParamObjectPtrVarVector(Handle hParams, int num, int offset, ObjectValueType type, float buffer[3]);
/* Sets an objects vector variable value
/**
* Sets an objects vector variable value
*
* @param hParams Handle to params structure
* @param num Param number to set.
@ -942,11 +967,11 @@ native void DHookGetParamObjectPtrVarVector(Handle hParams, int num, int offset,
* @param value The value to set the vector var to.
*
* @error Invalid handle. Invalid param number. Invalid param type. Invalid Object type.
* @noreturn
*/
native void DHookSetParamObjectPtrVarVector(Handle hParams, int num, int offset, ObjectValueType type, float value[3]);
/* Gets an objects string variable value
/**
* Gets an objects string variable value
*
* @param hParams Handle to params structure
* @param num Param number to get.
@ -956,27 +981,29 @@ native void DHookSetParamObjectPtrVarVector(Handle hParams, int num, int offset,
* @param size Size of the buffer
*
* @error Invalid handle. Invalid param number. Invalid param type. Invalid Object type.
* @noreturn
*/
native void DHookGetParamObjectPtrString(Handle hParams, int num, int offset, ObjectValueType type, char[] buffer, int size);
/* Checks if a pointer param is null
/**
* Checks if a pointer param is null
*
* @param hParams Handle to params structure
* @param num Param number to check.
*
* @return true if null, false otherwise.
* @error Non pointer param
* @return True if null false otherwise.
*/
native bool DHookIsNullParam(Handle hParams, int num);
/* Get param address (Use only for ptr param types)
/**
* Get param address (Use only for ptr param types)
*
* @param hParams Handle to params structure
* @param num Param number to get. (Example if the function has 2 params and you need the value of the first param num would be 1.)
* @param num Param number to get. (Example if the function has 2 params and you need the value of the first
* param num would be 1.)
*
* @return Address of the parameter.
* @error Invalid handle. Invalid param number. Invalid param type.
* @return address of the parameter.
*/
native Address DHookGetParamAddress(Handle hParams, int num);

2
plugins/include/functions.inc
View File

@ -466,6 +466,8 @@ native void CreateNative(const char[] name, NativeCall func);
* @param error Error code to use.
* @param fmt Error message format.
* @param ... Format arguments.
* @noreturn
* @error Always!
*/
native int ThrowNativeError(int error, const char[] fmt, any ...);

1
plugins/include/sourcemod.inc
View File

@ -348,6 +348,7 @@ native void SetFailState(const char[] string, any ...);
*
* @param fmt String format.
* @param ... Format arguments.
* @noreturn
* @error Always!
*/
native void ThrowError(const char[] fmt, any ...);

2
public/IGameConfigs.h
View File

@ -158,7 +158,6 @@ namespace SourceMod
*
* @param sectionname Section name to hook.
* @param listener Listener callback.
* @noreturn
*/
virtual void AddUserConfigHook(const char *sectionname, ITextListener_SMC *listener) =0;
@ -167,7 +166,6 @@ namespace SourceMod
*
* @param sectionname Section name to unhook.
* @param listener Listener callback.
* @noreturn
*/
virtual void RemoveUserConfigHook(const char *sectionname, ITextListener_SMC *listener) =0;

1
public/IGameHelpers.h
View File

@ -188,7 +188,6 @@ namespace SourceMod
*
* @param hndl CBaseHandle object.
* @param pEnt Edict pointer.
* @noreturn
*/
virtual void SetHandleEntity(CBaseHandle &hndl, edict_t *pEnt) =0;

1
public/asm/asm.c
View File

@ -24,7 +24,6 @@
*
* @param dest Destination buffer where a call opcode + addr (5 bytes) has just been written.
* @param pc The program counter value that needs to be set (usually the next address from the source).
* @noreturn
*/
void check_thunks(unsigned char *dest, unsigned char *pc)
{