Skip to content

utility-reference.md

Latest commit

 

History

History
54 lines (39 loc) · 2.52 KB

utility-reference.md

File metadata and controls

54 lines (39 loc) · 2.52 KB
Raw

General utility reference

Resource ownership

resource_utils.hpp contains small move-only RAII types:

  • UniqueHandle closes real CloseHandle-compatible handles. Never wrap the current-process/current-thread pseudo-handles or a borrowed handle.
  • UniqueModule balances a module reference obtained from LoadLibrary. A raw GetModuleHandle result is borrowed and must not be wrapped directly.
  • ScopeExit runs a no-throw cleanup callable on every scope exit unless released.

put() on UniqueHandle first closes existing ownership and returns storage for an output API. Use it only with APIs that follow the normal null-on-failure output contract. release() transfers ownership without closing.

Native status

native_helpers.hpp distinguishes success, informational, warning, and error severity using the encoded NTSTATUS severity bits. Native success is not limited to numeric zero: informational results also satisfy Succeeded(status).

NtStatusMessage uses the dynamically resolved RtlNtStatusToDosError when it is available and includes the original status in hexadecimal. Win32ErrorMessage uses the system message table and supplies a deterministic hexadecimal fallback.

Checked arithmetic

CheckedAdd, CheckedMultiply, and CheckedAlignUp operate on unsigned types and return false without producing a wrapped result. Alignment must be a nonzero power of two. Use these helpers before allocating count * element_size, adding native buffer offsets, or rounding page/record lengths.

Counted Unicode strings

UnicodeStringView creates a non-owning UNICODE_STRING over a std::wstring_view. It rejects text whose byte length cannot fit in USHORT. The source storage must outlive every native call using the resulting structure. It does not allocate, copy, append a terminator, or own the source.

MakeObjectAttributes returns a fully initialized OBJECT_ATTRIBUTES value and accepts optional root, security descriptor, and security QoS pointers. All pointed- to objects remain caller-owned.

Resolver diagnostics

resolver_diagnostics.hpp exposes UnresolvedFunctions(), which checks all 104 preserved pointer slots and returns stable export-name views for null entries. Call it after ResolveAllFunctions() for diagnostics. The original optional OpenSCManagerA_opt and VirtualProtectEx_opt slots intentionally remain null, so an empty list is not the compatibility expectation.

Record this unresolved list alongside the full Windows 10/11 build when an internal export affects reproduction behavior.