PREAD_PROCESS_MEMORY_ROUTINE callback function (dbghelp.h)

Article
02/22/2024

An application-defined callback function used with the StackWalk64 function. It is called when StackWalk64 needs to read memory from the address space of the process.

The PREAD_PROCESS_MEMORY_ROUTINE64 type defines a pointer to this callback function. ReadProcessMemoryProc64 is a placeholder for the application-defined function name.

Syntax

PREAD_PROCESS_MEMORY_ROUTINE PreadProcessMemoryRoutine;

BOOL PreadProcessMemoryRoutine(
  [in]  HANDLE hProcess,
  [in]  DWORD lpBaseAddress,
  [out] PVOID lpBuffer,
  [in]  DWORD nSize,
  [out] PDWORD lpNumberOfBytesRead
)
{...}

Parameters

[in] hProcess

A handle to the process for which the stack trace is generated.

[in] lpBaseAddress

The base address of the memory to be read.

[out] lpBuffer

A pointer to a buffer that receives the memory to be read.

[in] nSize

The size of the memory to be read, in bytes.

[out] lpNumberOfBytesRead

A pointer to a variable that receives the number of bytes actually read.

Return value

If the function succeeds, the return value should be TRUE. If the function fails, the return value should be FALSE.

Remarks

In many cases, this function can best service the callback with a corresponding call to ReadProcessMemory.

This function should read as much of the requested memory as possible. The StackWalk64 function handles the case where only part of the requested memory is read.

This callback function supersedes the PREAD_PROCESS_MEMORY_ROUTINE callback function. PREAD_PROCESS_MEMORY_ROUTINE is defined as follows in Dbghelp.h.

#if !defined(_IMAGEHLP_SOURCE_) && defined(_IMAGEHLP64)
#define PREAD_PROCESS_MEMORY_ROUTINE PREAD_PROCESS_MEMORY_ROUTINE64
#else
typedef
BOOL
(__stdcall *PREAD_PROCESS_MEMORY_ROUTINE)(
    __in HANDLE hProcess,
    __in DWORD lpBaseAddress,
    __out_bcount(nSize) PVOID lpBuffer,
    __in DWORD nSize,
    __out PDWORD lpNumberOfBytesRead
    );
#endif

Requirements

Requirement	Value
Target Platform	Windows
Header	dbghelp.h
Redistributable	DbgHelp.dll 5.1 or later