Função SHCreateThreadWithHandle (shlwapi.h)

Artigo
08/26/2023

Cria um novo thread e recupera seu identificador.

Sintaxe

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

Parâmetros

[in] pfnThreadProc

Tipo: LPTHREAD_START_ROUTINE

Um ponteiro para uma função definida pelo aplicativo do tipo LPTHREAD_START_ROUTINE. Se um novo thread tiver sido criado com êxito, essa função definida pelo aplicativo será chamada no contexto desse thread. SHCreateThreadWithHandle não aguarda a função apontada por pfnThreadProc ser concluída antes de retornar ao chamador. O valor retornado para a função especificada por pfnThreadProc é o código de saída do thread.

[in, optional] pData

Tipo: void*

Um ponteiro para uma estrutura de dados opcional definida pelo aplicativo que contém dados de inicialização. Ele é passado para a função apontada por pfnThreadProc e, opcionalmente, a função apontada por pfnCallback.

[in] flags

Tipo: SHCT_FLAGS

Sinalizadores que controlam o comportamento da função; uma ou mais das constantes CTF .

[in, optional] pfnCallback

Tipo: LPTHREAD_START_ROUTINE

Um ponteiro para uma função opcional definida pelo aplicativo do tipo LPTHREAD_START_ROUTINE. Essa função é chamada no contexto do thread criado antes que a função apontada por pfnThreadProc seja chamada. Ele também receberá pData como seu argumento. SHCreateThreadWithHandle aguarda a função apontada por pfnCallback ser concluída antes de retornar ao chamador. O valor retornado para a função especificada por pfnCallback é ignorado.

[out, optional] pHandle

Tipo: HANDLE*

Um ponteiro para o HANDLE do thread criado. Quando não for mais necessário, esse identificador deverá ser fechado chamando a função CloseHandle . Esse valor pode ser NULL.

Valor retornado

Tipo: BOOL

TRUE se o thread for criado com êxito; caso contrário, FALSE

Comentários

Antes do Windows 7, essa função não tinha um arquivo de cabeçalho ou biblioteca associado. Para usar essa função nesses sistemas operacionais anteriores, chame LoadLibrary com o nome DLL (Shlwapi.dll) para obter um identificador de módulo. Em seguida, chame GetProcAddress com esse identificador de módulo e um ordinal de função de 615 para obter o endereço dessa função.

A função apontada por pfnThreadProc e pfnCallback deve assumir o seguinte formato.

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

O nome da função é arbitrário. O parâmetro pData aponta para uma estrutura de dados definida pelo aplicativo com informações de inicialização.

Exemplos

O exemplo de código a seguir fornece um typedef de protótipo de ponteiro de função para chamar SHCreateThreadWithHandle por ordinal e mostra como realizar essa chamada.

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

Requisitos


Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shlwapi.h
Biblioteca	Shlwapi.lib
DLL	Shlwapi.dll (versão 6.0 ou posterior)