SHCreateThreadWithHandle-Funktion (shlwapi.h)

Artikel
08/26/2023

Erstellt einen neuen Thread und ruft dessen Handle ab.

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

Parameter

[in] pfnThreadProc

Typ: LPTHREAD_START_ROUTINE

Ein Zeiger auf eine anwendungsdefinierte Funktion vom Typ LPTHREAD_START_ROUTINE. Wenn ein neuer Thread erfolgreich erstellt wurde, wird diese anwendungsdefinierte Funktion im Kontext dieses Threads aufgerufen. SHCreateThreadWithHandle wartet nicht, bis die Funktion abgeschlossen ist, auf die pfnThreadProc verweist, bevor der Aufrufer zurückgegeben wird. Der Rückgabewert für die von pfnThreadProc angegebene Funktion ist der Exitcode des Threads.

[in, optional] pData

Typ: void*

Ein Zeiger auf eine optionale anwendungsdefinierte Datenstruktur, die Initialisierungsdaten enthält. Sie wird an die Funktion übergeben, auf die pfnThreadProc verweist, und optional die Funktion, auf die pfnCallback verweist.

[in] flags

Typ: SHCT_FLAGS

Flags, die das Verhalten der Funktion steuern; eine oder mehrere der CTF-Konstanten .

[in, optional] pfnCallback

Typ: LPTHREAD_START_ROUTINE

Ein Zeiger auf eine optionale anwendungsdefinierte Funktion vom Typ LPTHREAD_START_ROUTINE. Diese Funktion wird im Kontext des erstellten Threads aufgerufen, bevor die Funktion aufgerufen wird, auf die pfnThreadProc verweist. Außerdem wird pData als Argument empfangen. SHCreateThreadWithHandle wartet, bis die Funktion abgeschlossen ist, auf die pfnCallback verweist, bevor es zum Aufrufer zurückkehrt. Der Rückgabewert für die von pfnCallback angegebene Funktion wird ignoriert.

[out, optional] pHandle

Typ: HANDLE*

Ein Zeiger auf den HANDLE des erstellten Threads. Wenn es nicht mehr benötigt wird, sollte dieses Handle durch Aufrufen der CloseHandle-Funktion geschlossen werden. Dieser Wert kann NULL sein.

Rückgabewert

Typ: BOOL

TRUE , wenn der Thread erfolgreich erstellt wurde; andernfalls FALSE

Hinweise

Vor Windows 7 verfügte diese Funktion nicht über eine zugehörige Header- oder Bibliotheksdatei. Um diese Funktion unter diesen früheren Betriebssystemen zu verwenden, rufen Sie LoadLibrary mit dem DLL-Namen (Shlwapi.dll) auf, um ein Modulhandle abzurufen. Rufen Sie dann GetProcAddress mit diesem Modulhandle und einer Funktionszahl von 615 auf, um die Adresse dieser Funktion abzurufen.

Die Funktion, auf die von pfnThreadProc und pfnCallback verwiesen wird, muss die folgende Form annehmen.

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

Der Funktionsname ist beliebig. Der pData-Parameter verweist auf eine anwendungsdefinierte Datenstruktur mit Initialisierungsinformationen.

Beispiele

Im folgenden Codebeispiel wird eine Funktionszeiger-Prototyptypdefinition zum Aufrufen von SHCreateThreadWithHandle nach Ordinal bereitgestellt. Außerdem wird gezeigt, wie ein solcher Aufruf ausgeführt wird.

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

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shlwapi.h
Bibliothek	Shlwapi.lib
DLL	Shlwapi.dll (Version 6.0 oder höher)