Please send to me "PE format",thank you and I'll give you Mark!

[justyk]

[MSXP2]

your email?

[justyk]

My address is [e-mail]

[alphapaopao]

PE Format
Win32-based executable (image) files are structured according to the Portable Executable (PE) format. For a description of this format, see the specification included on the Microsoft Developer Network (MSDN) Library.


Symbol Files
A symbol file contains the same debugging information that an executable file would contain. However, the information is stored in a file with a .DBG extension, rather than the executable file. Therefore, you can install only the symbol files you will need during debugging. This reduces the file size of the executable, saving load time and disk storage.

To create a .DBG file, build your executable file with debug information, then use the SplitSymbols function or theRebase tool.

The operating system dynamic-link libraries (DLL) have associated symbol files. These files are not installed during installation. To install the system symbol files, create a directory on your hard disk, and copy the files from your system installation compact disc (CD). The symbol files are located in the SUPPORT\DEBUG\I386\SYMBOLS directory tree.



ImageHlp Functions
The ImageHlp function set contains six different classes of functions:

general
image modification
debugger
image access
symbol handler
image integrity
The descriptions of these functions assume that you are familiar with the PE format and its specification.


ImageHlp General Functions
ImageHlp provides the following general helper functions:

ImagehlpApiVersion
ImagehlpApiVersionEx
MakeSureDirectoryPathExists
SearchTreeForFile

ImagehlpApiVersion
The ImagehlpApiVersion function retrieves the information about the version of ImageHlp installed on the system.

LPAPI_VERSION ImagehlpApiVersion(VOID);

Parameters
This function has no parameters.

Return Values
The return value is a pointer to an API_VERSION structure.

Remarks
Use the information in the API_VERSION structure to determine if the version of ImageHlp installed on the system is compatible with the version of ImageHlp used by the application. Although the ImageHlp functions are backwards compatible, functions that are introduced in one version are obviously not available in earlier versions.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp General Functions, API_VERSION, ImagehlpApiVersionEx


ImagehlpApiVersionEx
The ImagehlpApiVersionEx function modifies the information about the version of ImageHlp used by the application.

LPAPI_VERSION ImagehlpApiVersionEx(
IN OUT LPAPI_VERSION AppVersion
);

Parameters
AppVersion
Pointer to an API_VERSION structure. This structure should contain valid ImageHlp version information for your application.
Return Values
The return value is a pointer to an API_VERSION structure.

Remarks
Use the ImagehlpApiVersionEx function to indicate the version of ImageHlp with which the application was built. ImageHlp uses this information to ensure compatibility. For example, consider walking through kernel-mode callback stack frames (which exist in Windows NT 4.0, where User and GDI exist in kernel mode). If you call ImagehlpApiVersionEx to set the Revision member to version 4 or later, the StackWalk function will continue through a callback stack frame. Otherwise, if you set Revision to a version earlier than 4, StackWalk will stop at the kernel transition.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp General Functions, API_VERSION, ImagehlpApiVersion


MakeSureDirectoryPathExists
The MakeSureDirectoryPathExists function creates all the directories in the specified DirPath, beginning with the root.

BOOL MakeSureDirectoryPathExists(
IN LPSTR DirPath
);

Parameters
DirPath
Pointer to a null-terminated string that specifies a valid path name. If the final component of the path is a directory, not a filename, the string must end with a backslash (\) character.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
Each directory specified is created, if it does not already exist. If only some of the directories are created, the function will return FALSE.

QuickInfo
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp General Functions

SearchTreeForFile
The SearchTreeForFile function is used to search a directory tree for a specified file.

BOOL SearchTreeForFile(
IN LPSTR RootPath,
IN LPSTR InputPathName,
OUT LPSTR OutputPathBuffer
);

Parameters
RootPath
Pointer to a null-terminated string that specifies the path where the function should begin searching for the file.
InputPathName
Pointer to a null-terminated string that specifies the file for which the function will search. You can use a partial path.
OutputPathBuffer
Pointer to a buffer that receives the full path to the file that is found. This string is not modified if the return value is FALSE.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The function searches for the file specified by the InputPathName parameter beginning at the path specified in the RootPath parameter. The maximum path depth that is allowed in the RootPath is 32 directories. When the function finds the file in the directory tree, it places the full path to the file in the buffer specified by the OutputPathBuffer parameter. The underlying file system specifies the order of the subdirectory search.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp General Functions


ImageHlp Image Modification Functions
The image modification functions allow you to change the executable image. They are mostly for use by development tools and install programs. They can be used to bind an image, compute its checksum (which is important for ensuring image integrity), change its load address, and produce symbol files.

The following are the image modification functions.

BindImage
BindImageEx
CheckSumMappedFile
MapFileAndCheckSum
ReBaseImage
RemovePrivateCvSymbolic
RemoveRelocations
SplitSymbols
UpdateDebugInfoFile
UpdateDebugInfoFileEx

BindImage
The BindImage function computes the virtual address of each imported function.

BOOL BindImage(
IN LPSTR ImageName,
IN LPSTR DllPath,
IN LPSTR SymbolPath
);

Parameters
ImageName
Pointer to a null-terminated string that specifies the name of the file to be bound. This value can be a filename, a partial path, or a full path.
DllPath
Pointer to a null-terminated string that specifies the root of the search path to use if the file specified by the ImageName parameter cannot be opened.
SymbolPath
Pointer to a null-terminated string that specifies the root of the path to search for the file's corresponding symbol file.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
A call to BindImage is equivalent to the following call:

BindImageEx( 0, ImageName, DllPath, SymbolPath, NULL );

For more information, see BindImageEx.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions, BindImageEx


BindImageEx
The BindImageEx function computes the virtual address of each function that is imported.

BOOL BindImageEx(
IN DWORD Flags,
IN LPSTR ImageName,
IN LPSTR DllPath,
IN LPSTR SymbolPath,
IN PIMAGEHLP_STATUS_ROUTINE StatusRoutine
);

Parameters
Flags
Specifies the behavior of the function. This parameter can be a combination of the following values: Value Meaning
BIND_NO_BOUND_IMPORTS Do not generate a new import address table.
BIND_NO_UPDATE Do not make any changes to the file.
BIND_ALL_IMAGES Bind all images in the call tree for this file.


ImageName
Pointer to a null-terminated string that specifies the name of the file to be bound. This value can be a filename, a partial path, or a full path.
DllPath
Pointer to a null-terminated string that specifies the root of the search path to use if the file specified by the ImageName parameter cannot be opened.
SymbolPath
Pointer to a null-terminated string that specifies the root of the path to search for the file's corresponding symbol file.
StatusRoutine
Pointer to a status routine. The status routine is called during the progress of the image binding. For more information, see PIMAGEHLP_STATUS_ROUTINE.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The process of binding an image consists of computing the virtual address of each imported function. The computed virtual address is then saved in the importing image's Import Address Table (IAT). As a result, the image is loaded much faster, particularly if it uses many DLLs, because the system loader does not have to computer the address of each imported function.

If a corresponding symbol file can be located, its time stamp and checksum are updated.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions, PIMAGEHLP_STATUS_ROUTINE


PIMAGEHLP_STATUS_ROUTINE
The PIMAGEHLP_STATUS_ROUTINE function is an application-defined callback function used with the BindImageEx function. The status routine is called during the process of the image binding.

The PIMAGEHLP_STATUS_ROUTINE type defines a pointer to this callback function. The application can define the function name.

typedef BOOL (CALLBACK *PIMAGEHLP_STATUS_ROUTINE)(
IMAGEHLP_STATUS_REASON Reason,
LPSTR ImageName,
LPSTR DllName,
ULONG Va,
ULONG Parameter
);

Parameters
Reason
Specifies the current status of the bind operation. This parameter can be one of the following values. Value Meaning

BindOutOfMemory
BindRvaToVaFailed
BindNoRoomInImage
BindImportModuleFailed
BindImportProcedureFailed
BindImportModule
BindImportProcedure
BindForwarder
BindForwarderNOT
BindImageModified
BindExpandFileHeaders
BindImageComplete
BindMismatchedSymbols
BindSymbolsNotUpdated


ImageName
Pointer to a null-terminated string that specifies the name of the file to be bound. This value can be a filename, a partial path, or a full path.
DllName
Pointer to a null-terminated string that specifies the name of the DLL.
Va
Specifies the computed virtual address.
Parameter
Specifies additional status information. This value depends on the value of the Reason parameter.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions, BindImageEx

CheckSumMappedFile
The CheckSumMappedFile function computes the checksum of the specified image file.

PIMAGE_NT_HEADERS CheckSumMappedFile(
IN LPVOID BaseAddress,
IN DWORD FileLength,
OUT LPDWORD HeaderSum,
OUT LPDWORD CheckSum
);

Parameters
BaseAddress
Specifies the base address of the mapped file. This value is obtained by calling the MapViewOfFile function.
FileLength
Specifies the length of the file, in bytes.
HeaderSum
Pointer to a variable that receives the original checksum from the image file, or zero if there is an error.
CheckSum
Pointer to the variable that receives the computed checksum.
Return Values
If the function succeeds, the return value is a pointer to the IMAGE_NT_HEADERS structure contained in the mapped image.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks
The CheckSumMappedFile function computes a new checksum for the file and returns it in the CheckSum parameter. This function is used by any application that creates or modifies an executable image. Checksums are required for Windows NT kernel mode drivers and some system DLLs. The linker computes the original checksum at link time, if you use the appropriate linker switch. For more details, see your linker documentation.

It is recommended that all images have valid checksums. It is the caller's responsibility to place the newly computed checksum into the mapped image and update the on-disk image of the file.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions, MapFileAndCheckSum, MapViewOfFile


MapFileAndCheckSum
The MapFileAndCheckSum function computes the checksum of the specified file.

ULONG MapFileAndCheckSum(
IN LPTSTR Filename,
OUT LPDWORD HeaderSum,
OUT LPDWORD CheckSum
);

Parameters
Filename
Pointer to a null-terminated string that specifies the filename of the file for which the checksum is to be computed.
HeaderSum
Pointer to a variable that receives the original checksum from the image file, or zero if there is an error.
CheckSum
Pointer to the variable that receives the computed checksum.
Return Values
If the function succeeds, the return value is CHECKSUM_SUCCESS.

If the function fails, the return value is one of the following:

Value Meaning
CHECKSUM_OPEN_FAILURE Could not open the file.
CHECKSUM_MAP_FAILURE Could not create the file mapping for the file.
CHECKSUM_MAPVIEW_FAILURE Could not map a view of the file.
CHECKSUM_UNICODE_FAILURE Could not convert the filename to UNICODE.


Remarks
The MapFileAndCheckSum function computes a new checksum for the file and returns it in the CheckSum parameter. This function is used by any application that creates or modifies an executable image. Checksums are required for Windows NT kernel mode drivers and some system DLLs. The linker computes the original checksum at link time, if you use the appropriate linker switch. For more details, see your linker documentation.

It is recommended that all images have valid checksums. It is the caller's responsibility to place the newly computed checksum into the mapped image and update the on-disk image of the file.

QuickInfo
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions, CheckSumMappedFile

ReBaseImage
The ReBaseImage function is used to change the load address for the specified image, which reduces the required load time for a DLL.

Alternatively, you can use theRebase tool.

BOOL ReBaseImage(
IN LPSTR CurrentImageName,
IN LPSTR SymbolPath,
IN BOOL fReBase,
IN BOOL fRebaseSysfileOk,
IN BOOL fGoingDown,
IN DWORD CheckImageSize,
OUT LPDWORD OldImageSize,
OUT LPDWORD OldImageBase,
OUT LPDWORD NewImageSize,
IN OUT LPDWORD NewImageBase,
IN DWORD TimeStamp
);

Parameters
CurrentImageName
Pointer to a null-terminated string that specifies filename of the file to be rebased.
SymbolPath
Pointer to a null-terminated string that specifies the path used to find the corresponding symbol file.
fReBase
Specifies whether the image is to be rebased. If this value is TRUE, the image is rebased. Otherwise, the image is not rebased.
fRebaseSysfileOk
Specifies whether a system image is to be rebased. If this value is TRUE, the system image is rebased. Otherwise, the system image is not rebased.
fGoingDown
Specifies whether the image should be rebased below the given base. If this value is TRUE, the image can be rebased below the given base; otherwise, it cannot.
CheckImageSize
Specifies the maximum size that the image can grow to, or zero if there is no limit.
OldImageSize
Pointer to a variable that receives the original image size.
OldImageBase
Pointer to a variable that receives the original image base.
NewImageSize
Pointer to a variable that receives the new image size after the rebase operation.
NewImageBase
Pointer to a variable that receives the new image base after the rebase operation.
TimeStamp
Specifies the new time stamp for the image. The value must be represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The ReBaseImage function changes the desired load address for the specified image. This operation involves reading the entire image and updating all fixups, debug information, checksum, and time stamp values. You can rebase an image to reduce the required load time for its DLLs. If an application can rely on a DLL being loaded at the desired load address, then the system loader does not have to relocate the image. The image is simply loaded into the application's virtual address space and the DllMain function is called, if one is present.

A well-behaved application has its DLLs rebased so they each fall within a unique range of the virtual address space. The system DLLs are currently based in memory from 0x70000000 to 0x78000000 (0x68000000 to 0x78000000 on MIPS). Therefore, you should base your DLLs from 0x60000000 to 0x68000000. One possible scheme is to choose a base address based on the first letter of the DLL name, as shown in the following table.

First Letter Base Address
A - C 0x60000000
D - F 0x61000000
G - I 0x62000000
J - L 0x63000000
M - O 0x64000000
P - R 0x65000000
S - U 0x66000000
V - X 0x67000000
Y - Z 0x68000000


By using these suggestions with the ReBaseImage function, each DLL in an application can be assigned a unique base address. This process can be part of the build process or part of the final release procedure for the application.

QuickInfo
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions, DllMain


RemovePrivateCvSymbolic
The RemovePrivateCvSymbolic function removes all but public information from the CodeView debug information.

BOOL RemovePrivateCvSymbolic(
IN PCHAR DebugData,
OUT PCHAR *NewDebugData,
OUT LPDWORD NewDebugSize
);

Parameters
DebugData
Pointer to the CodeView debug data. This data can be found by mapping the image and searching the debug directories for debug type IMAGE_DEBUG_TYPE_CODEVIEW.
NewDebugData
Pointer to a buffer that receives the public CodeView debug information.
NewDebugSize
Pointer to a variable that receives the size of the public CodeView debug information.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The RemovePrivateCvSymbolic function removes all but public information from the CodeView debug information. Therefore, you can ship the debug symbols for an image without disclosing your data structures or other source information. The user can only get a stack trace, place breakpoints on functions, and dump memory. All but the following CodeView sections are discarded:

sstSegMap
sstSegName
sstOffsetMap16
sstOffsetMap32
sstModule
sstPublic
sstPublicSym
sstGlobalPub
It is the responsibility of the caller to free the memory pointed to by the NewDebugData parameter when he is finished.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions


RemoveRelocations
The RemoveRelocations function strips relocation information from an executable image.

VOID RemoveRelocations(
IN LPSTR ImageName
);

Parameters
ImageName
Pointer to a null-terminated string that specifies the name of the image from which to strip relocations. You must use a fully qualified path.
Return Values
None.

Remarks
The RemoveRelocations function strips relocation information from an executable image. This function exists so an image can be rebased (using the ReBaseImage function) after building and then have the relocations stripped so it will always load at that preferred load address. However, it is not recommended that you do this, because the image will not load if its preferred load address is occupied.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions, ReBaseImage


SplitSymbols
The SplitSymbols function strips symbols from the specified image.

BOOL SplitSymbols(
IN LPSTR ImageName,
IN LPSTR SymbolsPath,
OUT LPSTR SymbolFilePath,
IN DWORD Flags
);

Parameters
ImageName
Pointer to a null-terminated string that specifies the name of the image from which to split symbols.
SymbolsPath
Pointer to a null-terminated string that specifies a subdirectory for storing symbols. This parameter is optional.
SymbolFilePath
Pointer to a null-terminated string that specifies the name of the generated symbol file. This file typically has a .DBG extension.
Flags
Specifies the information to be split from the image. This parameter can be zero or a combination of the following values: Value Meaning
SPLITSYM_EXTRACT_ALL Usually, an image with the symbols split off will still contain a MISC debug directory with the name of the symbol file. Therefore, the debugger can still find the symbols. Using this flag removes this link. The end result is similar to using the -debug:none switch on the Microsoft linker.
SPLITSYM_REMOVE_PRIVATE This strips off the private CodeView symbolic information when generating the symbol file. It does this by making a call to the RemovePrivateCvSymbolic function.


Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The SplitSymbols function should be used when stripping symbols from an image. It will create a symbol file that all Win32-compatible debuggers understand. The format is defined in WINNT.H and consists of an image header (IMAGE_SEPARATE_DEBUG_HEADER), followed by the array of section headers, the exception information (on RISC only) or FPO information (on X86 only), and all debug symbolic information from the image.

If the SymbolsPath parameter is NULL, the symbol file is stored in the directory where the image exists. Otherwise, it is stored in the subdirectory below SymbolsPath that matches the extension of the image. Using this method reduces the chances of symbol file collision. For example, the symbols for myapp.exe will be in the SymbolsPath\exe directory and the symbols for myapp.dll will be in the SymbolsPath\dll directory.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions, RemovePrivateCvSymbolic


UpdateDebugInfoFile
The UpdateDebugInfoFile function takes the specified information and updates the corresponding fields in the symbol file.

BOOL UpdateDebugInfoFile(
IN LPSTR ImageFileName,
IN LPSTR SymbolPath,
OUT LPSTR DebugFilePath,
IN OUT PIMAGE_NT_HEADERS NtHeaders
);

Parameters
ImageFileName
Pointer to a null-terminated string that specifies the name of the image that is now out of date with respect to its symbol file.
SymbolPath
Pointer to a null-terminated string that specifies the path in which to look for the symbol file.
DebugFilePath
Pointer to a buffer that receives the filename of the symbol file that was updated.
NtHeaders
Pointer to an IMAGE_NT_HEADERS structure that specifies the new NT header information.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The UpdateDebugInfoFile function takes the information stored in the IMAGE_NT_HEADERS structure and updates the corresponding fields in the symbol file. Any time an image file is modified, this function should be called to keep the numbers in sync. Specifically, whenever an image checksum changes, the symbol file should be updated to match.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions, UpdateDebugInfoFileEx

UpdateDebugInfoFileEx
The UpdateDebugInfoFileEx function takes the information stored in NtHeaders and updates the corresponding fields in the symbol file.

BOOL UpdateDebugInfoFileEx(
IN LPSTR ImageFileName,
IN LPSTR SymbolPath,
OUT LPSTR DebugFilePath,
IN OUT PIMAGE_NT_HEADERS NtHeaders,
IN DWORD OldChecksum
);

Parameters
ImageFIleName
Pointer to a null-terminated string that specifies the name of the image that is now out of date with respect to its symbol file.
SymbolPath
Pointer to a null-terminated string that specifies the path in which to look for the symbol file.
DebugFilePath
The symbol file that was updated.
NtHeaders
Pointer to an IMAGE_NT_HEADERS structure that specifies the new NT header information.
OldChecksum
Specifies the original checksum value. If this value does not match the checksum that is present in the mapped image, the flags in the symbol file contain IMAGE_SEPARATE_DEBUG_MISMATCH and the last error value is set to ERROR_INVALID_DATA.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks
The UpdateDebugInfoFileEx function takes the information stored in the IMAGE_NT_HEADERS structure and updates the corresponding fields in the symbol file. Any time an image file is modified, this function should be called to keep the numbers in sync. Specifically, whenever an image checksum changes, the symbol file should be updated to match.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Image Modification Functions


ImageHlp Debugger Functions
The debugging service functions are the ImageHlp functions most suited for use by a debugger or the debugging code in an application. These functions can be used in concert with the symbol handler functions for easier use. The StackWalk function, for example, is used by the memory allocators of several applications to best track memory leaks. The functions for finding and mapping debug information can be used when the ImageHlp symbol handler functions are not needed.

StackWalk
FindDebugInfoFile
FindExecutableImage
MapDebugInformation
UnmapDebugInformation
UnDecorateSymbolName

StackWalk
The StackWalk function provides a portable method for obtaining a stack trace.

BOOL StackWalk(
IN DWORD MachineType,
IN HANDLE hProcess,
IN HANDLE hThread,
IN OUT LPSTACKFRAME StackFrame,
IN OUT LPVOID ContextRecord,
IN PREAD_PROCESS_MEMORY_ROUTINE ReadMemoryRoutine,
IN PFUNCTION_TABLE_ACCESS_ROUTINE FunctionTableAccessRoutine,
IN PGET_MODULE_BASE_ROUTINE GetModuleBaseRoutine,
IN PTRANSLATE_ADDRESS_ROUTINE TranslateAddress
);

Parameters
MachineType
Specifies the architecture type of the machine for which the stack trace is generated. This parameter can be one of the following values: Value Meaning
IMAGE_FILE_MACHINE_I386 Intel
IMAGE_FILE_MACHINE_R4000 MIPS
IMAGE_FILE_MACHINE_R10000 MIPS
IMAGE_FILE_MACHINE_ALPHA DEC Alpha
IMAGE_FILE_MACHINE_POWERPC IBM PowerPC


hProcess
Handle to the process for which the stack trace is generated. If the caller supplies a valid callback pointer for the ReadMemoryRoutine parameter, then this value does not have to be a valid process handle. It can be a token that is unique and consistently the same for all calls to the StackWalk function. If the ImageHlp symbol handler is used with StackWalk, use the same process handles for the calls to each function.
hThread
Handle to the thread for which the stack trace is generated. If the caller supplies a valid callback pointer for the ReadMemoryRoutine parameter, then this value does not have to be a valid thread handle. It can be a token that is unique and consistently the same for all calls to the StackWalk function.
StackFrame
Pointer to a STACKFRAME structure. This structure is filled with information for the next frame, if the function call succeeds.
ContextRecord
Pointer to a CONTEXT structure. This parameter is required only when the MachineType parameter is not IMAGE_FILE_MACHINE_I386.
ReadMemoryRoutine
Pointer to a callback routine that provides memory read services. When the StackWalk function needs to read memory from the process's address space, this callback is used. If NULL is passed, then the ReadProcessMemory function is used. In this case, the hProcess parameter must be a valid process handle.
FunctionTableAccessRoutine
Pointer to a callback routine that provides access to the run-time function table for the process. For RISC machines, this function accesses the pdata table, while on X86 machines this function accesses the fpo table. This parameter is required because the StackWalk function does not have access to the process's run-time function table.
The symbol handler in ImageHlp provides functions that load and access the run-time table. If these functions are used, then SymFunctionTableAccess can be passed as a valid parameter.

GetModuleBaseRoutine
Pointer to a callback routine that provides a module base for any given virtual address. This parameter is required. The symbol handler in ImageHlp provides functions that load and maintain module information. If these functions are used, then SymGetModuleBase can be passed as a valid parameter.
TranslateAddress
Pointer to a callback routine that provides address translation for 16-bit addresses. Most, if not all, callers of StackWalk can safely pass NULL for this parameter.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The StackWalk function provides a portable method for obtaining a stack trace. This function is used by all Microsoft debuggers and tools that require stack trace facilities. Using the StackWalk function is recommended over writing your own function because of all the complexities associated with stack walking on Win32 platforms. In addition, there are compiler options that cause the stack to appear differently, depending on how the module is compiled. By using this function, your application has a portable stack trace that continues to work as the compiler and operating system change.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Debugger Functions, CONTEXT, STACKFRAME




FindDebugInfoFile
The FindDebugInfoFile function locates a symbol file.

HANDLE FindDebugInfoFile(
IN LPSTR FileName,
IN LPSTR SymbolPath,
OUT LPSTR DebugFilePath
);

Parameters
FileName
Pointer to a null-terminated string that specifies the name of the symbol file that is desired. You can use a partial path.
SymbolPath
Pointer to a null-terminated string that specifies the path where symbol files are located. This can be multiple paths, with each separated by a semicolon (;).
DebugFilePath
The full path of the symbol file that is found.
Return Values
If the function succeeds, the return value is an open handle to the debug file.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks
The FindDebugInfoFile function is used to locate a symbol file. This function is provided so symbol files can be located in several different directories through a single function call. The SymbolPath parameter can contain multiple paths, with each separated by a semicolon (;). When multiple paths are specified, each directory tree is searched for the symbol file. When the file is located, the search stops. Thus, be sure to specify SymbolPath with the paths in the correct order.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Debugger Functions




FindExecutableImage
The FindExecutableImage function locates an executable image file.

HANDLE FindExecutableImage(
IN LPSTR FileName,
IN LPSTR SymbolPath,
OUT LPSTR ImageFilePath
);

Parameters
FileName
Pointer to a null-terminated string that specifies the name of the executable image file. You can use a partial path.
SymbolPath
Pointer to a null-terminated string that specifies the path where symbol files are located. This can be multiple paths, with each separated by a semicolon (;).
ImageFilePath
Pointer to a null-terminated string that receives the full path of the executable image file that is located.
Return Values
If the function succeeds, the return value is an open handle to the executable image file.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks
The FindExecutableImage function is used to locate an executable image file. This function is provided so executable image files can be located in several different directories through a single function call. The SymbolPath parameter can contain multiple paths, with each separated by a semicolon (;). When multiple paths are specified, each directory tree is searched for the executable image file. When the file is located, the search stops. Thus, be sure to specify SymbolPath with the paths in the correct order.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Debugger Functions


MapDebugInformation
The MapDebugInformation function gains access to the debug information for an image.

PIMAGE_DEBUG_INFORMATION MapDebugInformation(
IN HANDLE FileHandle,
IN LPSTR FileName,
IN LPSTR SymbolPath,
IN DWORD ImageBase
);

Parameters
FileHandle
Handle to an open executable image, a symbol file, or NULL.
FileName
Pointer to a null-terminated string that specifies the name of an executable image file, symbol file, or NULL.
SymbolPath
Pointer to a null-terminated string that specifies the path where symbol files are located. The path can be multiple paths, each separated by a semicolon (;).
ImageBase
Specifies the base address for the image or zero.
Return Values
If the function succeeds, the return value is a pointer to an IMAGE_DEBUG_INFORMATION structure.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks
The MapDebugInformation function is used to gain access to an image's debug information. The debug information is extracted from the image or the symbol file and placed into the IMAGE_DEBUG_INFORMATION structure. This structure is allocated by ImageHlp and must be deallocated by using the UnmapDebugInformation function. The memory for the structure is not in the process's default heap, so attempts to free it with a memory deallocation routine will fail.

QuickInfo
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Debugger Functions, IMAGE_DEBUG_INFORMATION, UnmapDebugInformation


UnmapDebugInformation
The UnmapDebugInformation function deallocates the memory and resources allocated by a call to the MapDebugInformation function.

BOOL UnmapDebugInformation(
IN PIMAGE_DEBUG_INFORMATION DebugInfo
);

Parameters
DebugInfo
Pointer to an IMAGE_DEBUG_INFORMATION structure that is returned from a call to the MapDebugInformation function.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The UnmapDebugInformation function is the counterpart to the MapDebugInformation function and must be used to deallocate the memory and resources allocated by a call to the MapDebugInformation function.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Debugger Functions, IMAGE_DEBUG_INFORMATION, MapDebugInformation


UnDecorateSymbolName
The UnDecorateSymbolName function undecorates decorated C++ symbol names.

DWORD UnDecorateSymbolName(
IN LPSTR DecoratedName,
OUT LPSTR UnDecoratedName,
IN DWORD UndecoratedLength,
IN DWORD Flags
);

Parameters
DecoratedName
Pointer to a null-terminated string that specifies a decorated C++ symbol name. This name can be identified by the first character of the name, which is always a question mark (?).
UnDecoratedName
Pointer to a null-terminated string that specifies the buffer that receives the undecorated name.
UndecoratedLength
Specifies the length of the UnDecoratedName buffer.
Flags
Specifies how the decorated name is undecorated. This parameter can be zero or any combination of the following values: Value Description
UNDNAME_COMPLETE Enable full undecoration.
UNDNAME_NO_LEADING_UNDERSCORES Remove leading underscores from Microsoft keywords.
UNDNAME_NO_MS_KEYWORDS Disable expansion of Microsoft keywords.
UNDNAME_NO_FUNCTION_RETURNS Disable expansion of return types for primary declarations.
UNDNAME_NO_ALLOCATION_MODEL Disable expansion of the declaration model.
UNDNAME_NO_ALLOCATION_LANGUAGE Disable expansion of the declaration language specifier.
UNDNAME_NO_MS_THISTYPE Disable expansion of Microsoft keywords on the this type for primary declaration.
UNDNAME_NO_CV_THISTYPE Disable expansion of CodeView modifiers on the this type for primary declaration.
UNDNAME_NO_THISTYPE Disable all modifiers on the this type.
UNDNAME_NO_ACCESS_SPECIFIERS Disable expansion of access specifiers for members.
UNDNAME_NO_THROW_SIGNATURES Disable expansion of throw-signatures for functions and pointers to functions.
UNDNAME_NO_MEMBER_TYPE Disable expansion of the static or virtual attribute of members.
UNDNAME_NO_RETURN_UDT_MODEL Disable expansion of Microsoft model for UDT returns.
UNDNAME_32_BIT_DECODE Undecorate 32-bit decorated names.
UNDNAME_NAME_ONLY Crack only the name for primary declaration. Returns [scope::]name. Does expand template parameters.
UNDNAME_NO_ARGUMENTS Do not undecorate function arguments.
UNDNAME_NO_SPECIAL_SYMS Do not undecorate special names, such as vtable, vcall, vector, metatype, and so on.


Return Values
If the function succeeds, the return value is the number of characters in the UnDecoratedName buffer, not including the NULL terminator.

If the function fails, the return value is zero. To retrieve extended error information, call GetLastError.

Remarks
If the function fails and returns zero, the content of the UnDecoratedName buffer is undetermined.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, ImageHlp Debugger Functions


Image Access
The image access functions get access to the data in an executable image. The functions provide high-level access to the base of images and very specific access to the most common parts of an image's data.

ImageDirectoryEntryToData
ImageLoad
ImageNtHeader
ImageRvaToSection
ImageRvaToVa
ImageUnload
MapAndLoad
UnMapAndLoad
GetTimestampForLoadedLibrary
GetImageConfigInformation
SetImageConfigInformation
GetImageUnusedHeaderBytes

ImageDirectoryEntryToData
The ImageDirectoryEntryToData function obtains access to image-specific data.

PVOID ImageDirectoryEntryToData(
IN LPVOID Base,
IN BOOLEAN MappedAsImage,
IN USHORT DirectoryEntry,
OUT PULONG Size
);

Parameters
Base
Specifies the base address of the image.
MappedAsImage
Specifies how the image is mapped. If this flag is TRUE, the image is mapped by the system loader. If the flag is FALSE, the file is mapped by a call to the MapViewOfFile function.
DirectoryEntry
Specifies the index number of the desired directory entry. The value must be one of the following: Value Meaning
IMAGE_DIRECTORY_ENTRY_EXPORT Export directory
IMAGE_DIRECTORY_ENTRY_IMPORT Import directory
IMAGE_DIRECTORY_ENTRY_RESOURCE Resource directory
IMAGE_DIRECTORY_ENTRY_EXCEPTION Exception directory
IMAGE_DIRECTORY_ENTRY_SECURITY Security directory
IMAGE_DIRECTORY_ENTRY_BASERELOC Base relocation table
IMAGE_DIRECTORY_ENTRY_DEBUG Debug directory
IMAGE_DIRECTORY_ENTRY_COPYRIGHT
IMAGE_DIRECTORY_ENTRY_GLOBALPTR RVA of global pointer
IMAGE_DIRECTORY_ENTRY_TLS thread local storage directory
IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG Load configuration directory
IMAGE_DIRECTORY_ENTRY_BOUND_IMPORT Bound import directory
IMAGE_DIRECTORY_ENTRY_IAT Import address table


Size
Specifies the size of the desired directory entry's data.
Return Values
If the function succeeds, the return value is a pointer to the directory entry's data.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks
The ImageDirectoryEntryToData function is used to obtain access to image-specific data.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, MapViewOfFile


ImageLoad
The ImageLoad function maintains a list of loaded DLLs.

PLOADED_IMAGE ImageLoad(
IN LPSTR DllName,
IN LPSTR DllPath
);

Parameters
DllName
Pointer to a null-terminated string that specifies the name of the image that is loaded.
DllPath
Pointer to a null-terminated string that specifies the path used to locate the image if the name provided cannot be found. If NULL is used, then the search path rules set forth in the SearchPath function apply.
Return Values
If the function succeeds, the return value is a pointer to a LOADED_IMAGE structure.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks
The ImageLoad function is used to maintain a list of loaded DLLs. If the image has already been loaded, the prior LOADED_IMAGE is returned. Otherwise, the new image is added to the list.

The LOADED_IMAGE structure must be deallocated by the ImageUnload function.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, ImageUnload, LOADED_IMAGE


ImageNtHeader
The ImageNtHeader function locates the IMAGE_NT_HEADERS structure in a PE image and returns a pointer to the data.

PIMAGE_NT_HEADERS ImageNtHeader(
IN LPVOID ImageBase
);

Parameters
ImageBase
Specifies the base address of an image that is mapped into memory by a call to the MapViewOfFile function.
Return Values
If the function succeeds, the return value is a pointer to an IMAGE_NT_HEADERS structure.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, MapViewOfFile

ImageRvaToSection
The ImageRvaToSection function locates a relative virtual address (RVA) within the image header of a file that is mapped as a file and returns a pointer to the section table entry for that virtual address.

PIMAGE_SECTION_HEADER ImageRvaToSection(
IN PIMAGE_NT_HEADERS NtHeaders,
IN LPVOID Base,
IN DWORD Rva
);

Parameters
NtHeaders
Pointer to an IMAGE_NT_HEADERS structure. This structure can be obtained by calling the ImageNtHeader function.
Base
Specifies the base address of an image that is mapped into memory through a call to MapViewOfFile.
Rva
Specifies the relative virtual address to locate.
Return Values
If the function succeeds, the return value is a pointer to an IMAGE_SECTION_HEADER structure.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks
The ImageRvaToSection function locates an RVA within the image header of a file that is mapped as a file and returns a pointer to the section table entry for that virtual address.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, ImageNtHeader, MapViewOfFile


ImageRvaToVa
The ImageRvaToVa function locates a relative virtual address (RVA) within the image header of a file that is mapped as a file and returns the virtual address of the corresponding byte in the file.

LPVOID ImageRvaToVa(
IN PIMAGE_NT_HEADERS NtHeaders,
IN LPVOID Base,
IN DWORD Rva,
IN OUT PIMAGE_SECTION_HEADER *LastRvaSection
);

Parameters
NtHeaders
Pointer to an IMAGE_NT_HEADERS structure. This structure can be obtained by calling the ImageNtHeader function.
Base
Specifies the base address of an image that is mapped into memory through a call to the MapViewOfFile function.
Rva
Specifies the relative virtual address to locate.
LastRvaSection
Pointer to an IMAGE_SECTION_HEADER structure that specifies the last RVA section. This is an optional parameter. When specified, it points to a variable that contains the last section value used for the specified image to translate an RVA to a VA.
Return Values
If the function succeeds, the return value is the virtual address in the mapped file.

If the function fails, the return value is NULL. To retrieve extended error information, call GetLastError.

Remarks
The ImageRvaToVa function locates an RVA within the image header of a file that is mapped as a file and returns the virtual address of the corresponding byte in the file.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, ImageNtHeader, MapViewOfFile

ImageUnload
The ImageUnload function is used to deallocate resources from a previous call to the ImageLoad function.

BOOL ImageUnload(
IN PLOADED_IMAGE LoadedImage
);

Parameters
LoadedImage
Pointer to a LOADED_IMAGE structure that is returned from a call to the ImageLoad function.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, ImageLoad, LOADED_IMAGE



MapAndLoad
The MapAndLoad function maps an image and preloads data from the mapped file.

BOOL MapAndLoad(
IN LPSTR ImageName,
IN LPSTR DllPath,
OUT PLOADED_IMAGE LoadedImage,
IN BOOL DotDll,
IN BOOL ReadOnly
);

Parameters
ImageName
Pointer to a null-terminated string that specifies the name of the image that is loaded.
DllPath
Pointer to a null-terminated string that specifies the path used to locate the image if the name provided cannot be found. If NULL is used, then the search path rules set forth in the SearchPath function apply.
LoadedImage
Pointer to a LOADED_IMAGE structure that receives information about the image after it is loaded.
DotDll
Specifies the default extension, if the image name does not contain a file extension. If the value is TRUE, a .DLL extension is used. If the value is FALSE, then an .EXE extension is used.
ReadOnly
Specifies the access mode. If this value is TRUE, the file is mapped for read-access only. If the value is FALSE, the file is mapped for read and write access.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The MapAndLoad function maps an image and preloads data from the mapped file. The corresponding function, UnMapAndLoad, must be used to deallocate all resources that are allocated by the MapAndLoad function.

QuickInfo
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, LOADED_IMAGE, UnMapAndLoad


UnMapAndLoad
The UnMapAndLoad function is used to deallocate all resources that are allocated by a previous call to the MapAndLoad function.

BOOL UnMapAndLoad(
IN PLOADED_IMAGE LoadedImage
);

Parameters
LoadedImage
Pointer to a LOADED_IMAGE structure. This structure is obtained through a call to the MapAndLoad function.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The UnMapAndLoad function must be used to deallocate all resources that are allocated by a previous call to MapAndLoad. This function also writes a new checksum value into the image before the file is closed. This ensures that if a file is changed, it can be successfully loaded by the system loader.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, LOADED_IMAGE, MapAndLoad


GetTimestampForLoadedLibrary
The GetTimestampForLoadedLibrary function returns the timestamp of a loaded image.

DWORD GetTimestampForLoadedLibrary(
IN LPVOID ImageBase
);

Parameters
ImageBase
Specifies the base address of an image that is mapped into memory by a call to the MapViewOfFile function.
Return Values
If the function succeeds, the return value is the time stamp from the image.

If the function fails, the return value is zero. To retrieve extended error information, call GetLastError.

Remarks
The time stamp for an image indicates the date and time that the image was created by the linker. The value is represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock. The time stamp can be printed using the C run-time (CRT) function ctime.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, MapViewOfFile


GetImageConfigInformation
The GetImageConfigInformation function locates and returns the load configuration data of an image.

BOOL GetImageConfigInformation(
IN PLOADED_IMAGE LoadedImage,
OUT PIMAGE_LOAD_CONFIG_DIRECTORY ImageConfigInformation
);

Parameters
LoadedImage
Pointer to a LOADED_IMAGE structure that is returned from a call to MapAndLoad or LoadImage.
ImageConfigInformation
Pointer to an IMAGE_LOAD_CONFIG_DIRECTORY structure.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The SetImageConfigInformation function locates and changes the load configuration data of an image.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, IMAGE_LOAD_CONFIG_DIRECTORY, LOADED_IMAGE, SetImageConfigInformation


SetImageConfigInformation
The SetImageConfigInformation function locates and changes the load configuration data of an image.

BOOL SetImageConfigInformation(
IN PLOADED_IMAGE LoadedImage,
IN OUT PIMAGE_LOAD_CONFIG_DIRECTORY ImageConfigInformation
);

Parameters
LoadedImage
Pointer to a LOADED_IMAGE structure that is returned from a call to MapAndLoad or LoadImage.
ImageConfigInformation
Pointer to an IMAGE_LOAD_CONFIG_DIRECTORY structure.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The GetImageConfigInformation function locates and returns the load configuration data of an image.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, GetImageConfigInformation, IMAGE_LOAD_CONFIG_DIRECTORY, LOADED_IMAGE


GetImageUnusedHeaderBytes
The GetImageUnusedHeaderBytes function returns the offset and size of the part of the PE header that is currently unused.

DWORD GetImageUnusedHeaderBytes(
IN PLOADED_IMAGE LoadedImage,
OUT LPDWORD SizeUnusedHeaderBytes
);

Parameters
LoadedImage
Pointer to a LOADED_IMAGE structure that is returned from a call to MapAndLoad or LoadImage.
SizeUnusedHeaderBytes
This receives the size of the image's unused header bytes.
Return Values
If the function succeeds, the return value is the offset from the base address of the first unused header byte.

If the function fails, the return value is zero. To retrieve extended error information, call GetLastError.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Access, LOADED_IMAGE


Symbol Handler
The symbol handler functions give applications easy and portable access to the symbolic debug information of an image. These functions should be used exclusively to ensure access to symbolic information. This is necessary because these functions isolate the application from the symbol format.

These are generic, high-level functions that provide symbol access without having knowledge of the symbolic format. This frees the application from compiler, linker, and image format changes and isolates the dependency to the ImageHlp function set.

SymInitialize
SymCleanup
SymEnumerateModules
SymEnumModulesCallback
SymEnumerateSymbols
SymEnumSymbolsCallback
SymFunctionTableAccess
SymGetModuleBase
SymGetModuleInfo
SymGetOptions
SymGetSearchPath
SymGetSymFromAddr
SymGetSymFromName
SymGetSymNext
SymGetSymPrev
SymLoadModule
SymRegisterCallback
SymbolRegisteredCallback
SymSetOptions
SymSetSearchPath
SymUnDName
SymUnloadModule

SymInitialize
The SymInitialize function initializes the symbol handler for a process.

BOOL SymInitialize(
IN HANDLE hProcess,
IN LPSTR UserSearchPath,
IN BOOL fInvadeProcess
);

Parameters
hProcess
Handle to the process for which symbols are to be maintained. If the application is a debugger, use the process handle for the object being debugged, otherwise use the GetCurrentProcess function to obtain the process handle.
UserSearchPath
Pointer to a null-terminated string that specifies a path, or series of paths separated by a semicolon (;), that is used to search for symbol files. If a value of NULL is used, then ImageHlp attempts to form a symbol path from the following sources:
Current directory
Environment variable _NT_SYMBOL_PATH
Environment variable _NT_ALTERNATE_SYMBOL_PATH
Environment variable SYSTEMROOT
fInvadeProcess
If this value is TRUE, ImageHlp enumerates the loaded modules for the process and effectively calls the SymLoadModule function for each module.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The SymInitialize function is used to initialize the symbol handler for a process. In the context of the symbol handler, a process is a convenient object to use when collecting symbol information. Usually, symbol handlers are used by debuggers and other tools that need to load symbols for a process being debugged.

The process handle passed to SymInitialize can be any unique value, except in the case when fInvadeProcess is TRUE. The value passed to SymInitialize must be the same value passed to all other ImageHlp symbol handler functions. It is the process handle that ImageHlp uses to identify the caller and locate the correct symbol information. You must call the SymCleanup function to deallocate all resources associated with the process for which symbols are loaded.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Symbol Handler, SymLoadModule



SymCleanup
The SymCleanup function deallocates all resources associated with the process handle.

BOOL SymCleanup(
IN HANDLE hProcess
);

Parameters
hProcess
Handle to the process that was originally passed to the SymInitialize function.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
This function frees all resources associated with the process handle. Failure to call this function causes memory and resource leaks in the calling application

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Symbol Handler, SymInitialize


SymEnumerateModules
The SymEnumerateModules function enumerates all modules that have been loaded for the process by the SymLoadModule function.

BOOL SymEnumerateModules(
IN HANDLE hProcess,
IN PSYM_ENUMMODULES_CALLBACK EnumModulesCallback,
IN PVOID UserContext
);

Parameters
hProcess
Handle to the process that was originally passed to the SymInitialize function.
EnumModulesCallback
Pointer to the enumeration ca

[alphapaopao]

Image Integrity
The following functions manage the set of certificates in an image file. Routines are provided to add, remove, and query certificates. There is also a function available for obtaining the byte stream of an image file required to calculate a message digest of the image file. This is needed to create signature certificates.

Every certificate in a file has an index which can change as certificates are removed. New certificates will always be added "at the end" of the list of existing certificates. That is, they will be assigned indices that are greater than any index currently in use. In general, an application should not assume that a given certificate has the same index it had the last time it was referenced.

ImageGetDigestStream
ImageAddCertificate
ImageRemoveCertificate
ImageEnumerateCertificates
ImageGetCertificateData
ImageGetCertificateHeader

ImageGetDigestStream
The ImageGetDigestStream function returns the data to be digested from a given image file, subject to the passed DigestLevel parameter.

BOOL ImageGetDigestStream(
IN HANDLE FileHandle,
IN DWORD DigestLevel,
IN PVOID Buffer,
IN OUT PDWORD BufferLength,
IN OUT PDWORD Context
);

Parameters
FileHandle
Handle to the image file to be modified. This handle must be opened for FILE_READ_DATA access.
DigestLevel
Specifies which aspects of the image are to be included in the returned data stream. This parameter can be one or more of the following values: Value Meaning

DICE_PE_IMAGE_DIGEST_DEBUG_INFO
DICE_PE_IMAGE_DIGEST_RESOURCES


Buffer
Provides a pointer to a buffer for the returned data.
BufferLength
On input, this supplies the size of the passed Buffer in bytes. On output, it returns the amount of data remaining in the image. Thus, an application can pass in a BufferLength of zero to determine exactly how much space is required to retrieve all the data in a single pass.
Context
Supplies and returns cross-call context information so sequential calls can return data blocks without requiring the system to maintain state information about the operation in progress.
This parameter must be zero on the first call for accurate results.

Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The ImageGetDigestStream function returns the data to be digested from a given image file, subject to the passed DigestLevel parameter. The order of the bytes will be consistent for different calls, which is required to ensure that the same message digest is always produced from the retrieved byte stream.

To ensure cross-platform compatibility, all implementations of this function must behave in a consistent manner with respect to the order in which the various parts of the image file are returned.

Data should be returned in the following order:

Image (executable and static data) information.
Resource data.
Debug information.
If any of these are not specified, the remaining parts must be returned in the same order.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity

ImageAddCertificate
The ImageAddCertificate function is used to add a DICE_CERTIFICATE to the specified file.

BOOL ImageAddCertificate(
IN HANDLE FileHandle,
IN PDICE_CERTIFICATE Certificate,
OUT PDWORD Index
);

Parameters
FileHandle
Handle to the image file to be modified. This handle must be opened for FILE_READ_DATA and FILE_WRITE_DATA access.
Certificate
Specifies a buffer containing a DICE_CERTIFICATE header and all associated sections. The Length member in the certificate header will be used to determine the length of this buffer.
Index
Receives the index of the newly added certificate.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The ImageAddCertificate function adds a DICE_CERTIFICATE to the specified file. The certificate is added at the end of the existing list of certificates and is assigned an index.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity


ImageRemoveCertificate
The ImageRemoveCertificate function is used to remove the specified certificate from the given file.

BOOL ImageRemoveCertificate(
IN HANDLE FileHandle,
IN DWORD Index
);

Parameters
FileHandle
Handle to the image file to be modified. This handle must be opened for FILE_READ_DATA and FILE_WRITE_DATA access.
Index
Specifies the index of the certificate to be removed.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The ImageRemoveCertificate function removes the specified certificate from the given file.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity


ImageEnumerateCertificates
The ImageEnumerateCertificates function is used to return information about the certificates currently contained in an image file.

BOOL ImageEnumerateCertificates(
IN HANDLE FileHandle,
IN DWORD TypeFilter,
OUT PDWORD CertificateCount,
IN OUT PDWORD Indices OPTIONAL,
IN OUT DWORD IndexCount OPTIONAL
);

Parameters
FileHandle
Handle to the image file to be examined. This handle must be opened for FILE_READ_DATA access.
TypeFilter
Specifies a DICE certificate section type to be used as a filter when returning certificate information. DICE_SECTION_TYPE_ANY should be passed for information on all section types present in the image.
CertificateCount
Receives the number of certificates in the image containing sections of the type specified by the TypeFilter parameter. If none are found, this parameter is zero .
Indices
Optionally provides a buffer to use to return an array of indices to the certificates containing sections of the specified type. No ordering should be assumed for the index values, nor are they guaranteed to be contiguous when DICE_SECTION_TYPE_ANY is queried.
IndexCount
Specifies the length, in double-words, of the Indices buffer. This parameter will be examined whenever Indices is present. If CertificateCount is greater than IndexCount, Indices will be filled in with the first IndexCount sections found in the image and an appropriate warning will be returned.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The ImageEnumerateCertificates function returns information about the certificates currently contained in an image file. It has filtering capabilities which allow certificates containing sections of any single type (or of any type) to be returned.

After the indices of interesting certificates are discovered, they can be passed to the ImageGetCertificateData function to obtain the actual bodies of the certificates.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity, ImageGetCertificateData

ImageGetCertificateData
The ImageGetCertificateData function is used to return a complete certificate from a file.

BOOL ImageGetCertificateData(
IN HANDLE FileHandle,
IN DWORD CertificateIndex,
OUT PDICE_CERTIFICATE Certificate,
IN OUT PDWORD RequiredLength
);

Parameters
FileHandle
Handle to the image file to be modified. This handle must be opened for FILE_READ_DATA access.
CertificateIndex
Specifies the index of the certificate to be returned.
Certificate
Specifies a buffer to receive the certificate data.
RequiredLength
On input, this parameter specifies the length of the Certificate buffer in bytes. On return, it receives the length of the certificate.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The ImageGetCertificateData function returns a complete certificate from a file.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity


ImageGetCertificateHeader
The ImageGetCertificateHeader function is used to return only the header part of the specified DICE_CERTIFICATE up to, but not including, the section offset array.

BOOL ImageGetCertificateHeader(
IN HANDLE FileHandle,
IN DWORD CertificateIndex,
OUT PDICE_CERTIFICATE CertificateHeader
);

Parameters
FileHandle
Handle to the image file to be modified. This handle must be opened for FILE_READ_DATA access.
CertificateIndex
Specifies the index of the certificate whose header is to be returned.
CertificateHeader
Specifies a buffer to receive the certificate header.
Return Values
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks
The ImageGetCertificateHeader function returns only the header part of the specified DICE_CERTIFICATE up to, but not including, the section offset array.

QuickInfo
Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.
Import Library: Use imagehlp.lib.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity


ImageHlp Structures
This section describes the ImageHlp data structures. These structures are either returned through pointers or are passed to ImageHlp as function parameters.



ADDRESS
API_VERSION
IMAGE_DEBUG_INFORMATION
IMAGEHLP_DEFERRED_SYMBOL_LOAD
IMAGEHLP_DUPLICATE_SYMBOL
IMAGEHLP_MODULE
IMAGEHLP_SYMBOL
KDHELP
LOADED_IMAGE
STACKFRAME



ADDRESS
typedef struct _tagADDRESS {
DWORD Offset;
WORD Segment;
ADDRESS_MODE Mode;
} ADDRESS, *LPADDRESS;

Members
Offset
Specifies either an offset into the segment, or a 32-bit virtual address. The interpretation of this value depends on the value contained in the Mode member.
Segment
Specifies the segment number. This value is used only for 16-bit addressing.
Mode
Specifies the addressing mode. This parameter can be one of the following values:
AddrMode1616
AddrMode1632
AddrModeReal
AddrModeFlat

QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity

API_VERSION
The API_VERSION structure contains the ImageHlp version.

typedef struct API_VERSION {
USHORT MajorVersion;
USHORT MinorVersion;
USHORT Revision;
USHORT Reserved;
} API_VERSION, *LPAPI_VERSION;

Members
MajorVersion
Specifies the major version number.
MinorVersion
Specifies the minor version number.
Revision
Specifies the revision number.
Reserved
Reserved for use by the operating system.
QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity, ImageHlpApiVersion, ImageHlpApiVersionEx


IMAGE_DEBUG_INFORMATION
The IMAGE_DEBUG_INFORMATION structure contains debug information.

typedef struct _IMAGE_DEBUG_INFORMATION {
LIST_ENTRY List;
DWORD Size;
PVOID MappedBase;
USHORT Machine;
USHORT Characteristics;
DWORD CheckSum;
DWORD ImageBase;
DWORD SizeOfImage;
DWORD NumberOfSections;
PIMAGE_SECTION_HEADER Sections;
DWORD ExportedNamesSize;
LPSTR ExportedNames;
DWORD NumberOfFunctionTableEntries;
PIMAGE_FUNCTION_ENTRY FunctionTableEntries;
DWORD LowestFunctionStartingAddress;
DWORD HighestFunctionEndingAddress;
DWORD NumberOfFpoTableEntries;
PFPO_DATA FpoTableEntries;
DWORD SizeOfCoffSymbols;
PIMAGE_COFF_SYMBOLS_HEADER CoffSymbols;
DWORD SizeOfCodeViewSymbols;
PVOID CodeViewSymbols;
LPSTR ImageFilePath;
LPSTR ImageFileName;
LPSTR DebugFilePath;
DWORD TimeDateStamp;
BOOL RomImage;
PIMAGE_DEBUG_DIRECTORY DebugDirectory;
DWORD NumberOfDebugDirectories;
DWORD Reserved[ 3 ];
} IMAGE_DEBUG_INFORMATION, *PIMAGE_DEBUG_INFORMATION;

Members
List
Specifies the linked list pointers.
Size
Specifies the size of the memory allocated for the IMAGE_DEBUG_INFORMATION structure and all debug information.
MappedBase
Specifies the base address of the image.
Machine
Specifies the machine type. (See WINNT.H for valid values.)
Characteristics
Specifies the characteristics of the image.
CheckSum
Specifies the checksum of the image.
ImageBase
Specifies the requested base address of the image.
SizeOfImage
Specifies the size of the image.
NumberOfSections
Specifies the number of COFF section headers.
Sections
Pointer to the first COFF section header.
ExportedNamesSize
Specifies the size, in bytes, of the ExportedNames member.
ExportedNames
Pointer to a series of null-terminated strings that name all the functions exported from the image.
NumberOfFunctionTableEntries
Specifies the number of entries contained in the FunctionTableEntries member.
FunctionTableEntries
Pointer to the first function table entry.
LowestFunctionStartingAddress
Specifies the lowest function table starting address.
HighestFunctionEndingAddress
Specifies the highest function table ending address.
NumberOfFpoTableEntries
Specifies the number of entries contained in the FpoTableEntries member.
FpoTableEntries
Pointer to the first FPO entry.
SizeOfCoffSymbols
Specifies the size of the COFF symbol table.
CoffSymbols
Pointer to the COFF symbol table.
SizeOfCodeViewSymbols
Specifies the size of the CodeView symbol table.
CodeViewSymbols
Pointer to the beginning of the CodeView symbol table.
ImageFilePath
Specifies the relative path to the image filename.
ImageFileName
Specifies the image filename.
DebugFilePath
Specifies the full path to the symbol file.
TimeDateStamp
Specifies the time stamp of the image. This represents the date and time the image was created by the linker.
RomImage
This value is TRUE if the image is a ROM image.
DebugDirectory
Pointer to the first debug directory. (See WINNT.H for structure format.)
NumberOfDebugDirectories
Specifies the number of entries contained in the DebugDirectory member.
Reserved
The value in Reserved[0] contains the original executable image's section alignment. The values in Reserved[1] and Reserved[2] are undefined and reserved for use by the operating system.
QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity, MapDebugInformation

IMAGE_LOAD_CONFIG_DIRECTORY
The IMAGE_LOAD_CONFIG_DIRECTORY structure contains the load configuration data of an image.

typedef struct _IMAGE_LOAD_CONFIG_DIRECTORY {
DWORD Characteristics;
DWORD TimeDateStamp;
WORD MajorVersion;
WORD MinorVersion;
DWORD GlobalFlagsClear;
DWORD GlobalFlagsSet;
DWORD CriticalSectionDefaultTimeout;
DWORD DeCommitFreeBlockThreshold;
DWORD DeCommitTotalFreeThreshold;
PVOID LockPrefixTable;
DWORD MaximumAllocationSize;
DWORD VirtualMemoryThreshold;
DWORD ProcessHeapFlags;
DWORD ProcessAffinityMask;
WORD CSDVersion;
WORD Reserved1;
DWORD Reserved[ 2 ];
} IMAGE_LOAD_CONFIG_DIRECTORY, *PIMAGE_LOAD_CONFIG_DIRECTORY;

Members
Characteristics
Flags indicating attributes of the file.
TimeDateStamp
Specifies the date and time stamp value. The value is represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock. The time stamp can be printed using the C run-time (CRT) function ctime.
MajorVersion
Major version number.
MinorVersion
Minor version number.
GlobalFlagsClear
GlobalFlagsSet
CriticalSectionDefaultTimeout
DeCommitFreeBlockThreshold
DeCommitTotalFreeThreshold
LockPrefixTable
MaximumAllocationSize
VirtualMemoryThreshold
ProcessHeapFlags
ProcessAffinityMask
CSDVersion
Reserved1
Reserved
QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in winnt.h.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity, GetImageConfigInformation, SetImageConfigInformation

IMAGEHLP_DEFERRED_SYMBOL_LOAD
typedef struct _IMAGEHLP_DEFERRED_SYMBOL_LOAD {
DWORD SizeOfStruct;
DWORD BaseOfImage;
DWORD CheckSum;
DWORD TimeDateStamp;
CHAR FileName[MAX_PATH];
} IMAGEHLP_DEFERRED_SYMBOL_LOAD,
*PIMAGEHLP_DEFERRED_SYMBOL_LOAD;

Members
SizeOfStruct
Specifies the size of the structure. The caller must set this to sizeof(IMAGEHLP_DEFERRED_SYMBOL_LOAD).
BaseOfImage
Specifies the base virtual address where the image is loaded.
CheckSum
Specifies the computed checksum of the image. This value can be zero.
TimeDateStamp
Specifies the date and time stamp value. The value is represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock. The time stamp can be printed using the C run-time (CRT) function ctime.
FileName
Specifies the image name. The name may or may not contain a full path.
QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity


IMAGEHLP_DUPLICATE_SYMBOL
typedef struct _IMAGEHLP_DUPLICATE_SYMBOL {
DWORD SizeOfStruct;
DWORD NumberOfDups;
PIMAGEHLP_SYMBOL Symbol;
ULONG SelectedSymbol;
} IMAGEHLP_DUPLICATE_SYMBOL, *PIMAGEHLP_DUPLICATE_SYMBOL;

Members
SizeOfStruct
Specifies the size of the structure. The caller must set this to sizeof(IMAGEHLP_DUPLICATE_SYMBOL).
NumberOfDups
The number of duplicate symbols.
Symbol
Pointer to an array of symbols (IMAGEHLP_SYMBOL structures). The number of entries in the array is specified by the NumberOfDups member.
SelectedSymbol
Specifies the index into the symbol array for the selected symbol.
QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity, IMAGEHLP_SYMBOL



IMAGEHLP_MODULE
The IMAGEHLP_MODULE structure contains module information.

typedef struct _IMAGEHLP_MODULE {
DWORD SizeOfStruct;
DWORD BaseOfImage;
DWORD ImageSize;
DWORD TimeDateStamp;
DWORD CheckSum;
DWORD NumSyms;
SYM_TYPE SymType;
CHAR ModuleName[32];
CHAR ImageName[256];
CHAR LoadedImageName[256];
} IMAGEHLP_MODULE, *PIMAGEHLP_MODULE;

Members
SizeOfStruct
Specifies the size of the structure. The caller must set this to sizeof(IMAGEHLP_MODULE).
BaseOfImage
Specifies the base virtual address where the image is loaded.
ImageSize
Specifies the size of the image.
TimeDateStamp
Specifies the date and time stamp value. The value is represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock. The time stamp can be printed using the C run-time (CRT) function ctime.
CheckSum
Specifies the computed checksum of the image. This value can be zero.
NumSyms
Specifies the number of symbols in the symbol table.
SymType
Specifies the type of symbols that are loaded. This parameter can be one of the following values: Value Meaning
SymNone No symbols are loaded.
SymCoff COFF symbols.
SymCv CodeView symbols.
SymPdb PDB symbols. (Actually CodeView stored in a PDB file.)
SymExport Symbols generated from a DLL's export table.
SymDeferred ImageHlp has not yet attempted to load symbols.


ModuleName
Specifies the module name.
ImageName
Specifies the image name. The name may or may not contain a full path.
LoadedImageName
Specifies the full path and filename from which symbols were loaded.
QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity, SymGetModuleInfo




IMAGEHLP_SYMBOL
The IMAGEHLP_SYMBOL structure contains symbol information.

typedef struct _IMAGEHLP_SYMBOL {
DWORD SizeOfStruct;
DWORD Address;
DWORD Size;
DWORD Flags;
DWORD MaxNameLength;
CHAR Name[1];
} IMAGEHLP_SYMBOL, *PIMAGEHLP_SYMBOL;

Members
SizeOfStruct
Specifies the size of the structure, in bytes. The caller must set this parameter to sizeof(IMAGEHLP_SYMBOL).
Address
Specifies the virtual address for the symbol.
Size
Specifies the size of the symbol. This value is a best guess and can be zero.
Flags
Specifies additional information about the symbol. This parameter can be one of the following: Value Meaning

SYMF_OMAP_GENERATED
SYMF_OMAP_MODIFIED


MaxNameLength
The caller must set this value to the maximum length of the string that the Name member can contain. Because symbol names can vary in length, this data structure is allocated by the caller. This member is used so ImageHlp knows how much memory is available for use by the symbol name.
Name
A null-terminated string specifying either the decorated or undecorated symbol name. If the buffer is not large enough for the complete symbol, then the name is truncated to MaxNameLength characters.
QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity, SymGetSymFromAddr, SymGetSymFromName



KDHELP
typedef struct _KDHELP {
DWORD Thread;
DWORD ThCallbackStack;
DWORD NextCallback;
DWORD FramePointer;
DWORD KiCallUserMode;
DWORD KeUserCallbackDispatcher;
} KDHELP, *PKDHELP;

Members
Thread
Specifies the address of the kernel thread object, as provided in the WAIT_STATE_CHANGE packet.
ThCallbackStack
Specifies the offset in the thread object to the pointer to the current callback frame in the kernel stack.
NextCallback
Specifies the address of the next callback frame.
FramePointer
Specifies the address of the saved frame pointer, if applicable.
KiCallUserMode
Specifies the address of the kernel function that calls out to user mode.
KeUserCallbackDispatcher
Specifies the address of the user mode dispatcher function.
QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity


LOADED_IMAGE
The LOADED_IMAGE structure contains information about the loaded image.

typedef struct _LOADED_IMAGE {
LPSTR ModuleName;
HANDLE hFile;
PUCHAR MappedAddress;
PIMAGE_NT_HEADERS FileHeader;
PIMAGE_SECTION_HEADER LastRvaSection;
ULONG NumberOfSections;
PIMAGE_SECTION_HEADER Sections;
ULONG Characteristics;
BOOLEAN fSystemImage;
BOOLEAN fDOSImage;
LIST_ENTRY Links;
ULONG SizeOfImage;
} LOADED_IMAGE, *PLOADED_IMAGE;

Members
ModuleName
Pointer to a null-terminated string that specifies the filename of the mapped file.
hFile
Handle to the mapped file.
MappedAddress
Specifies the base address of the mapped file.
FileHeader
Pointer to the NT headers.
LastRvaSection
Pointer to the first COFF section header.
NumberOfSections
Specifies the count of the COFF section headers.
Sections
Pointer to the first COFF section header.
Characteristics
Specifies the image characteristics value.
fSystemImage
This value is TRUE if the image is a kernel mode executable image.
fDOSImage
This value is TRUE if the image is a 16-bit executable image.
Links
Specifies the list of loaded images.
SizeOfImage
Specifies the size of the image.
QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity, ImageLoad, MapAndLoad


STACKFRAME
The STACKFRAME structure represents a stack frame.

typedef struct _tagSTACKFRAME {
ADDRESS AddrPC;
ADDRESS AddrReturn;
ADDRESS AddrFrame;
ADDRESS AddrStack;
LPVOID FuncTableEntry;
DWORD Params[4];
BOOL Far;
BOOL Virtual;
DWORD Reserved[3];
KDHELP KdHelp;
} STACKFRAME, *LPSTACKFRAME;

Members
AddrPC
Specifies the program counter.
AddrReturn
Specifies the return address.
AddrFrame
Specifies the frame pointer.
AddrStack
Specifies the stack pointer.
FuncTableEntry
The pointer to pdata, fpo, or NULL.
Params
The possible arguments to the function.
Far
This member is TRUE if this is a WOW far call.
Virtual
This member is TRUE if this is a virtual frame.
Reserved
Used internally by the StackWalk function.
KdHelp
The helper data for walking kernel callback frames.
QuickInfo
Windows NT: Requires version 3.51 or later.
Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in imagehlp.h.

See Also
PE Image Helper (ImageHlp) Overview, Image Integrity, StackWalk