SHCreateThreadWithHandle function (shlwapi.h)

Article
10/13/2021

Creates a new thread and retrieves its handle.

Syntax

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
);

Parameters

[in] pfnThreadProc

Type: LPTHREAD_START_ROUTINE

A pointer to an application-defined function of type LPTHREAD_START_ROUTINE. If a new thread was successfully created, this application-defined function is called in the context of that thread. SHCreateThreadWithHandle does not wait for the function pointed to by pfnThreadProc to complete before returning to its caller. The return value for the function specified by pfnThreadProc is the exit code of the thread.

[in, optional] pData

Type: void*

A pointer to an optional application-defined data structure that contains initialization data. It is passed to the function pointed to by pfnThreadProc and, optionally, the function pointed to by pfnCallback.

[in] flags

Type: SHCT_FLAGS

Flags that control the behavior of the function; one or more of the CTF constants.

[in, optional] pfnCallback

Type: LPTHREAD_START_ROUTINE

A pointer to an optional application-defined function of type LPTHREAD_START_ROUTINE. This function is called in the context of the created thread before the function pointed to by pfnThreadProc is called. It will also receive pData as its argument. SHCreateThreadWithHandle waits for the function pointed to by pfnCallback to complete before returning to its caller. The return value for the function specified by pfnCallback is ignored.

[out, optional] pHandle

Type: HANDLE*

A pointer to the HANDLE of the created thread. When it is no longer needed, this handle should be closed by calling the CloseHandle function. This value can be NULL.

Return value

Type: BOOL

TRUE if the thread is successfully created; otherwise, FALSE

Remarks

Prior to Windows 7, this function did not have an associated header or library file. To use this function under those earlier operating systems, call LoadLibrary with the DLL name (Shlwapi.dll) to obtain a module handle. Then call GetProcAddress with that module handle and a function ordinal of 615 to get the address of this function.

The function pointed to by pfnThreadProc and pfnCallback must take the following form.

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

The function name is arbitrary. The pData parameter points to an application-defined data structure with initialization information.

Examples

The following code example provides a function pointer prototype typedef for calling SHCreateThreadWithHandle by ordinal and shows how to accomplish such a call.

// 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);
}

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	shlwapi.h
Library	Shlwapi.lib
DLL	Shlwapi.dll (version 6.0 or later)

Share via