|
102 Patches: Detours to the Rescue
C reference for DttR maintainers and modders.
|
#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 } |
Core SDK APIs for status handling, signature scans, patches, hooks, and patch groups.
Definition in file dttr_core.h.
| #define DTTR_ARRAY_COUNT | ( | array | ) |
Definition at line 18 of file dttr_core.h.
Referenced by dttr_audio_init(), dttr_game_hooks_init(), dttr_graphics_hooks_init(), dttr_inputs_hooks_init(), dttr_movies_hooks_init(), dttr_mss_sdl_release_hooks(), and install_mss_import_hook().
| typedef DTTR_Core_Hook DTTR_Core_Patch |
Definition at line 26 of file dttr_core.h.
| typedef struct DTTR_Core_PatchGroup DTTR_Core_PatchGroup |
Definition at line 25 of file dttr_core.h.
| typedef enum DTTR_Core_TargetKind DTTR_Core_TargetKind |
| typedef struct DTTR_Core_TargetReport DTTR_Core_TargetReport |
| typedef struct DTTR_Core_TargetSpec DTTR_Core_TargetSpec |
| enum 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.
| 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.
| ctx | Runtime context that supplies the runtime scanner and target module. |
| aob | Space-separated byte pattern. Wildcards follow the runtime scanner. |
| out_addr | Receives the resolved address on success. |
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_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.
| mod | Module to scan. |
| aob | Space-separated byte pattern. |
| out_addr | Receives the resolved address on success. |
Definition at line 238 of file core.c.
References aob_scan_with(), DTTR_Core_HookSigscan(), dttr_core_result(), and DTTR_ERR_INVALID_ARGUMENT.
| 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.
| ctx | Runtime context used to resolve and install the hook. |
| aob | Space-separated byte pattern to resolve. |
| offset | Offset added to the resolved match before installing the hook. |
| prologue_size | Minimum prologue bytes, or 0 for automatic sizing. |
| detour | Replacement function to call. |
| out_original | Optional output receiving the original trampoline. |
| out_hook | Required output receiving the hook handle. |
Definition at line 380 of file core.c.
References ctx, DTTR_Core_AOBFind(), DTTR_Core_HookFunction(), DTTR_ResultOK(), and NULL.
| 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.
| ctx | Runtime context used to install the hook. |
| address | Function entry or instruction site to hook. |
| prologue_size | Minimum prologue bytes for the hook injection site, or 0 for automatic sizing. |
| detour | Replacement function to call. |
| out_original | Optional output receiving the original trampoline. |
| out_hook | Required output receiving the hook handle. |
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_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.
| ctx | Runtime context used to patch the pointer slot. |
| address | Address of the pointer slot to replace. |
| new_value | Replacement pointer value, or NULL to clear the slot. |
| out_original | Optional output receiving the previous pointer value. |
| out_hook | Required output receiving the hook handle. |
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_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.
| ctx | Runtime context used to resolve and patch memory. |
| aob | Space-separated byte pattern to resolve. |
| offset | Offset added to the resolved match before writing the jump. |
| detour | Destination address for the relative jump. |
| out_patch | Required output receiving the patch handle. |
Definition at line 446 of file core.c.
References ctx, DTTR_Core_AOBFind(), DTTR_Core_PatchRel32Jump(), DTTR_ResultOK(), and NULL.
| 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.
| ctx | Runtime context used to patch memory. |
| address | Address to patch. |
| bytes | Replacement bytes to write. |
| size | Number of replacement bytes. |
| out_patch | Required output receiving the patch handle. |
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_Result DTTR_Core_PatchGroupCreate | ( | const DTTR_Core_Context * | ctx, |
| DTTR_Core_PatchGroup ** | out_group ) |
Create a patch group for rollback and teardown.
| ctx | Runtime context used by patch-group installs. |
| out_group | Receives the created patch group on success. |
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_Result DTTR_Core_PatchGroupDestroy | ( | DTTR_Core_PatchGroup * | group | ) |
Uninstall a patch group and release its storage.
| group | Patch group to destroy, or NULL. |
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_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.
| group | Patch group that will own the hook handle. |
| address | Function entry or instruction site to hook. |
| prologue_size | Minimum prologue bytes, or 0 for automatic sizing. |
| detour | Replacement function to call. |
| out_original | Optional output receiving the original trampoline. |
| out_hook | Optional output receiving the hook handle. |
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_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.
| group | Patch group that will own the hook handle. |
| address | Address of the pointer slot to replace. |
| new_value | Replacement pointer value, or NULL to clear the slot. |
| out_original | Optional output receiving the previous pointer value. |
| out_hook | Optional output receiving the hook handle. |
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_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.
| group | Patch group that will own installed target handles. |
| targets | Array of target specifications to install. |
| target_count | Number of entries in targets. |
| out_report | Optional output receiving install counts and failure details. |
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_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.
| group | Patch group that will own the patch handle. |
| address | Address to patch. |
| bytes | Replacement bytes to write. |
| size | Number of replacement bytes. |
| out_patch | Optional output receiving the patch handle. |
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_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.
| group | Patch group that will own the patch handle. |
| address | Address of the jump instruction to write. |
| detour | Destination address for the relative jump. |
| out_patch | Optional output receiving the patch handle. |
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_Result DTTR_Core_PatchGroupRelease | ( | DTTR_Core_PatchGroup ** | group | ) |
Destroy a patch group pointer and clear the caller slot.
| group | Address of the caller-owned patch group pointer, or NULL. |
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_Result DTTR_Core_PatchGroupUninstall | ( | DTTR_Core_PatchGroup * | group | ) |
Detach every active handle in a patch group while keeping it reusable.
| group | Patch group to uninstall. |
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_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.
| ctx | Runtime context used to patch memory. |
| address | Address of the jump instruction to write. |
| detour | Destination address for the relative jump. |
| out_patch | Required output receiving the patch handle. |
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_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.
| ctx | Runtime context that supplies the runtime scanner and target module. |
| sig | Raw byte signature buffer. |
| mask | Mask string where implementation-defined wildcard characters skip bytes. |
| out_addr | Receives the resolved address on success. |
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_Result DTTR_Core_Unhook | ( | DTTR_Core_Hook * | hook | ) |
Detach a function or pointer hook created by the SDK runtime.
| hook | Hook handle returned by an SDK hook call, or NULL. |
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_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.