DbgHelp函数

通用帮助函数
EnumDirTree
功能
枚举所有在指定文件夹中的指定文件.
原型
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
);

参数
hProcess [in, optional]
A handle to a process. This handle must have been previously passed to the SymInitialize function.一个进程的句柄.该句柄必须已经被SymInitialize函数处理过.(如何处理见后面的代码1)
RootPath [in]
The path where the function should begin searching for the file.指定函数开始查找文件的路径
InputPathName [in]
The name of the file to be found. You can specify a partial path.需要查找的文件名,也可以指定部分的路径.
OutputPathBuffer [out, optional]
A pointer to a buffer that receives 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. 一个指向接收文件全路径缓冲区的指针.如果函数失败或者没有找到匹配文件,该缓冲区将包含它找到的最新的全路径.(也就是说,如果失败或者没有找到,缓冲区的数据就不会变化)
This parameter is optional and can be NULL.这个参数是可选的,并且可以置空.
Callback [in, optional]
An application-defined callback function, or NULL. For more information, see EnumDirTreeProc.一个应用程序定义的回调函数,或者置空.详细信息请看EnumDirTreeProc(下一节)
CallbackData [in, optional]
The user-defined data or NULL. This value is passed to the callback function.用户定义的数据或者置空.该值会被传递给回调函数.
返回值
函数成功返回TRUE
函数失败返回FALSE,进一步的错误信息,请调用GetLastError函数
注意
查找可以被取消,如果你注册了SymRegisterCallbackProc64(详细情况后面再解)回调函数.对于每一个文件操作,EnumDirTree都会用CBA_DEFERRED_SYMBOL_LOAD_CANCEL参数调用这个回调函数.如果回调函数返回TRUE,则EnumDirTree就会取消查找
所有的DbgHelp函数,包括本函数,都是单线程的.因此,从一个以上的线程对本函数的调用会产生未知的行为或者内存冲突.为了避免这种情况,你必须异步多个线程所有对本函数的调用.
想要调用Unicode版本,请定义DBGHELP_TRANSLATE_TCHAR,并调用EnumDirTreeW
要求
DbgHelp.dll6.0或者之后的版本
需要DbgHelp.h DbgHelp.lib DbgHelp.dll
EnumDirTreeW (Unicode版)
EnumDirTree (ANSI版)

代码1
//如何初始化一个进程的符号表.下面的代码会加载该进程的符号(即pdb文件)
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
功能
用于EnumDirTree的回调函数.它会在每次匹配的时候被调用
原型
BOOL CALLBACK EnumDirTreeProc(
  _In_      PCTSTR FilePath,
  _In_opt_  PVOID CallerData
);

参数
FilePath [in]
A pointer to a buffer that receives the full path of the file that is found.一个指向接收找到的文件全路径缓冲区的指针.
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.一个用户在EnumDirTree函数指定的值,或者为空.通常的情况,这个参数被应用程序用来传递一个数据结构的指针,使得回调函数可以构建一些上下文.
返回值
如果要停止枚举,返回TRUE.如果要继续枚举,返回FALSE.

SymRegisterCallback64
功能
注册一个由符号句柄使用的回调函数
原型
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
    );

参数
hProcess [in]
A handle to the process that was originally passed to the SymInitialize function.指向进程的句柄.该句柄已经通过SymInitialize函数进行过初始化.
CallbackFunction [in]
A SymRegisterCallbackProc64 callback function.一个SymRegisterCallbackProc64类型的回调函数
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.一个用户定义的值或者是NULL.该值只是简单的传递给回调函数.通常,这个参数用来给应用程序传递一个让回调函数构建一些上下文的数据结构.
返回值
成功返回TRUE.失败返回FALSE.进一步的错误信息请调用GetLastError函数.

注意
本函数让应用程序通过符号句柄注册一个回调函数来用.符号句柄调用注册的回调函数仅当这里有给应用程序的对应的状态或者处理信息时.
本函数是单线程的,如果要在多线程中用,请让他们异步处理.否则会引起未知的行为或者内存冲突.
要使用Unicode版本,请定义DBGHELP_TRANSLATE_TCHAR宏.
本函数取代了SymRegisterCallback函数.

SymRegisterCallbackProc64
功能
一个用于SymRegisterCallback64函数的应用程序定义的回调函数.它由符号句柄调用.
PSYMBOL_REGISTERED_CALLBACK64的类型定义了该函数的指针.SymRegisterCallbackProc64只是应用程序定义函数名的占位符.
原型
BOOL CALLBACK SymRegisterCallbackProc64(
  _In_      HANDLE hProcess,
  _In_      ULONG ActionCode,
  _In_opt_  ULONG64 CallbackData,
  _In_opt_  ULONG64 UserContext
);


参数
hProcess [in]
A handle to the process that was originally passed to the SymInitialize function.一个由SymInitialize函数初始化的进程句柄.
ActionCode [in]
The callback code. This parameter can be one of the following values. 回调码.这个参数可以是下面数据中的一种:
数值 含义
CBA_DEBUG_INFO
0x10000000 Display verbose information.
显示详细的信息.
The CallbackData parameter is a pointer to a string.此时, CallbackData是一个指向字符串的指针.
CBA_DEFERRED_SYMBOL_LOAD_CANCEL
0x00000007 Deferred symbol loading has started. To cancel the symbol load, return TRUE. 延迟的符号加载已经开始.要取消符号加载,请返回TRUE.
The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure. CallbackData参数是一个IMAGEHLP_DEFERRED_SYMBOL_LOAD64指针
CBA_DEFERRED_SYMBOL_LOAD_COMPLETE
0x00000002 Deferred symbol load has completed. 延迟的返回加载已经完成
The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure.CallbackData参数是一个指向 IMAGEHLP_DEFERRED_SYMBOL_LOAD64结构体的指针
CBA_DEFERRED_SYMBOL_LOAD_FAILURE
0x00000003 Deferred symbol load 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.CallbackData参数是一个IMAGEHLP_DEFERRED_SYMBOL_LOAD64结构的指针.符号句柄将会尝试去再次加载.如果回调函数设置了结构体的FileName成员
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 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. CallbackData参数是一个结构体的指针.符号句柄会尝试再次加载符号,如果结构体的FileName成员被设置的话.
DbgHelp 5.1: This value is not supported.在这个版本中,该值不被支持.
CBA_DEFERRED_SYMBOL_LOAD_START
0x00000001 Deferred symbol load has started. 延迟加载已经开始
The CallbackData parameter is a pointer to a IMAGEHLP_DEFERRED_SYMBOL_LOAD64 structure. CallbackData参数是一个结构体的指针
CBA_DUPLICATE_SYMBOL
0x00000005 Duplicate symbols were found. This reason is used only in COFF or CodeView format. 完全一样的符号被找到.该原因仅在COFF或者CodeView格式中被用到.
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.要指明哪个符号会被用到,请设置结构体中的SelectedSymbol 成员
CBA_EVENT
0x00000010 Display verbose information. If you do not handle this event, the information is resent through the CBA_DEBUG_INFO event.显然详细的信息.如果你不处理这个事件.这个信息会和CBA_DEBUG_INFO事件冲突.
The CallbackData parameter is a pointer to a IMAGEHLP_CBA_EVENT structure. CallbackData参数是一个IMAGEHLP_CBA_EVENT结构体指针
CBA_READ_MEMORY
0x00000006 The loaded image has been read. 载入的映像已经被读取
The CallbackData parameter is a pointer to a IMAGEHLP_CBA_READ_MEMORY structure. The callback function should read the number of bytes specified by the bytes member into the buffer specified by the buf member, and update the bytesread member accordingly. CallbackData参数是一个IMAGEHLP_CBA_READ_MEMORY结构体指针.回调函数应该读取由bytes成员指定的字节数字节到buf成员中去.并更新关联的bytesread成员
CBA_SET_OPTIONS
0x00000008 Symbol options have been updated. To retrieve the current options, call the SymGetOptions function.符号选项已经被更新了.要取得当前的选项,请调用SymGetOptions函数
The CallbackData parameter should be ignored. CallbackData参数将被忽略
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.为源代码服务显示详细信息.如果你不处理这个事件,该信息将和CBA_DEBUG_INFO产生冲突
The CallbackData parameter is a pointer to a IMAGEHLP_CBA_EVENT structure. CallbackData参数是一个IMAGEHLP_CBA_EVENT结构体指针
DbgHelp 6.6 and earlier: This value is not supported.在此版本以及更早的版本,将不会被支持.
CBA_SRCSRV_INFO
0x20000000 Display verbose information for source server.为源代码服务显示信息信息.
The CallbackData parameter is a pointer to a string. CallbackData参数是一个字符串指针
DbgHelp 6.6 and earlier: This value is not supported. 在此版本以及更早的版本,将不会被支持.
CBA_SYMBOLS_UNLOADED
0x00000004 Symbols have been unloaded. 符号已经被卸载
The CallbackData parameter should be ignored. CallbackData参数将被忽略
CallbackData [in, optional]
Data for the operation. The format of this data depends on the value of the ActionCode parameter.给操作的数据.数据的格式依赖于ActionCode参数
If the callback function was registered with SymRegisterCallbackW64, the data is a Unicode string or data structure. Otherwise, the data uses ANSI format.如果该回调函数是被SymRegisterCallbackW64 注册的,那么数据就是Unicode字符串或者数据结构.否则,数据就是ANSI格式的.
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. SymRegisterCallback64中指定的用户定义值或者NULL.通常,该参数是用来给应用程序传一个让回调函数构建一些上下文的数据结构指针.

返回值
如果成功处理了就返回TRUE.如果处理失败就返回FALSE.如果你没有处理特定的代码,也应该返回FALSE.如果此时你返回真,可能会产生意想不到的后果.
注意
由另外的调用某个符号句柄函数,引起调用的应用程序,通过注册的回调函数,获取结果.调用的应用程序必须为可能引起的边界效应做好准备.如果应用程序只有一个回调函数,而又用于多线程中,那么就有必要异步处理回调函数上下文中的某些数据访问.
回调函数定义PSYMBOL_REGISTERED_CALLBACK64取代PSYMBOL_REGISTERED_CALLBACK


ImagehlpApiVersion
功能
系统中安装的DbgHelp库的版本信息
要标明应用程序组建时库的版本,请使用ImagehlpApiVersionEx函数
原型
LPAPI_VERSION WINAPI ImagehlpApiVersion(void);

参数
该函数没有参数
返回值
返回一个API_VERSION结构体的指针,该结构体见后面
注意
使用API_VERSION结构体中的信息去检测安装在系统中库的版本是否和应用程序用的库的版本兼容.尽管库函数是向后兼容的,但某个版本中的函数并不总是在早期的版本中适用.
注意函数是单线程的,处理方法见上.
API_VERSION
功能
包含的库的版本信息
原型
typedef struct API_VERSION {
  USHORT MajorVersion;
  USHORT MinorVersion;
  USHORT Revision;
  USHORT Reserved;
} API_VERSION, *LPAPI_VERSION;
成员
MajorVersion
The major version number.主版本号
MinorVersion
The minor version number.副版本号
Revision
The revision number.修订版本号
Reserved
This member is reserved for use by the operating system.该成员是为操作系统使用保留
ImagehlpApiVersionEx
功能
修改应用程序使用库的版本信息
原型
LPAPI_VERSION WINAPI ImagehlpApiVersionEx(
  _In_  LPAPI_VERSION AppVersion
);

参数
AppVersion [in]
A pointer to an API_VERSION structure that contains valid version information for your application.一个指向版本结构体的指针,包含一个对你应用程序而言,有效的版本信息

返回值
返回一个指向版本信息结构体的指针
注意
使用本函数标明应用程序组建时库的版本信息.库会使用这个信息去确定兼容性.例如,在内核模式下工作时回调帧(用户和GDI存在于内核中).如果你调用本函数去设置修订版本的值为4或之后的版本,那么StackWalk64函数将会通过一个回调堆栈帧继续.另外,如果你设置修正版本到4之前的值,StackWalk64就会在内核传递处停止.
注意这也是一个单线程函数.

MakeSureDirectoryPathExists
功能
从根目录开始,创建指定路径中所有的文件夹
原型
BOOL WINAPI MakeSureDirectoryPathExists(
  _In_  PCSTR DirPath
);
参数
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.一个有效的路径名.如果最后的部分是一个目录,而不是文件名,那么字符串必须以一个反斜杠字符结尾

返回值
成功返回TRUE失败返回FALSE.要获取更多的错误信息可以调用GetLastError函数
注意
每一个不存在的目录都会被创建.如果只有部分的目录被创建,函数会返回FALSE.
该函数不支持Unicode格式.如果要使用Unicode格式的路径,请调用SHCreateDirectoryEx(见后)函数
这个是单线程的函数,注意事项见前面.

SHCreateDirectoryEx
功能
依照可选的安全属性,创建系统的文件夹
原型
int SHCreateDirectoryEx(
  _In_opt_  HWND hwnd,
  _In_      LPCTSTR pszPath,
  _In_opt_  const SECURITY_ATTRIBUTES *psa
);

参数
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.一个父窗口的句柄.如果没有用户界面显示,这个参数也可以设置为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.一个指定了合格目录路径的空字符结尾的字符串.该字符串最大长度是248个字节,包括最后的空字符.
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.一个指向安全属性结构体带有文件夹安全属性信息的指针.如果没有安全属性需要被设置,可以将它设置为NULL

返回值
如果成功返回 ERROR_SUCCESS.如果操作失败,返回下面的错误代码.如果错误代码不在下表中,请参看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.

注意
这个函数按照pszPath给定的有效路径创建系统文件夹.如果里面的一个或多个文件夹不存在,它们都会被创建.本函数会校验文件是否可见.如果它们是不可见的,那么会按照下面的方式处理:
如果hwnd是一个有效的窗口句柄,一个消息框会被显示来警告用户不能访问文件.如果用户选择不继续,那么函数返回ERROR_CANCELLED
如果hwnd是NULL,将不会有用户接口显示,函数将直接返回ERROR_CANCELLED.
要求
Windows2000Pro Windows XP Windows Server 2003及其以上版本
头文件 Shlobj.h
库文件 Shell32.lib
动态库 Shell32.dll(5.0或之后的版本)
Unicode版 SHCreateDirectoryExW
ANSI版   SHCreateDirectoryExA

SearchTreeForFile
功能
寻找指定文件的路径树
原型
BOOL WINAPI SearchTreeForFile(
  _In_   PCTSTR RootPath,
  _In_   PCTSTR InputPathName,
  _Out_  PTSTR OutputPathBuffer
);

参数
RootPath [in]
The path where the function should begin searching for the file.函数开始搜索文件的路径
InputPathName [in]
The file for which the function will search. You can use a partial path.函数要查找的文件.你也可以使用一个相对路径
OutputPathBuffer [out]
A 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.指向接收找到路径全路径的缓冲区.该字符串不会被更改,如果返回值为FALSE
返回值
函数如果成功返回TRUE. 失败返回FALSE,更多的失败信息请调用GetLastError函数

注意
函数在RootPath参数指定的路径开始查找在InputPathName参数中指定的文件. RootPath中包含的最大的路径深度为32个路径.当函数在目录树中找到了文件,它会将文件的全路径放在OutpuPathBuffer参数指定的缓冲区中.子目录的搜索顺序由底层的文件系统决定.
搜索可以被取消,如果你注册了SymRegisterCallbackProc64函数的回调函数.对于每一个目录搜索,本函数都会用CBA_DEFERRED_SYMBOL_LOAD_CANCEL参数调用回调函数.如果回调函数返回TRUE,本函数将会取消搜索.
本函数触发一个CBA_DEFERRED_SYMBOL_LOAD_CANCEL事件,在每个目录被搜索到时.这将允许调用者取消搜索.
这是一个单线程的函数
定义DBGHELP_TRANSLATE_TCHAR来使用Unicode版本