Fonction SHCreateThreadWithHandle (shlwapi.h)

Article
08/26/2023

Crée un thread et récupère son handle.

Syntaxe

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

Paramètres

[in] pfnThreadProc

Type : LPTHREAD_START_ROUTINE

Pointeur vers une fonction définie par l’application de type LPTHREAD_START_ROUTINE. Si un nouveau thread a été créé avec succès, cette fonction définie par l’application est appelée dans le contexte de ce thread. SHCreateThreadWithHandle n’attend pas que la fonction pointée vers pfnThreadProc se termine avant de revenir à son appelant. La valeur de retour de la fonction spécifiée par pfnThreadProc est le code de sortie du thread.

[in, optional] pData

Type : void*

Pointeur vers une structure de données facultative définie par l’application qui contient des données d’initialisation. Il est passé à la fonction pointée vers pfnThreadProc et, éventuellement, à la fonction pointée vers par pfnCallback.

[in] flags

Type : SHCT_FLAGS

Indicateurs qui contrôlent le comportement de la fonction ; une ou plusieurs constantes CTF .

[in, optional] pfnCallback

Type : LPTHREAD_START_ROUTINE

Pointeur vers une fonction facultative définie par l’application de type LPTHREAD_START_ROUTINE. Cette fonction est appelée dans le contexte du thread créé avant que la fonction pointée par pfnThreadProc ne soit appelée. Il recevra également pData comme argument. SHCreateThreadWithHandle attend que la fonction pointée par pfnCallback se termine avant de revenir à son appelant. La valeur de retour de la fonction spécifiée par pfnCallback est ignorée.

[out, optional] pHandle

Type : HANDLE*

Pointeur vers le HANDLE du thread créé. Lorsqu’il n’est plus nécessaire, ce handle doit être fermé en appelant la fonction CloseHandle . Cette valeur peut être NULL.

Valeur retournée

Type : BOOL

TRUE si le thread a été créé ; sinon, FALSE

Remarques

Avant Windows 7, cette fonction n’avait pas d’en-tête ou de fichier de bibliothèque associé. Pour utiliser cette fonction sous ces systèmes d’exploitation antérieurs, appelez LoadLibrary avec le nom de DLL (Shlwapi.dll) pour obtenir un handle de module. Ensuite, appelez GetProcAddress avec ce handle de module et un ordinal de fonction de 615 pour obtenir l’adresse de cette fonction.

La fonction pointée vers par pfnThreadProc et pfnCallback doit prendre la forme suivante.

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

Le nom de la fonction est arbitraire. Le paramètre pData pointe vers une structure de données définie par l’application avec des informations d’initialisation.

Exemples

L’exemple de code suivant fournit un prototype de pointeur de fonction typedef pour appeler SHCreateThreadWithHandle par ordinal et montre comment effectuer un tel appel.

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

Configuration requise


Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shlwapi.h
Bibliothèque	Shlwapi.lib
DLL	Shlwapi.dll (version 6.0 ou ultérieure)