102 Patches: Detours to the Rescue
C reference for DttR maintainers and modders.
Loading...
Searching...
No Matches
dttr_core.h File Reference
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <windows.h>
#include <dttr_result.h>
#include <dttr_runtime.h>

Go to the source code of this file.

Data Structures

struct  DTTR_Core_TargetSpec
struct  DTTR_Core_TargetReport

Macros

#define DTTR_ARRAY_COUNT(array)

Typedefs

typedef struct DTTR_Core_PatchGroup DTTR_Core_PatchGroup
typedef DTTR_Core_Hook DTTR_Core_Patch
typedef enum DTTR_Core_TargetKind DTTR_Core_TargetKind
typedef struct DTTR_Core_TargetSpec DTTR_Core_TargetSpec
typedef struct DTTR_Core_TargetReport DTTR_Core_TargetReport

Enumerations

enum  DTTR_Core_TargetKind {
  DTTR_TARGET_ADDRESS_PATCH = 1 , DTTR_TARGET_AOB_PATCH = 2 , DTTR_TARGET_ADDRESS_HOOK = 3 , DTTR_TARGET_AOB_HOOK = 4 ,
  DTTR_TARGET_POINTER_HOOK = 5 , DTTR_TARGET_ADDRESS_REL32_JMP = 6 , DTTR_TARGET_AOB_REL32_JMP = 7
}

Functions

DTTR_Result DTTR_Core_AOBFind (const DTTR_Core_Context *ctx, const char *aob, uintptr_t *out_addr)
DTTR_Result DTTR_Core_SignatureFind (const DTTR_Core_Context *ctx, const char *sig, const char *mask, uintptr_t *out_addr)
DTTR_Result DTTR_Core_AOBFindInModule (HMODULE mod, const char *aob, uintptr_t *out_addr)
DTTR_Result DTTR_Core_PatchBytes (const DTTR_Core_Context *ctx, uintptr_t address, const uint8_t *bytes, size_t size, DTTR_Core_Patch **out_patch)
DTTR_Result DTTR_Core_HookFunction (const DTTR_Core_Context *ctx, uintptr_t address, int prologue_size, void *detour, void **out_original, DTTR_Core_Hook **out_hook)
DTTR_Result DTTR_Core_HookAOB (const DTTR_Core_Context *ctx, const char *aob, intptr_t offset, int prologue_size, void *detour, void **out_original, DTTR_Core_Hook **out_hook)
DTTR_Result DTTR_Core_PatchRel32Jump (const DTTR_Core_Context *ctx, uintptr_t address, void *detour, DTTR_Core_Patch **out_patch)
DTTR_Result DTTR_Core_PatchAOBRel32Jump (const DTTR_Core_Context *ctx, const char *aob, intptr_t offset, void *detour, DTTR_Core_Patch **out_patch)
DTTR_Result DTTR_Core_HookPointer (const DTTR_Core_Context *ctx, uintptr_t address, void *new_value, void **out_original, DTTR_Core_Hook **out_hook)
DTTR_Result DTTR_Core_Unpatch (DTTR_Core_Patch *patch)
 Detach a byte patch created by the SDK runtime.
DTTR_Result DTTR_Core_Unhook (DTTR_Core_Hook *hook)
DTTR_Result DTTR_Core_PatchGroupCreate (const DTTR_Core_Context *ctx, DTTR_Core_PatchGroup **out_group)
DTTR_Result DTTR_Core_PatchGroupUninstall (DTTR_Core_PatchGroup *group)
DTTR_Result DTTR_Core_PatchGroupDestroy (DTTR_Core_PatchGroup *group)
DTTR_Result DTTR_Core_PatchGroupRelease (DTTR_Core_PatchGroup **group)
DTTR_Result DTTR_Core_PatchGroupPatchBytes (DTTR_Core_PatchGroup *group, uintptr_t address, const uint8_t *bytes, size_t size, DTTR_Core_Patch **out_patch)
DTTR_Result DTTR_Core_PatchGroupHookFunction (DTTR_Core_PatchGroup *group, uintptr_t address, int prologue_size, void *detour, void **out_original, DTTR_Core_Hook **out_hook)
DTTR_Result DTTR_Core_PatchGroupHookPointer (DTTR_Core_PatchGroup *group, uintptr_t address, void *new_value, void **out_original, DTTR_Core_Hook **out_hook)
DTTR_Result DTTR_Core_PatchGroupPatchRel32Jump (DTTR_Core_PatchGroup *group, uintptr_t address, void *detour, DTTR_Core_Patch **out_patch)
DTTR_Result DTTR_Core_PatchGroupInstallTargets (DTTR_Core_PatchGroup *group, const DTTR_Core_TargetSpec *targets, size_t target_count, DTTR_Core_TargetReport *out_report)

Detailed Description

Core SDK APIs for status handling, signature scans, patches, hooks, and patch groups.

Definition in file dttr_core.h.

Macro Definition Documentation

◆ DTTR_ARRAY_COUNT

#define DTTR_ARRAY_COUNT ( array)

Typedef Documentation

◆ DTTR_Core_Patch

Definition at line 26 of file dttr_core.h.

◆ DTTR_Core_PatchGroup

Definition at line 25 of file dttr_core.h.

◆ DTTR_Core_TargetKind

◆ DTTR_Core_TargetReport

typedef struct DTTR_Core_TargetReport DTTR_Core_TargetReport

◆ DTTR_Core_TargetSpec

typedef struct DTTR_Core_TargetSpec DTTR_Core_TargetSpec

Enumeration Type Documentation

◆ DTTR_Core_TargetKind

Enumerator
DTTR_TARGET_ADDRESS_PATCH 
DTTR_TARGET_AOB_PATCH 
DTTR_TARGET_ADDRESS_HOOK 
DTTR_TARGET_AOB_HOOK 
DTTR_TARGET_POINTER_HOOK 
DTTR_TARGET_ADDRESS_REL32_JMP 
DTTR_TARGET_AOB_REL32_JMP 

Definition at line 28 of file dttr_core.h.

Function Documentation

◆ DTTR_Core_AOBFind()

DTTR_Result DTTR_Core_AOBFind ( const DTTR_Core_Context * ctx,
const char * aob,
uintptr_t * out_addr )

Resolve a textual AOB pattern through the context runtime scanner.

Parameters
ctxRuntime context that supplies the runtime scanner and target module.
aobSpace-separated byte pattern. Wildcards follow the runtime scanner.
out_addrReceives the resolved address on success.
Returns
DTTR_OK when the pattern is found, otherwise an error status.

Definition at line 247 of file core.c.

References aob_scan_with(), ctx, dttr_core_result(), DTTR_ERR_INVALID_ARGUMENT, DTTR_ERR_RUNTIME_UNAVAILABLE, runtime_context_valid(), and DTTR_Core_API::sigscan.

Referenced by DTTR_Core_HookAOB(), DTTR_Core_PatchAOBRel32Jump(), target_address(), and test_signature_helpers_resolve_aob_patterns().

◆ DTTR_Core_AOBFindInModule()

DTTR_Result DTTR_Core_AOBFindInModule ( HMODULE mod,
const char * aob,
uintptr_t * out_addr )

Resolve a textual AOB pattern in an explicit module without an SDK context.

Parameters
modModule to scan.
aobSpace-separated byte pattern.
out_addrReceives the resolved address on success.
Returns
DTTR_OK when the pattern is found, otherwise an error status.

Definition at line 238 of file core.c.

References aob_scan_with(), DTTR_Core_HookSigscan(), dttr_core_result(), and DTTR_ERR_INVALID_ARGUMENT.

◆ DTTR_Core_HookAOB()

DTTR_Result DTTR_Core_HookAOB ( const DTTR_Core_Context * ctx,
const char * aob,
intptr_t offset,
int prologue_size,
void * detour,
void ** out_original,
DTTR_Core_Hook ** out_hook )

Resolve an AOB target and install a function detour at its offset.

Parameters
ctxRuntime context used to resolve and install the hook.
aobSpace-separated byte pattern to resolve.
offsetOffset added to the resolved match before installing the hook.
prologue_sizeMinimum prologue bytes, or 0 for automatic sizing.
detourReplacement function to call.
out_originalOptional output receiving the original trampoline.
out_hookRequired output receiving the hook handle.
Returns
DTTR_OK when the target resolves and the hook installs.

Definition at line 380 of file core.c.

References ctx, DTTR_Core_AOBFind(), DTTR_Core_HookFunction(), DTTR_ResultOK(), and NULL.

◆ DTTR_Core_HookFunction()

DTTR_Result DTTR_Core_HookFunction ( const DTTR_Core_Context * ctx,
uintptr_t address,
int prologue_size,
void * detour,
void ** out_original,
DTTR_Core_Hook ** out_hook )

Install a function detour and return both the trampoline and hook handle.

Parameters
ctxRuntime context used to install the hook.
addressFunction entry or instruction site to hook.
prologue_sizeMinimum prologue bytes for the hook injection site, or 0 for automatic sizing.
detourReplacement function to call.
out_originalOptional output receiving the original trampoline.
out_hookRequired output receiving the hook handle.
Returns
DTTR_OK when the hook is installed, otherwise an error status.

Definition at line 336 of file core.c.

References ctx, dttr_core_hook_last_error(), dttr_core_result(), DTTR_ERR_HOOK_CHAIN_UNSUPPORTED, DTTR_ERR_INVALID_ARGUMENT, DTTR_ERR_MEMORY_PROTECTION, DTTR_ERR_RUNTIME_UNAVAILABLE, DTTR_OK, DTTR_Core_API::hook_function, NULL, runtime_context_valid(), and DTTR_Result::status.

Referenced by DTTR_Core_HookAOB(), DTTR_Core_PatchGroupHookFunction(), and install_one_target().

◆ DTTR_Core_HookPointer()

DTTR_Result DTTR_Core_HookPointer ( const DTTR_Core_Context * ctx,
uintptr_t address,
void * new_value,
void ** out_original,
DTTR_Core_Hook ** out_hook )

Patch a pointer slot and optionally return the previous slot value.

Parameters
ctxRuntime context used to patch the pointer slot.
addressAddress of the pointer slot to replace.
new_valueReplacement pointer value, or NULL to clear the slot.
out_originalOptional output receiving the previous pointer value.
out_hookRequired output receiving the hook handle.
Returns
DTTR_OK when the slot is patched, otherwise an error status.

Definition at line 472 of file core.c.

References ctx, dttr_core_result(), DTTR_ERR_INVALID_ARGUMENT, DTTR_ERR_MEMORY_PROTECTION, DTTR_ERR_RUNTIME_UNAVAILABLE, DTTR_OK, DTTR_Core_API::hook_pointer, NULL, and runtime_context_valid().

Referenced by DTTR_Core_PatchGroupHookPointer(), DTTR_PCDOGS_Hook_DataPointer(), install_one_target(), and install_pointer_hook().

◆ DTTR_Core_PatchAOBRel32Jump()

DTTR_Result DTTR_Core_PatchAOBRel32Jump ( const DTTR_Core_Context * ctx,
const char * aob,
intptr_t offset,
void * detour,
DTTR_Core_Patch ** out_patch )

Resolve an AOB target and patch it with a relative JMP.

Parameters
ctxRuntime context used to resolve and patch memory.
aobSpace-separated byte pattern to resolve.
offsetOffset added to the resolved match before writing the jump.
detourDestination address for the relative jump.
out_patchRequired output receiving the patch handle.
Returns
DTTR_OK when the target resolves and the jump patch installs.

Definition at line 446 of file core.c.

References ctx, DTTR_Core_AOBFind(), DTTR_Core_PatchRel32Jump(), DTTR_ResultOK(), and NULL.

◆ DTTR_Core_PatchBytes()

DTTR_Result DTTR_Core_PatchBytes ( const DTTR_Core_Context * ctx,
uintptr_t address,
const uint8_t * bytes,
size_t size,
DTTR_Core_Patch ** out_patch )

Patch bytes and return a handle that can restore the original memory.

Parameters
ctxRuntime context used to patch memory.
addressAddress to patch.
bytesReplacement bytes to write.
sizeNumber of replacement bytes.
out_patchRequired output receiving the patch handle.
Returns
DTTR_OK when the bytes were patched, otherwise an error status.

Definition at line 302 of file core.c.

References ctx, dttr_core_result(), DTTR_ERR_INVALID_ARGUMENT, DTTR_ERR_MEMORY_PROTECTION, DTTR_ERR_RUNTIME_UNAVAILABLE, DTTR_OK, NULL, DTTR_Core_API::patch_bytes, runtime_context_valid(), and size.

Referenced by DTTR_Core_PatchGroupPatchBytes(), DTTR_Core_PatchRel32Jump(), and install_one_target().

◆ DTTR_Core_PatchGroupCreate()

DTTR_Result DTTR_Core_PatchGroupCreate ( const DTTR_Core_Context * ctx,
DTTR_Core_PatchGroup ** out_group )

Create a patch group for rollback and teardown.

Parameters
ctxRuntime context used by patch-group installs.
out_groupReceives the created patch group on success.
Returns
DTTR_OK when the patch group is created, otherwise an error status.

Definition at line 607 of file core.c.

References ctx, dttr_core_result(), DTTR_ERR_INVALID_ARGUMENT, DTTR_ERR_OUT_OF_MEMORY, DTTR_OK, NULL, and runtime_context_valid().

Referenced by DTTR_PCDOGS_PatchGroup_Install(), and test_patch_group_target_failure_rolls_back_only_new_entries().

◆ DTTR_Core_PatchGroupDestroy()

DTTR_Result DTTR_Core_PatchGroupDestroy ( DTTR_Core_PatchGroup * group)

Uninstall a patch group and release its storage.

Parameters
groupPatch group to destroy, or NULL.
Returns
DTTR_OK when all tracked handles detached and storage was released. On restore failure, the group is retained so callers can retry or diagnose.

Definition at line 642 of file core.c.

References DTTR_Core_PatchGroupUninstall(), dttr_core_result(), DTTR_OK, DTTR_ResultOK(), and free.

Referenced by DTTR_Core_PatchGroupRelease(), and test_patch_group_target_failure_rolls_back_only_new_entries().

◆ DTTR_Core_PatchGroupHookFunction()

DTTR_Result DTTR_Core_PatchGroupHookFunction ( DTTR_Core_PatchGroup * group,
uintptr_t address,
int prologue_size,
void * detour,
void ** out_original,
DTTR_Core_Hook ** out_hook )

Install a function hook and adopt the handle into a patch group.

Parameters
groupPatch group that will own the hook handle.
addressFunction entry or instruction site to hook.
prologue_sizeMinimum prologue bytes, or 0 for automatic sizing.
detourReplacement function to call.
out_originalOptional output receiving the original trampoline.
out_hookOptional output receiving the hook handle.
Returns
DTTR_OK when the hook is installed and adopted.

Definition at line 726 of file core.c.

References DTTR_Core_HookFunction(), DTTR_ResultOK(), NULL, patch_group_finish_install(), and patch_group_prepare_install().

Referenced by patch_group_hook_symbol_function().

◆ DTTR_Core_PatchGroupHookPointer()

DTTR_Result DTTR_Core_PatchGroupHookPointer ( DTTR_Core_PatchGroup * group,
uintptr_t address,
void * new_value,
void ** out_original,
DTTR_Core_Hook ** out_hook )

Install a pointer hook and adopt the handle into a patch group.

Parameters
groupPatch group that will own the hook handle.
addressAddress of the pointer slot to replace.
new_valueReplacement pointer value, or NULL to clear the slot.
out_originalOptional output receiving the previous pointer value.
out_hookOptional output receiving the hook handle.
Returns
DTTR_OK when the slot is patched and adopted.

Definition at line 757 of file core.c.

References DTTR_Core_HookPointer(), DTTR_ResultOK(), NULL, patch_group_finish_install(), and patch_group_prepare_install().

Referenced by DTTR_PCDOGS_PatchGroup_HookDataPointer().

◆ DTTR_Core_PatchGroupInstallTargets()

DTTR_Result DTTR_Core_PatchGroupInstallTargets ( DTTR_Core_PatchGroup * group,
const DTTR_Core_TargetSpec * targets,
size_t target_count,
DTTR_Core_TargetReport * out_report )

Install target specs transactionally into a patch group.

Parameters
groupPatch group that will own installed target handles.
targetsArray of target specifications to install.
target_countNumber of entries in targets.
out_reportOptional output receiving install counts and failure details.
Returns
DTTR_OK when all required targets install. Required-target failure rolls back installed handles.

Definition at line 826 of file core.c.

References DTTR_Core_TargetReport::attempted, dttr_core_report_fail(), dttr_core_report_init(), dttr_core_result(), DTTR_ERR_INVALID_ARGUMENT, DTTR_ERR_NOT_FOUND, DTTR_OK, DTTR_ResultOK(), install_one_target(), DTTR_Core_TargetReport::installed, NULL, patch_group_reserve(), patch_group_uninstall_from(), DTTR_Core_TargetReport::skipped_optional, DTTR_Result::status, and target_original_slot().

Referenced by patch_spec_install(), and test_patch_group_target_failure_rolls_back_only_new_entries().

◆ DTTR_Core_PatchGroupPatchBytes()

DTTR_Result DTTR_Core_PatchGroupPatchBytes ( DTTR_Core_PatchGroup * group,
uintptr_t address,
const uint8_t * bytes,
size_t size,
DTTR_Core_Patch ** out_patch )

Patch bytes and adopt the handle into a patch group.

Parameters
groupPatch group that will own the patch handle.
addressAddress to patch.
bytesReplacement bytes to write.
sizeNumber of replacement bytes.
out_patchOptional output receiving the patch handle.
Returns
DTTR_OK when the bytes are patched and adopted.

Definition at line 697 of file core.c.

References DTTR_Core_PatchBytes(), DTTR_ResultOK(), NULL, patch_group_finish_install(), patch_group_prepare_install(), and size.

Referenced by test_patch_group_target_failure_rolls_back_only_new_entries().

◆ DTTR_Core_PatchGroupPatchRel32Jump()

DTTR_Result DTTR_Core_PatchGroupPatchRel32Jump ( DTTR_Core_PatchGroup * group,
uintptr_t address,
void * detour,
DTTR_Core_Patch ** out_patch )

Patch a rel32 jump and adopt the handle into a patch group.

Parameters
groupPatch group that will own the patch handle.
addressAddress of the jump instruction to write.
detourDestination address for the relative jump.
out_patchOptional output receiving the patch handle.
Returns
DTTR_OK when the jump patch is installed and adopted.

Definition at line 786 of file core.c.

References DTTR_Core_PatchRel32Jump(), DTTR_ResultOK(), NULL, patch_group_finish_install(), and patch_group_prepare_install().

◆ DTTR_Core_PatchGroupRelease()

DTTR_Result DTTR_Core_PatchGroupRelease ( DTTR_Core_PatchGroup ** group)

Destroy a patch group pointer and clear the caller slot.

Parameters
groupAddress of the caller-owned patch group pointer, or NULL.
Returns
DTTR_OK when all tracked handles detached and *group was cleared. On restore failure, *group is retained so callers can retry or diagnose.

Definition at line 657 of file core.c.

References DTTR_Core_PatchGroupDestroy(), dttr_core_result(), DTTR_OK, DTTR_ResultOK(), and NULL.

Referenced by dttr_audio_cleanup(), dttr_game_hooks_cleanup(), dttr_graphics_hooks_cleanup(), dttr_inputs_hooks_cleanup(), dttr_movies_hooks_cleanup(), DTTR_PCDOGS_PatchGroup_Install(), and dttr_sidecar_install_pcdogs_patch_group().

◆ DTTR_Core_PatchGroupUninstall()

DTTR_Result DTTR_Core_PatchGroupUninstall ( DTTR_Core_PatchGroup * group)

Detach every active handle in a patch group while keeping it reusable.

Parameters
groupPatch group to uninstall.
Returns
DTTR_OK when all tracked handles are detached.

Definition at line 634 of file core.c.

References dttr_core_result(), DTTR_OK, and patch_group_uninstall_from().

Referenced by DTTR_Core_PatchGroupDestroy().

◆ DTTR_Core_PatchRel32Jump()

DTTR_Result DTTR_Core_PatchRel32Jump ( const DTTR_Core_Context * ctx,
uintptr_t address,
void * detour,
DTTR_Core_Patch ** out_patch )

Patch a site with a five-byte relative JMP when the target is in range.

Parameters
ctxRuntime context used to patch memory.
addressAddress of the jump instruction to write.
detourDestination address for the relative jump.
out_patchRequired output receiving the patch handle.
Returns
DTTR_OK when the jump patch is installed, otherwise an error status.

Definition at line 421 of file core.c.

References ctx, DTTR_Core_PatchBytes(), dttr_core_result(), DTTR_ERR_INVALID_ARGUMENT, DTTR_ERR_UNSUPPORTED, NULL, rel32_displacement(), and runtime_context_valid().

Referenced by DTTR_Core_PatchAOBRel32Jump(), DTTR_Core_PatchGroupPatchRel32Jump(), and install_one_target().

◆ DTTR_Core_SignatureFind()

DTTR_Result DTTR_Core_SignatureFind ( const DTTR_Core_Context * ctx,
const char * sig,
const char * mask,
uintptr_t * out_addr )

Resolve a raw signature and mask through the context runtime scanner.

Parameters
ctxRuntime context that supplies the runtime scanner and target module.
sigRaw byte signature buffer.
maskMask string where implementation-defined wildcard characters skip bytes.
out_addrReceives the resolved address on success.
Returns
DTTR_OK when the signature is found, otherwise an error status.

Definition at line 269 of file core.c.

References ctx, dttr_core_result(), DTTR_ERR_INVALID_ARGUMENT, DTTR_ERR_NOT_FOUND, DTTR_ERR_RUNTIME_UNAVAILABLE, DTTR_OK, runtime_context_valid(), and DTTR_Core_API::sigscan.

Referenced by test_signature_helpers_resolve_aob_patterns().

◆ DTTR_Core_Unhook()

DTTR_Result DTTR_Core_Unhook ( DTTR_Core_Hook * hook)

Detach a function or pointer hook created by the SDK runtime.

Parameters
hookHook handle returned by an SDK hook call, or NULL.
Returns
DTTR_OK when detached or already null, otherwise an error.

Definition at line 517 of file core.c.

References DTTR_Core_HookDetachChecked(), dttr_core_result(), DTTR_ERR_MEMORY_PROTECTION, and DTTR_OK.

Referenced by dttr_mss_sdl_release_hooks().

◆ DTTR_Core_Unpatch()

DTTR_Result DTTR_Core_Unpatch ( DTTR_Core_Patch * patch)

Detach a byte patch created by the SDK runtime.

Definition at line 509 of file core.c.

References DTTR_Core_HookDetachChecked(), dttr_core_result(), DTTR_ERR_MEMORY_PROTECTION, and DTTR_OK.