Funzione SHCreateThreadWithHandle (shlwapi.h)

Articolo
08/26/2023

Crea un nuovo thread e ne recupera l'handle.

Sintassi

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

Parametri

[in] pfnThreadProc

Tipo: LPTHREAD_START_ROUTINE

Puntatore a una funzione definita dall'applicazione di tipo LPTHREAD_START_ROUTINE. Se è stato creato correttamente un nuovo thread, questa funzione definita dall'applicazione viene chiamata nel contesto di tale thread. SHCreateThreadWithHandle non attende il completamento della funzione a cui fa riferimento pfnThreadProc prima di tornare al chiamante. Il valore restituito per la funzione specificata da pfnThreadProc è il codice di uscita del thread.

[in, optional] pData

Tipo: void*

Puntatore a una struttura di dati facoltativa definita dall'applicazione che contiene i dati di inizializzazione. Viene passato alla funzione a cui punta pfnThreadProc e, facoltativamente, la funzione a cui punta pfnCallback.

[in] flags

Tipo: SHCT_FLAGS

Flag che controllano il comportamento della funzione; una o più costanti CTF .

[in, optional] pfnCallback

Tipo: LPTHREAD_START_ROUTINE

Puntatore a una funzione facoltativa definita dall'applicazione di tipo LPTHREAD_START_ROUTINE. Questa funzione viene chiamata nel contesto del thread creato prima che venga chiamata la funzione a cui punta pfnThreadProc . Riceverà anche pData come argomento. SHCreateThreadWithHandle attende il completamento della funzione a cui fa riferimento pfnCallback prima di tornare al chiamante. Il valore restituito per la funzione specificata da pfnCallback viene ignorato.

[out, optional] pHandle

Tipo: HANDLE*

Puntatore all'handle del thread creato. Quando non è più necessario, questo handle deve essere chiuso chiamando la funzione CloseHandle . Questo valore può essere NULL.

Valore restituito

Tipo: BOOL

TRUE se il thread viene creato correttamente; in caso contrario, FALSE

Commenti

Prima di Windows 7, questa funzione non disponeva di un'intestazione o di un file di libreria associato. Per usare questa funzione in questi sistemi operativi precedenti, chiamare LoadLibrary con il nome dll (Shlwapi.dll) per ottenere un handle di modulo. Chiamare quindi GetProcAddress con l'handle del modulo e un numero ordinale di funzione 615 per ottenere l'indirizzo di questa funzione.

La funzione a cui punta pfnThreadProc e pfnCallback deve assumere il formato seguente.

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

Il nome della funzione è arbitrario. Il parametro pData punta a una struttura di dati definita dall'applicazione con informazioni di inizializzazione.

Esempio

Nell'esempio di codice seguente viene fornito un typedef prototipo del puntatore a funzione per chiamare SHCreateThreadWithHandle per ordinale e viene illustrato come eseguire tale chiamata.

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

Requisiti


Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shlwapi.h
Libreria	Shlwapi.lib
DLL	Shlwapi.dll (versione 6.0 o successiva)