CWorkerThread 類別
這個類別會建立背景工作線程或使用現有的線程、等候一或多個核心物件句柄，並在其中一個句柄發出訊號時執行指定的用戶端函式。
重要
這個類別及其成員不能用於在 Windows 執行階段 中執行的應用程式。
語法
template <class ThreadTraits = DefaultThreadTraits>
class CWorkerThread
參數
ThreadTraits
提供線程建立函式的類別，例如 CRTThreadTraits 或 Win32ThreadTraits。
成員
受保護的結構
| 名稱 | 描述 |
|---|---|
WorkerClientEntry |
公用建構函式
| 名稱 | 描述 |
|---|---|
| CWorkerThread：：CWorkerThread | 背景工作線程的建構函式。 |
| CWorkerThread：：~CWorkerThread | 背景工作線程的解構函式。 |
公用方法
| 名稱 | 描述 |
|---|---|
| CWorkerThread：：AddHandle | 呼叫這個方法，將可等候物件的句柄新增至背景工作線程所維護的清單。 |
| CWorkerThread：：AddTimer | 呼叫此方法，將定期等候定時器新增至背景工作線程所維護的清單。 |
| CWorkerThread：：GetThreadHandle | 呼叫此方法以取得背景工作線程的線程句柄。 |
| CWorkerThread：：GetThreadId | 呼叫此方法以取得背景工作線程的線程標識碼。 |
| CWorkerThread：：Initialize | 呼叫此方法以初始化背景工作線程。 |
| CWorkerThread：：RemoveHandle | 呼叫這個方法，從可等候的物件清單中移除句柄。 |
| CWorkerThread：：Shutdown | 呼叫此方法以關閉背景工作線程。 |
備註
使用 CWorkerThread
建立這個類別的實例。
使用核心物件的句柄和 IWorkerThreadClient 實作的指標呼叫 CWorkerThread：：AddHandle。
- 或 -
使用 IWorkerThreadClient 實作的指標呼叫 CWorkerThread：：AddTimer。
實 作 IWorkerThreadClient：：Execute 以在收到句柄或定時器訊號時採取一些動作。
若要從可等候的物件清單中移除物件，請呼叫 CWorkerThread：：RemoveHandle。
若要終止線程，請呼叫 CWorkerThread：：Shutdown。
需求
標頭： atlutil.h
CWorkerThread：：AddHandle
呼叫這個方法，將可等候物件的句柄新增至背景工作線程所維護的清單。
HRESULT AddHandle(
HANDLE hObject,
IWorkerThreadClient* pClient,
DWORD_PTR dwParam) throw();
參數
物件
可等候物件的句柄。
pClient
當句柄發出訊號時，要呼叫之物件的IWorkerThreadClient 介面指標。
dwParam
當句柄發出訊號時，要傳遞至 IWorkerThreadClient：：Execute 的參數。
傳回值
傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。
備註
當句柄 hObject 發出訊號時，將會透過 pClient 呼叫 IWorkerThreadClient：：Execute。
CWorkerThread：：AddTimer
呼叫此方法，將定期等候定時器新增至背景工作線程所維護的清單。
HRESULT AddTimer(
DWORD dwInterval,
IWorkerThreadClient* pClient,
DWORD_PTR dwParam,
HANDLE* phTimer) throw();
參數
dwInterval
指定以毫秒為單位的定時器期間。
pClient
當句柄發出訊號時，要呼叫之物件的IWorkerThreadClient 介面指標。
dwParam
當句柄發出訊號時，要傳遞至 IWorkerThreadClient：：Execute 的參數。
phTimer
[out]成功時，HANDLE 變數的位址會接收新建立定時器的句柄。
傳回值
傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。
備註
當定時器發出訊號時，將會透過 pClient 呼叫 IWorkerThreadClient：：Execute。
將定時器句柄從 phTimer 傳遞至 CWorkerThread：：RemoveHandle 以關閉定時器。
CWorkerThread：：CWorkerThread
建構函式。
CWorkerThread() throw();
CWorkerThread：：~CWorkerThread
解構函式。
~CWorkerThread() throw();
備註
CWorkerThread：：GetThreadHandle
呼叫此方法以取得背景工作線程的線程句柄。
HANDLE GetThreadHandle() throw();
傳回值
如果背景工作線程尚未初始化，則傳回線程句柄或 NULL。
CWorkerThread：：GetThreadId
呼叫此方法以取得背景工作線程的線程標識碼。
DWORD GetThreadId() throw();
傳回值
如果背景工作線程尚未初始化，則傳回線程標識碼或 NULL。
CWorkerThread：：Initialize
呼叫此方法以初始化背景工作線程。
HRESULT Initialize() throw();
HRESULT Initialize(CWorkerThread<ThreadTraits>* pThread) throw();
參數
pThread
現有的背景工作線程。
傳回值
傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。
備註
在建立或呼叫 CWorkerThread：：Shutdown 之後，應該呼叫這個方法來初始化物件。
若要讓兩個或多個 CWorkerThread 物件使用相同的背景工作線程，請初始化其中一個物件，而不傳遞任何自變數，然後將該物件的指標傳遞給其他物件的 Initialize 方法。 使用指標初始化的對象應該先關閉，再關閉用來初始化它們的物件。
如需使用現有物件的指標初始化時，該方法行為如何變更的資訊，請參閱 CWorkerThread：：Shutdown 。
CWorkerThread：：RemoveHandle
呼叫這個方法，從可等候的物件清單中移除句柄。
HRESULT RemoveHandle(HANDLE hObject) throw();
參數
物件
要移除的句柄。
傳回值
傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。
備註
拿掉句柄時，會在傳遞至 AddHandle 的相關聯物件上呼叫 IWorkerThreadClient：：CloseHandle。 如果此呼叫失敗， CWorkerThread 將會在句柄上呼叫 Windows CloseHandle 函式。
CWorkerThread：：Shutdown
呼叫此方法以關閉背景工作線程。
HRESULT Shutdown(DWORD dwWait = ATL_WORKER_THREAD_WAIT) throw();
參數
dwWait
等候背景工作線程關閉的時間，以毫秒為單位。 ATL_WORKER_THREAD_WAIT預設為10秒。 如有必要，您可以先為此符號定義自己的值，再包含 atlutil.h。
傳回值
傳回成功時S_OK，或失敗時發生錯誤 HRESULT，例如超過逾時值 dwWait。
備註
若要重複使用物件，請在呼叫此方法之後呼叫 CWorkerThread：：Initialize 。
請注意，在以指向另一個CWorkerThread物件的指標初始化的物件上呼叫 Shutdown 沒有任何作用，而且一律會傳回S_OK。
另請參閱
DefaultThreadTraits
類別
多執行緒：建立背景工作執行緒
IWorkerThreadClient 介面