Dbghelp function (1)

Dbghelp functions common help functions
Enumdirtree
Function
Enumerate all specified files in the specified folder.
Prototype
Bool winapi enumdirtree (
_ In_opt _ HANDLE hprocess,
_ In _ pctstr rootpath,
_ In _ pctstr inputpathname,
_ Out_opt _ ptstr outputpathbuffer,
_ In_opt _ penumdirtree_callback callback,
_ In_opt _ pvoid callbackdata
);

Parameters
Hprocess [IN, optional]
A handle to a process. this handle must have been previusly passed to the syminitialize function. the handle of a process. the handle must have been processed by the syminitialize function. (for how to handle this problem, see Code 1 below)
Rootpath [in]
The path where the function shoshould begin searching for the file. Specify the function to start searching for the file path.
Inputpathname [in]
The name of the file to be found. You can specify a partial path. The file name to be searched, you can also specify a part of the path.
Outputpathbuffer [out, optional]
A pointer to a buffer that determines es the full path of the file. if the function fails or does not find a matching file, this buffer will still contain the last full path that was found. A pointer to the full-path buffer of the received file. if the function fails or the matching file is not found, the buffer will contain the latest full path it has found. (that is, if the buffer fails or is not found, the data in the buffer will not change)
This parameter is optional and can be null. this parameter is optional and can be left empty.
Callback [IN, optional]
An application-defined callback function, or null. For more information, see enumdirtreeproc. A callback function defined by an application, or leave it blank. For details, see enumdirtreeproc (next section)
Callbackdata [IN, optional]
The user-defined data or null. This value is passed to the callback function. User-defined data may be left empty. This value will be passed to the callback function.
Return Value
Returns true if the function is successful.
If the function fails, false is returned. For more information, call the getlasterror function.
Note:
The query can be canceled. If you have registered the symregistercallbackproc64 (details are returned later) callback function. for each file operation, enumdirtree uses the CBA _deferred_symbol_load_cancel parameter to call this callback function. if the callback function returns true, enumdirtree will cancel searching.
All dbghelp functions, including this function, are single-threaded. therefore, calling the function from more than one thread may cause unknown behavior or memory conflicts. to avoid this situation, you must asynchronously call multiple threads for this function.
To call the Unicode version, define dbghelp_translate_tchar and call enumdirtreew.
Requirements
Dbghelp. dll6.0 or later versions
Dbghelp. h dbghelp. Lib dbghelp. dll is required.
Enumdirtreew (UNICODE)
Enumdirtree (ANSI)

Code 1
// How to initialize the symbol table of a process. The following code loads the symbols of the process (that is, the PDB file)
DWORD error;
Handle hprocess;

Symsetoptions (symopt_undname | symopt_deferred_loads );

Hprocess = getcurrentprocess ();

If (! Syminitialize (hprocess, null, true ))
{
// Syminitialize failed
Error = getlasterror ();
Printf ("syminitialize returned error: % d \ n", error );
Return false;
}

Enumdirtreeproc
Function
The callback function used for enumdirtree. It will be called during each matching.
Prototype
Bool callback enumdirtreeproc (
_ In _ pctstr filepath,
_ In_opt _ pvoid callerdata
);

Parameters
Filepath [in]
A pointer to a buffer that means es the full path of the file that is found. A pointer to the full path buffer of the received file.
Callerdata [IN, optional]
A user-defined value specified in enumdirtree, or null. typically, this parameter is used by an application to pass a pointer to a data structure that enables the callback function to establish some context. the value specified by a user in the enumdirtree function, or is null. in general, this parameter is used by the application to pass a pointer to the data structure, so that the callback function can build some context.
Return Value
If you want to stop enumeration, true is returned. If you want to continue enumeration, false is returned.

Symregistercallback64
Function
Registers a callback function used by the symbol handle.
Prototype
Bool winapi symregistercallback64 (
_ In _ HANDLE hprocess,
_ In _ psymbol_registered_callback64 callbackfunction,
_ In _ ulong64 usercontext
);
Bool
Imageapi
Symregistercallbackw64 (
_ In handle hprocess,
_ In psymbol_registered_callback64 callbackfunction,
_ In ulong64 usercontext
);

Parameters
Hprocess [in]
A handle to the process that was originally passed to the syminitialize function. The handle pointing to the process. The handle has been initialized through the syminitialize function.
Callbackfunction [in]
A symregistercallbackproc64 callback function. A callback function of the symregistercallbackproc64 type.
Usercontext [in]
A user-defined value or null. this value is simply passed to the callback function. normally, this parameter is used by an application to pass a pointer to a data structure that lets the callback function establish some context. A user-defined value or null. this value is simply passed to the callback function. generally, this parameter is used to pass a callback function to an application to construct a Data Structure with some context.
Return Value
Success returns true. Failure returns false. For more error information, call the getlasterror function.

Note:
This function allows the application to register a callback function using the symbol handle to call the registered callback function with the. symbol handle only when the corresponding status or processing information is provided to the application.
This function is single-threaded. If you want to use it in multiple threads, please let them process it asynchronously. Otherwise, unknown behavior or memory conflict will occur.
To use the Unicode version, define the dbghelp_translate_tchar macro.
This function replaces the symregistercallback function.

Symregistercallbackproc64
Function
A callback function defined by the application for the symregistercallback64 function. It is called by the symbol handle.
The type of psymbol_registered_callback64 defines the pointer to this function. symregistercallbackproc64 is only a placeholder for the function name defined by the application.
Prototype
Bool callback symregistercallbackproc64 (
_ In _ HANDLE hprocess,
_ In _ ulong actioncode,
_ In_opt _ ulong64 callbackdata,
_ In_opt _ ulong64 usercontext
);

Parameters
Hprocess [in]
A handle to the process that was originally passed to the syminitialize function. A Process Handle initialized by the syminitialize function.
Actioncode [in]
The callback code. This parameter can be one of the following values. Callback code. This parameter can be one of the following data types:
Numerical meaning
CBA _debug_info
0x10000000 display verbose information.
Displays detailed information.
The callbackdata parameter is a pointer to a string. At this time, callbackdata is a pointer to the string.
CBA _deferred_symbol_load_cancel
0x00000007 deferred symbol loading has started. to cancel the symbol load, return true. Delayed symbol loading has started. To cancel symbol loading, return true.
The callbackdata parameter is a pointer to a imagehlp_deferred_symbol_load64 structure. The callbackdata parameter is an imagehlp_deferred_symbol_load64 pointer
CBA _deferred_symbol_load_complete
0x00000002 deferred symbol load has completed. Delayed return Loading completed
The callbackdata parameter is a pointer to a imagehlp_deferred_symbol_load64 structure. The callbackdata parameter is a pointer to the imagehlp_deferred_symbol_load64 struct.
CBA _deferred_symbol_load_failure
0x00000003 deferred symbol load has failed delayed symbol loading has failed.
The callbackdata parameter is a pointer to a imagehlp_deferred_symbol_load64 structure. the symbol handler will attempt to load the symbols again if the callback function sets the filename member of this structure. structure. the callbackdata parameter is a pointer of the imagehlp_deferred_symbol_load64 structure. the symbol handle will try to load it again. if the callback function sets the filename Member of the struct
CBA _deferred_symbol_load_partial
0x00000020 deferred symbol load has partially completed. the symbol loader is unable to read the image header from either the image file or the specified module. the delayed symbol has been partially loaded. the symbol loader cannot read the image header from the image file or the specified module.
The callbackdata parameter is a pointer to a imagehlp_deferred_symbol_load64 structure. the symbol handler will attempt to load the symbols again if the callback function sets the filename member of this structure. the callbackdata parameter is a struct pointer. the symbol handle will try to load the symbol again if the filename Member of the struct is set.
Dbghelp 5.1: this value is not supported. This value is not supported in this version.
CBA _deferred_symbol_load_start
0x00000001 deferred symbol load has started. The delayed loading has started.
The callbackdata parameter is a pointer to a imagehlp_deferred_symbol_load64 structure. The callbackdata parameter is a struct pointer.
CBA _duplicate_symbol
0x00000005 duplicate symbols were found. This reason is used only in coff or codeview format. Identical symbols are found. This reason is only used in coff or codeview format.
The callbackdata parameter is a pointer to a imagehlp_duplicate_symbol64 structure. To specify which symbol to use, set the selectedsymbol member of this structure. Specify which symbol will be used. Set the selectedsymbol member in the struct.
CBA _event
0x00000010 display verbose information. if you do not handle this event, the information is resent through the CBA _debug_info event. apparently detailed information. if you do not handle this event. this information will conflict with the CBA _debug_info event.
The callbackdata parameter is a pointer to a imagehlp_ CBA _event structure. The callbackdata parameter is an imagehlp_ CBA _event struct pointer.
CBA _read_memory
0x00000006 the loaded image has been read. The loaded image has been read
The callbackdata parameter is a pointer to a imagehlp_ CBA _read_memory structure. the callback function shocould read the number of bytes specified by the bytes member into the buffer specified by the Buf member, and update the bytesread member accordingly. the callbackdata parameter is an imagehlp_ CBA _read_memory struct pointer. the callback function should read the byte numeric section specified by the bytes member to the Buf member. and update the associated bytesread members.
CBA _set_options
0x00000008 symbol options have been updated. to retrieve the current options, call the symgetoptions function. The symbolic options have been updated. To obtain the current options, call the symgetoptions function.

The callbackdata parameter shocould be ignored. callbackdata parameter will be ignored
CBA _srcsrv_event
0x40000000 display verbose information for source server. if you do not handle this event, the information is resent through the CBA _debug_info event. displays detailed information for the source code service. if you do not handle this event, this information will conflict with CBA _debug_info.
The callbackdata parameter is a pointer to a imagehlp_ CBA _event structure. The callbackdata parameter is an imagehlp_ CBA _event struct pointer.
Dbghelp 6.6 and earlier: this value is not supported. This and earlier versions will not be supported.
CBA _srcsrv_info
0x20000000 display verbose information for source server. Displays information for the source code service.
The callbackdata parameter is a pointer to a string. The callbackdata parameter is a string pointer.
Dbghelp 6.6 and earlier: this value is not supported. This and earlier versions will not be supported.
CBA _symbols_unloaded
0x00000004 symbols have been unloaded. the symbol has been uninstalled.
The callbackdata parameter shocould be ignored. callbackdata parameter will be ignored
Callbackdata [IN, optional]
Data for the operation. The format of this data depends on the value of the actioncode parameter. The data for the operation depends on the actioncode parameter.
If the callback function was registered with symregistercallbackw64, the data is a unicode string or data structure. otherwise, the data uses ANSI format. if the callback function is registered by symregistercallbackw64, the data is a unicode string or data structure. otherwise, the data is in ANSI format.

Usercontext [IN, optional]
User-Defined value specified in symregistercallback64, or null. typically, this parameter is used by an application to pass a pointer to a data structure that lets the callback function establish some context. the user-defined value specified in symregistercallback64 or null. generally, this parameter is used to send a Data Structure pointer for the callback function to build some contexts to the application.

Return Value
If the processing is successful, true is returned. if the processing fails, false is returned. if you have not processed the specific code, you should also return false. if you return true at this time, unexpected consequences may occur.
Note:
An application that calls another symbolic handle function obtains the result through the registered callback function. the called application must be prepared for possible boundary effects. if an application has only one callback function and is used in multiple threads, it is necessary to asynchronously process some data access in the context of the callback function.
The callback function defines psymbol_registered_callback64 to replace psymbol_registered_callback.

Imagehlpapiversion
Function
Version Information of the dbghelp library INSTALLED IN THE SYSTEM
Use the imagehlpapiversionex function to indicate the version of the library when the application is set up.
Prototype
Lpapi_version winapi imagehlpapiversion (void );

Parameters
This function has no parameters
Return Value
Returns a pointer to an api_version struct, which is later
Note:
Use the information in the api_version struct to check whether the version of the library installed in the system is compatible with the version of the library used by the application. although library functions are backward compatible, functions in a certain version are not always applicable in earlier versions.
Note that the function is single-threaded. For the processing method, see.
Api_version
Function
Version Information of the included library
Prototype
Typedef struct api_version {
Ushort majorversion;
Ushort minorversion;
Ushort revision;
Ushort reserved;
} Api_version, * lpapi_version;
Member
Majorversion
The major version number. Main version number
Minorversion
The minor version number. Minor version number
Revision
The revision number. Revision version number
Reserved
This member is reserved for use by the operating system. This member is reserved for the operating system
Imagehlpapiversionex
Function
Modify the version of the application library
Prototype
Lpapi_version winapi imagehlpapiversionex (
_ In _ lpapi_version appversion
);

Parameters
Appversion [in]
A pointer to an api_version structure that contains valid version information for your application. A pointer to the version struct, containing a valid version information for your application

Return Value
Returns a pointer to the structure of the version information.
Note:
Use this function to indicate the version of the library when the application is set up. the library uses this information to determine compatibility. for example, when working in kernel mode, the callback frame (user and GDI exist in the kernel ). if you call this function to set the value of the revised version to 4 or later, the stackparts 64 function will continue through a callback stack frame. in addition, if you set the value of the corrected version before 4, stack64 will stop at the kernel delivery.
Note that this is also a single-threaded function.

Makesuredirectorypathexists
Function
Create all the folders in the specified path from the root directory
Prototype
Bool winapi makesuredirectorypathexists (
_ In _ pcstr dirpath
);
Parameters
Dirpath [in]
A valid path name. if the final component of the path is a directory, not a file name, the string must end with a backslash (\) character. A valid path name. if the last part is a directory rather than a file name, the string must end with a backslash.

Return Value
Success return true failure return false. To obtain more error information, call the getlasterror function.
Note:
Each nonexistent directory is created. If only some directories are created, the function returns false.
This function does not support unicode format. To use a path in the unicode format, call the shcreatedirectoryex (see later) function.
This is a single-threaded function. For more information, see the preceding section.

Shcreatedirectoryex
Function
Create a system folder Based on optional security properties
Prototype
Int shcreatedirectoryex (
_ In_opt _ hwnd,
_ In _ lpctstr pszpath,
_ In_opt _ const security_attributes * PSA
);

Parameters
Hwnd [IN, optional]
Type: hwnd
A handle to a parent window. this parameter can be set to null if no user interface will be displayed. handle of a parent window. if no user interface is displayed, this parameter can be set to null.
Pszpath [in]
Type: lpctstr
A pointer to a null-terminated string specifying the fully qualified path of the directory. this string is of Maximum length of 248 characters, including the terminating null character. A string with null characters ending with a qualified directory path. the maximum length of a string is 248 bytes, including the last null character.
PSA [IN, optional]
Type: const security_attributes *
A pointer to a security_attributes structure with the directory's security attribute. set this parameter to null if no security attributes need to be set. A pointer pointing to a Security Attribute struct with Folder Security Attribute Information. if no security attribute needs to be set, you can set it to null.

Return Value
If the operation fails, the following error code is returned. If the error code is not in the following table, see system error codes.
Return Code Description
Error_bad_pathname the pszpath parameter was set to a relative path.
Error_filename_exced_range the path pointed to by pszpath is too long.
Error_path_not_found the system cannot find the path pointed to by pszpath. The path may contain an invalid entry.
Error_file_exists the directory exists.
Error_already_exists the directory exists.
Error_cancelled the user canceled the operation.

Note:
This function creates a system folder Based on the valid path specified by pszpath. if one or more folders do not exist, they will be created. this function checks whether the file is visible. if they are invisible, they will be processed as follows:
If hwnd is a valid window handle, a message box is displayed to warn users that they cannot access the file. If the user chooses not to continue, the function returns error_cancelled
If hwnd is null, no user interface is displayed. The function returns error_cancelled directly.
Requirements
Windows 2003 pro Windows XP Windows Server and later
Header file shlobj. h
Library File shell32.lib
Dynamic library shell32.dll (version 5.0 or later)
Unicode version shcreatedirectoryexw
ANSI shcreatedirectoryexa

Searchtreeforfile
Function
Search for the path tree of the specified file
Prototype
Bool winapi searchtreeforfile (
_ In _ pctstr rootpath,
_ In _ pctstr inputpathname,
_ Out _ ptstr outputpathbuffer
);

Parameters
Rootpath [in]
The path where the function shoshould begin searching for the file. The function starts searching for the file path.
Inputpathname [in]
The file for which the function will search. You can use a partial path. The file to be searched by the function. You can also use a relative path.
Outputpathbuffer [out]
A pointer to a buffer that splits es the full path to the file that is found. this string is not modified if the return value is false. it points to the buffer that finds the full path of the received path. the string will not be changed. If the returned value is false
Return Value
If the function is successful, true is returned. If the function fails, false is returned. For more failure information, call the getlasterror function.

Note:
The function starts searching for the files specified in the inputpathname parameter in the path specified by the rootpath parameter. the maximum depth of a rootpath is 32. when the function finds a file in the directory tree, it places the full path of the file in the buffer specified by the outpupathbuffer parameter. the search sequence of subdirectories is determined by the underlying file system.
The search can be canceled. If you have registered the callback function of the symregistercallbackproc64 function. for each directory search, this function uses the CBA _deferred_symbol_load_cancel parameter to call the callback function. if the callback function returns true, this function will cancel searching.
This function triggers a CBA _deferred_symbol_load_cancel event. When each directory is searched, the caller is allowed to cancel the search.
This is a single-threaded function.
Define dbghelp_translate_tchar to use the Unicode version