Fungsi SHCreateThreadWithHandle (shlwapi.h)

Artikel
08/26/2023

Membuat utas baru dan mengambil handelnya.

Sintaks

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

Jenis: LPTHREAD_START_ROUTINE

Penunjuk ke fungsi jenis LPTHREAD_START_ROUTINE yang ditentukan aplikasi. Jika utas baru berhasil dibuat, fungsi yang ditentukan aplikasi ini dipanggil dalam konteks utas tersebut. SHCreateThreadWithHandle tidak menunggu fungsi yang ditunjukkan oleh pfnThreadProc selesai sebelum kembali ke pemanggilnya. Nilai yang dikembalikan untuk fungsi yang ditentukan oleh pfnThreadProc adalah kode keluar dari utas.

[in, optional] pData

Jenis: void*

Penunjuk ke struktur data opsional yang ditentukan aplikasi yang berisi data inisialisasi. Ini diteruskan ke fungsi yang ditunjukkan oleh pfnThreadProc dan, secara opsional, fungsi yang ditunjukkan oleh pfnCallback.

[in] flags

Jenis: SHCT_FLAGS

Bendera yang mengontrol perilaku fungsi; satu atau beberapa konstanta CTF .

[in, optional] pfnCallback

Jenis: LPTHREAD_START_ROUTINE

Penunjuk ke fungsi jenis LPTHREAD_START_ROUTINE yang ditentukan aplikasi opsional. Fungsi ini dipanggil dalam konteks utas yang dibuat sebelum fungsi yang ditunjukkan oleh pfnThreadProc dipanggil. Ini juga akan menerima pData sebagai argumennya. SHCreateThreadWithHandle menunggu fungsi yang ditunjukkan oleh pfnCallback selesai sebelum kembali ke pemanggilnya. Nilai yang dikembalikan untuk fungsi yang ditentukan oleh pfnCallback diabaikan.

[out, optional] pHandle

Jenis: HANDLE*

Penunjuk ke HANDLE dari utas yang dibuat. Ketika tidak lagi diperlukan, handel ini harus ditutup dengan memanggil fungsi CloseHandle . Nilai ini bisa NULL.

Menampilkan nilai

Jenis: BOOL

TRUE jika utas berhasil dibuat; jika tidak, FALSE

Keterangan

Sebelum Windows 7, fungsi ini tidak memiliki file header atau pustaka terkait. Untuk menggunakan fungsi ini di bawah sistem operasi sebelumnya, panggil LoadLibrary dengan nama DLL (Shlwapi.dll) untuk mendapatkan handel modul. Kemudian panggil GetProcAddress dengan handel modul tersebut dan ordinal fungsi 615 untuk mendapatkan alamat fungsi ini.

Fungsi yang ditunjukkan oleh pfnThreadProc dan pfnCallback harus mengambil formulir berikut.

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

Nama fungsi bersifat arbitrer. Parameter pData menunjuk ke struktur data yang ditentukan aplikasi dengan informasi inisialisasi.

Contoh

Contoh kode berikut menyediakan typedef prototipe penunjuk fungsi untuk memanggil SHCreateThreadWithHandle berdasarkan ordinal dan menunjukkan cara menyelesaikan panggilan seperti itu.

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

Persyaratan


Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	shlwapi.h
Pustaka	Shlwapi.lib
DLL	Shlwapi.dll (versi 6.0 atau yang lebih baru)