mirror of
https://git.recroomarchive.org/Radium/libradhook.git
synced 2026-08-07 09:10:59 +00:00
api changes, check README
This commit is contained in:
nexusverypro
@@ -10,6 +10,24 @@
|
||||
# define RADHOOK_API
|
||||
#endif // RADHOOK_API
|
||||
|
||||
// versioning
|
||||
#define RADHOOK_VERSION_MAJOR 1
|
||||
#define RADHOOK_VERSION_MINOR 1
|
||||
#define RADHOOK_VERSION_PATCH 0
|
||||
|
||||
#if _MSC_VER
|
||||
# include <sal.h> // for source code annotations
|
||||
#else
|
||||
# define _In_
|
||||
# define _In_opt_
|
||||
# define _Out_
|
||||
# define _Out_opt_
|
||||
# define _Outptr_
|
||||
# define _Ret_z_
|
||||
# define _Success_(expr)
|
||||
# define _Out_writes_to_(size, count)
|
||||
#endif
|
||||
|
||||
enum class RadHookResult : int {
|
||||
Success = 0,
|
||||
AlreadyInstalled,
|
||||
@@ -26,6 +44,7 @@ enum class RadHookResult : int {
|
||||
Unknown,
|
||||
};
|
||||
|
||||
_Ret_z_
|
||||
/**
|
||||
* @brief Creates a human readable name for a status code.
|
||||
*
|
||||
@@ -33,14 +52,15 @@ enum class RadHookResult : int {
|
||||
* @return Null-terminated string describing the status code.
|
||||
*/
|
||||
RADHOOK_API
|
||||
const char*
|
||||
const char*
|
||||
RadHookResultToString(
|
||||
RadHookResult result
|
||||
);
|
||||
);
|
||||
|
||||
struct RadHookOpaque;
|
||||
using RadHookHandle = RadHookOpaque*;
|
||||
|
||||
_Success_(return == RadHookResult::Success)
|
||||
/**
|
||||
* @brief Creates and installs a hook.
|
||||
*
|
||||
@@ -55,20 +75,21 @@ using RadHookHandle = RadHookOpaque*;
|
||||
* @return Operation result.
|
||||
*/
|
||||
RADHOOK_API
|
||||
RadHookResult
|
||||
RadHookResult
|
||||
RadHookCreate(
|
||||
void* target,
|
||||
void* detour,
|
||||
RadHookHandle* outHandle
|
||||
);
|
||||
_In_ void* target,
|
||||
_In_ void* detour,
|
||||
_Out_ RadHookHandle* outHandle
|
||||
);
|
||||
|
||||
_Success_(return == RadHookResult::Success)
|
||||
/**
|
||||
* @brief Creates and installs a hook from a function pointer.
|
||||
*
|
||||
* Convenience overload that accepts a typed function pointer for the target.
|
||||
*
|
||||
* @tparam TargetFn Target function pointer type.
|
||||
* @param target Function to hook.
|
||||
* @param target Target function to hook.
|
||||
* @param detour Replacement function.
|
||||
* @param outHandle Receives the created hook handle on success.
|
||||
*
|
||||
@@ -76,12 +97,13 @@ RadHookCreate(
|
||||
*/
|
||||
template <typename TargetFn>
|
||||
requires std::is_function_v<std::remove_pointer_t<TargetFn>>
|
||||
RadHookResult
|
||||
RadHookResult
|
||||
RadHookCreate(
|
||||
TargetFn target,
|
||||
void* detour,
|
||||
RadHookHandle* outHandle
|
||||
) {
|
||||
_In_ void* detour,
|
||||
_Out_ RadHookHandle* outHandle
|
||||
)
|
||||
{
|
||||
return RadHookCreate(
|
||||
reinterpret_cast<void*>(target),
|
||||
detour,
|
||||
@@ -100,10 +122,10 @@ RadHookCreate(
|
||||
* otherwise the result of the operation.
|
||||
*/
|
||||
RADHOOK_API
|
||||
RadHookResult
|
||||
RadHookResult
|
||||
RadHookEnable(
|
||||
RadHookHandle handle
|
||||
);
|
||||
_In_ RadHookHandle handle
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Disables an installed hook.
|
||||
@@ -116,10 +138,10 @@ RadHookEnable(
|
||||
* otherwise the result of the operation.
|
||||
*/
|
||||
RADHOOK_API
|
||||
RadHookResult
|
||||
RadHookResult
|
||||
RadHookDisable(
|
||||
RadHookHandle handle
|
||||
);
|
||||
_In_ RadHookHandle handle
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Destroys a hook.
|
||||
@@ -132,10 +154,10 @@ RadHookDisable(
|
||||
* @return Operation result.
|
||||
*/
|
||||
RADHOOK_API
|
||||
RadHookResult
|
||||
RadHookResult
|
||||
RadHookDestroy(
|
||||
RadHookHandle handle
|
||||
);
|
||||
_In_ RadHookHandle handle
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Enables every registered hook.
|
||||
@@ -145,7 +167,7 @@ RadHookDestroy(
|
||||
* @return Operation result.
|
||||
*/
|
||||
RADHOOK_API
|
||||
RadHookResult
|
||||
RadHookResult
|
||||
RadHookEnableAll();
|
||||
|
||||
/**
|
||||
@@ -156,7 +178,7 @@ RadHookEnableAll();
|
||||
* @return Operation result.
|
||||
*/
|
||||
RADHOOK_API
|
||||
RadHookResult
|
||||
RadHookResult
|
||||
RadHookDisableAll();
|
||||
|
||||
/**
|
||||
@@ -167,9 +189,10 @@ RadHookDisableAll();
|
||||
* @return Number of registered hooks.
|
||||
*/
|
||||
RADHOOK_API
|
||||
size_t
|
||||
size_t
|
||||
RadHookGetCount();
|
||||
|
||||
_Out_writes_to_(maxCount, return)
|
||||
/**
|
||||
* @brief Retrieves registered hook handles.
|
||||
*
|
||||
@@ -182,11 +205,11 @@ RadHookGetCount();
|
||||
* @return Number of handles copied.
|
||||
*/
|
||||
RADHOOK_API
|
||||
size_t
|
||||
size_t
|
||||
RadHookGetHandles(
|
||||
RadHookHandle* outHandles,
|
||||
size_t maxCount
|
||||
);
|
||||
_Out_ RadHookHandle* outHandles,
|
||||
_In_ size_t maxCount
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Checks whether a hook handle is valid.
|
||||
@@ -196,10 +219,10 @@ RadHookGetHandles(
|
||||
* @return true if the handle refers to a registered hook; otherwise false.
|
||||
*/
|
||||
RADHOOK_API
|
||||
bool
|
||||
bool
|
||||
RadHookIsValid(
|
||||
RadHookHandle handle
|
||||
);
|
||||
_In_ RadHookHandle handle
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Checks whether a hook is currently enabled.
|
||||
@@ -209,10 +232,10 @@ RadHookIsValid(
|
||||
* @return true if the hook is enabled; otherwise false.
|
||||
*/
|
||||
RADHOOK_API
|
||||
bool
|
||||
bool
|
||||
RadHookIsEnabled(
|
||||
RadHookHandle handle
|
||||
);
|
||||
_In_ RadHookHandle handle
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Returns the hooked target function.
|
||||
@@ -223,10 +246,10 @@ RadHookIsEnabled(
|
||||
* is invalid.
|
||||
*/
|
||||
RADHOOK_API
|
||||
void*
|
||||
void*
|
||||
RadHookGetTarget(
|
||||
RadHookHandle handle
|
||||
);
|
||||
_In_ RadHookHandle handle
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Returns the detour function.
|
||||
@@ -237,10 +260,10 @@ RadHookGetTarget(
|
||||
* invalid.
|
||||
*/
|
||||
RADHOOK_API
|
||||
void*
|
||||
void*
|
||||
RadHookGetDetour(
|
||||
RadHookHandle handle
|
||||
);
|
||||
_In_ RadHookHandle handle
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Returns the trampoline containing the relocated original code.
|
||||
@@ -253,10 +276,10 @@ RadHookGetDetour(
|
||||
* @return Pointer to the trampoline, or nullptr if unavailable.
|
||||
*/
|
||||
RADHOOK_API
|
||||
void*
|
||||
void*
|
||||
RadHookGetOriginal(
|
||||
RadHookHandle handle
|
||||
);
|
||||
_In_ RadHookHandle handle
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Returns the trampoline cast to a function pointer type.
|
||||
@@ -267,32 +290,125 @@ RadHookGetOriginal(
|
||||
* @return Trampoline cast to @p FnPtr.
|
||||
*/
|
||||
template <typename FnPtr>
|
||||
FnPtr
|
||||
FnPtr
|
||||
RadHookGetOriginalAs(
|
||||
RadHookHandle handle
|
||||
) {
|
||||
_In_ RadHookHandle handle
|
||||
)
|
||||
{
|
||||
return reinterpret_cast<FnPtr>(RadHookGetOriginal(handle));
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Enumerates currently registered hooks.
|
||||
*
|
||||
* Copies up to @p maxCount active hook handles into @p out.
|
||||
* Handles are written in no particular order.
|
||||
*
|
||||
* This function only returns hooks that are currently registered
|
||||
* and not destroyed.
|
||||
*
|
||||
* @param out Destination buffer for hook handles.
|
||||
* @param maxCount Maximum number of handles to copy.
|
||||
*
|
||||
* @return Number of hook handles written into @p out.
|
||||
*/
|
||||
_Out_writes_to_(maxCount, return)
|
||||
/**
|
||||
* @brief Enumerates currently registered hooks.
|
||||
*
|
||||
* Copies up to @p maxCount active hook handles into @p out.
|
||||
* Handles are written in no particular order.
|
||||
*
|
||||
* This function only returns hooks that are currently registered
|
||||
* and not destroyed.
|
||||
*
|
||||
* @param out Destination buffer for hook handles.
|
||||
* @param maxCount Maximum number of handles to copy.
|
||||
*
|
||||
* @return Number of hook handles written into @p out.
|
||||
*/
|
||||
RADHOOK_API
|
||||
size_t
|
||||
RadHookEnumerate(
|
||||
RadHookHandle* out,
|
||||
size_t maxCount
|
||||
);
|
||||
_Out_ RadHookHandle* out,
|
||||
_In_ size_t maxCount
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Returns the library version.
|
||||
*
|
||||
* Any of the output parameters may be nullptr if that component is not
|
||||
* needed. Useful for verifying ABI compatibility when radhook is loaded
|
||||
* as a shared library independently of the consuming module.
|
||||
*
|
||||
* @param outMajor Receives the major version, or nullptr.
|
||||
* @param outMinor Receives the minor version, or nullptr.
|
||||
* @param outPatch Receives the patch version, or nullptr.
|
||||
*/
|
||||
RADHOOK_API
|
||||
void
|
||||
RadHookGetVersion(
|
||||
_Out_opt_ int* outMajor,
|
||||
_Out_opt_ int* outMinor,
|
||||
_Out_opt_ int* outPatch
|
||||
);
|
||||
|
||||
_Success_(return == RadHookResult::Success)
|
||||
/**
|
||||
* @brief Creates and installs a hook on a vtable slot.
|
||||
*
|
||||
* @param vtable Pointer to the base of the vtable.
|
||||
* @param index Index of the slot to hook.
|
||||
* @param detour Replacement function.
|
||||
* @param outHandle Receives the created hook handle on success. Set to nullptr on failure.
|
||||
*
|
||||
* @return InvalidTarget if @p vtable is nullptr or the slot
|
||||
* at @p index is empty; otherwise the result of the operation.
|
||||
*/
|
||||
RADHOOK_API
|
||||
RadHookResult
|
||||
RadHookVTableCreate(
|
||||
_In_ void** vtable,
|
||||
_In_ size_t index,
|
||||
_In_ void* detour,
|
||||
_Out_ RadHookHandle* outHandle
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Queues a hook to be enabled on the next RadHookApplyQueued call.
|
||||
*
|
||||
* Does not modify the hook itself. If the same handle is queued for both
|
||||
* enable and disable before RadHookApplyQueued runs, the most recent call
|
||||
* wins.
|
||||
*
|
||||
* @param handle Hook handle.
|
||||
*
|
||||
* @return RadHookResult::InvalidHandle if the handle is not registered;
|
||||
* otherwise RadHookResult::Success.
|
||||
*/
|
||||
RADHOOK_API
|
||||
RadHookResult
|
||||
RadHookQueueEnable(
|
||||
_In_ RadHookHandle handle
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Queues a hook to be disabled on the next RadHookApplyQueued call.
|
||||
*
|
||||
* Does not modify the hook itself. If the same handle is queued for both
|
||||
* enable and disable before RadHookApplyQueued runs, the most recent call
|
||||
* wins.
|
||||
*
|
||||
* @param handle Hook handle.
|
||||
*
|
||||
* @return RadHookResult::InvalidHandle if the handle is not registered;
|
||||
* otherwise RadHookResult::Success.
|
||||
*/
|
||||
RADHOOK_API
|
||||
RadHookResult
|
||||
RadHookQueueDisable(
|
||||
_In_ RadHookHandle handle
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Applies all queued enable/disable operations.
|
||||
*
|
||||
* Every hook with a pending queued action has that action applied and its
|
||||
* queue cleared, regardless of individual outcomes. Hooks with no queued
|
||||
* action are left untouched.
|
||||
*
|
||||
* @return The result of the first queued operation that did not succeed
|
||||
* (ignoring RadHookResult::AlreadyEnabled / RadHookResult::AlreadyDisabled),
|
||||
* or RadHookResult::Success if all applied cleanly.
|
||||
*/
|
||||
RADHOOK_API
|
||||
RadHookResult
|
||||
RadHookApplyQueued();
|
||||
|
||||
#endif // __LIBRADHOOK_API_H__
|
||||
Reference in New Issue
Block a user