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參數會指向具有初始化資訊的應用程式定義資料結構。

範例

下列程式碼範例提供函式指標原型 typedef，以序數呼叫 SHCreateThreadWithHandle ，並示範如何完成這類呼叫。

// 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
程式庫	Shlwapi.lib
Dll	Shlwapi.dll (6.0 版或更新版本)