SHCreateThreadWithHandle 函数 (shlwapi.h)

项目
08/26/2023

创建一个新线程并检索其句柄。

语法

BOOL SHCreateThreadWithHandle(
  [in]            LPTHREAD_START_ROUTINE pfnThreadProc,
  [in, optional]  void                   *pData,
  [in]            SHCT_FLAGS             flags,
  [in, optional]  LPTHREAD_START_ROUTINE pfnCallback,
  [out, optional] HANDLE                 *pHandle
);

参数

[in] pfnThreadProc

类型： LPTHREAD_START_ROUTINE

指向 LPTHREAD_START_ROUTINE 类型的应用程序定义函数的指针。如果成功创建新线程，则会在该线程的上下文中调用此应用程序定义的函数。 SHCreateThreadWithHandle 不会等待 pfnThreadProc 指向的函数完成，然后再返回到其调用方。 pfnThreadProc 指定的函数的返回值是线程的退出代码。

[in, optional] pData

类型： void*

指向包含初始化数据的可选应用程序定义数据结构的指针。它传递给 pfnThreadProc 指向的函数，以及 pfnCallback 指向的函数（可选）。

[in] flags

类型： SHCT_FLAGS

控制函数行为的标志;一个或多个 CTF 常量。

[in, optional] pfnCallback

类型： LPTHREAD_START_ROUTINE

指向 LPTHREAD_START_ROUTINE 类型的可选应用程序定义函数的指针。在调用 pfnThreadProc 指向的函数之前，在创建的线程的上下文中调用此函数。它还将接收 pData 作为其参数。 SHCreateThreadWithHandle 等待 pfnCallback 指向的函数完成，然后再返回到其调用方。忽略 pfnCallback 指定的函数的返回值。

[out, optional] pHandle

类型： HANDLE*

指向所创建线程的 HANDLE 的指针。不再需要该句柄时，应通过调用 CloseHandle 函数关闭此句柄。此值可以为 NULL。

返回值

类型： BOOL

如果成功创建线程，则为 TRUE;否则为 FALSE

注解

在 Windows 7 之前，此函数没有关联的标头或库文件。若要在这些早期操作系统下使用此函数，请使用 DLL 名称 (Shlwapi.dll) 调用 LoadLibrary 以获取模块句柄。然后使用该模块句柄和 615 的函数序号调用 GetProcAddress 以获取此函数的地址。

pfnThreadProc 和 pfnCallback 指向的函数必须采用以下形式。

DWORD WINAPI ThreadProc(LPVOID pData)
{
    ...
}

函数名称是任意的。 pData 参数指向包含初始化信息的应用程序定义数据结构。

示例

下面的代码示例提供了用于按序号调用 SHCreateThreadWithHandle 的函数指针原型 typedef，并演示如何完成此类调用。

// Define SHCREATETHREADWITHHANDLE as a function pointer to SHCreateThreadWithHandle.
typedef BOOL (STDMETHODCALLTYPE *SHCREATETHREADWITHHANDLE)(LPTHREAD_START_ROUTINE, 
                                                           void *, 
                                                           DWORD, 
                                                           LPTHREAD_START_ROUTINE, 
                                                           HANDLE *);

// CallSHCreateThreadWithHandle is an example function that:
// 1. Accepts parameters for the SHCreateThreadWithHandle function.
// 2. Loads Shlwapi.dll, which implements SHCreateThreadWithHandle.
// 3. Obtains the address of SHCreateThreadWithHandle in the loaded library.
// 4. Calls SHCreateThreadWithHandle through a SHCREATETHREADWITHHANDLE function pointer.

BOOL CallSHCreateThreadWithHandle(LPTHREAD_START_ROUTINE pfnThreadProc, 
                                  void *pData,
                                  DWORD dwFlags, 
                                  LPTHREAD_START_ROUTINE pfnCallback, 
                                  HANDLE *pHandle)
{
    // Build a string that contains the local path to Shlwapi.dll.
    WCHAR szPath[MAX_PATH];
    GetSystemDirectory(szPath, ARRAYSIZE(szPath));  
    PathAppend(szPath, L"shlwapi.dll");

    // Attempt to load Shlwapi.dll.
    HMODULE hModule = LoadLibrary(szPath);

    HRESULT hr = hModule ? S_OK : HRESULT_FROM_WIN32(GetLastError());
    if (SUCCEEDED(hr)) 
    {
        // Shlwapi.dll is loaded. 
        // Before Windows 7, SHCreateThreadWithHandle must be accessed through 
        // its ordinal. The following commented lines are used for this.
        
        // Get the address of SHCreateThreadWithHandle through its ordinal value of 615.
        // SHCREATETHREADWITHHANDLE pfn =
        //     (SHCREATETHREADWITHHANDLE)GetProcAddress(hModule, MAKEINTRESOURCEA(615));
        //
        // hr = pfn ? S_OK : HRESULT_FROM_WIN32(GetLastError());
        //
        // if (SUCCEEDED(hr))
        // {
        //     // Call SHCreateThreadWithHandle through SHCREATETHREADWITHHANDLE.
        //     hr = pfn(pfnThreadProc, pData, dwFlags, pfnCallback, pHandle) 
        //               ? S_OK : HRESULT_FROM_WIN32(GetLastError());
        // }
        // FreeLibrary(hModule);
        
        hr = SHCreateThreadWithHandle(pfnThreadProc, pData, dwFlags, pfnCallback, pHandle) 
                       ? S_OK : HRESULT_FROM_WIN32(GetLastError());
    }
    return SUCCEEDED(hr);
}

要求


最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	shlwapi.h
Library	Shlwapi.lib
DLL	Shlwapi.dll (6.0 或更高版本)