Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

SHCreateThreadWithHandle function

Creates a new thread and retrieves its handle.

Syntax


BOOL SHCreateThreadWithHandle(
  _In_       LPTHREAD_START_ROUTINE pfnThreadProc,
  _In_opt_   void *pData,
  _In_       SHCT_FLAGS flags,
  _In_opt_   LPTHREAD_START_ROUTINE pfnCallback,
  _Out_opt_  HANDLE *pHandle
);

Parameters

pfnThreadProc [in]

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.

pData [in, optional]

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.

flags [in]

Type: SHCT_FLAGS

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

pfnCallback [in, optional]

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.

pHandle [out, optional]

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

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Shlwapi.h

Library

Shlwapi.lib

DLL

Shlwapi.dll (version 6.0 or later)

See also

LoadLibrary
GetProcAddress
GetSystemDirectory
GetLastError
HRESULT_FROM_WIN32

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.