Функция SHCreateThreadWithHandle (shlwapi.h)

Статья
08/26/2023

Создает новый поток и извлекает его дескриптор.

Синтаксис

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

Параметры

[in] pfnThreadProc

Тип: LPTHREAD_START_ROUTINE

Указатель на определяемую приложением функцию типа LPTHREAD_START_ROUTINE. Если новый поток был успешно создан, эта определяемая приложением функция вызывается в контексте этого потока. SHCreateThreadWithHandle не дожидается завершения функции, на которую указывает pfnThreadProc , прежде чем вернуться к вызывающей. Возвращаемое значение для функции, указанной pfnThreadProc , представляет собой код выхода потока.

[in, optional] pData

Тип: void*

Указатель на дополнительную структуру данных, определяемую приложением, которая содержит данные инициализации. Он передается в функцию, на которую указывает pfnThreadProc , и, при необходимости, в функцию, на которую указывает pfnCallback.

[in] flags

Тип: SHCT_FLAGS

Флаги, управляющие поведением функции; одна или несколько констант CTF .

[in, optional] pfnCallback

Тип: LPTHREAD_START_ROUTINE

Указатель на необязательную определяемую приложением функцию типа LPTHREAD_START_ROUTINE. Эта функция вызывается в контексте созданного потока перед вызовом функции, на которую указывает pfnThreadProc . Он также получит pData в качестве аргумента. SHCreateThreadWithHandle ожидает завершения функции, на которую указывает pfnCallback , прежде чем вернуться к вызывающей. Возвращаемое значение для функции, указанной pfnCallback , игнорируется.

[out, optional] pHandle

Тип: HANDLE*

Указатель на HANDLE созданного потока. Если он больше не нужен, этот дескриптор следует закрыть, вызвав функцию CloseHandle . Это значение может иметь значение NULL.

Возвращаемое значение

Тип: BOOL

Значение TRUE , если поток успешно создан; в противном случае — FALSE

До Windows 7 у этой функции не было связанного файла заголовка или библиотеки. Чтобы использовать эту функцию в предыдущих операционных системах, вызовите LoadLibrary с именем DLL (Shlwapi.dll), чтобы получить дескриптор модуля. Затем вызовите GetProcAddress с этим дескриптором модуля и порядком функции 615, чтобы получить адрес этой функции.

Функция, на которую указывают pfnThreadProc и pfnCallback , должна иметь следующую форму.

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

Имя функции является произвольным. Параметр pData указывает на определяемую приложением структуру данных со сведениями об инициализации.

Примеры

В следующем примере кода представлено определение типа прототипа указателя функции для вызова SHCreateThreadWithHandle по порядковой номеру и показано, как выполнить такой вызов.

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

Требования


Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	shlwapi.h
Библиотека	Shlwapi.lib
DLL	Shlwapi.dll (версия 6.0 или более поздняя)