IoCreateSystemThread 函式 (wdm.h)

IoCreateSystemThread 例程會建立以內核模式執行的系統線程，並提供線程的句柄。

語法

NTSTATUS IoCreateSystemThread(
  [in, out]       PVOID              IoObject,
  [out]           PHANDLE            ThreadHandle,
  [in]            ULONG              DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  HANDLE             ProcessHandle,
  [out, optional] PCLIENT_ID         ClientId,
  [in]            PKSTART_ROUTINE    StartRoutine,
  [in, optional]  PVOID              StartContext
);

參數

[in, out] IoObject

要與所建立線程產生關聯的 DEVICE_OBJECT 或 DRIVER_OBJECT 指標。 IoCreateSystemThread 會接受此物件的計數參考。 I/O 管理員稍後會在線程結束時釋放此參考。 如需詳細資訊，請參閱＜備註＞。

[out] ThreadHandle

例程寫入所建立線程核心句柄之變數的指標。 不再需要句柄時，驅動程式必須呼叫 ZwClose 例程來關閉句柄。

[in] DesiredAccess

ACCESS_MASK值，表示呼叫端對所建立線程要求的存取類型。

[in, optional] ObjectAttributes

指定線程物件屬性 之OBJECT_ATTRIBUTES 結構的指標。 線程物件的OBJ_PERMANENT、OBJ_EXCLUSIVE和OBJ_OPENIF屬性不是有效的屬性。 如果呼叫端未在系統進程內容中執行，則必須在OBJECT_ATTRIBUTES結構中設定 OBJ_KERNEL_HANDLE 屬性。

[in, optional] ProcessHandle

進程的開啟句柄，其位址空間是執行所建立線程。 呼叫端的線程必須具有此進程的PROCESS_CREATE_THREAD存取權。 如果此參數為 NULL，則會在初始系統進程中建立線程。 針對驅動程式建立的線程，此參數應該是 NULL 。 使用 Wdm.h 頭檔中定義的 NtCurrentProcess 宏來指定目前的進程。

[out, optional] ClientId

結構指標，例程會寫入所建立線程的用戶端標識符。 針對驅動程式建立的線程，此參數應該是 NULL 。

[in] StartRoutine

ThreadStart 例程的指標，這是所建立線程的進入點。

[in, optional] StartContext

當建立的線程開始執行時，做為 StartContext 參數傳遞至 ThreadStart 例程的內容指標。

傳回值

如果已成功建立新的線程，IoCreateSystemThread 會傳回STATUS_SUCCESS。 可能的傳回值包括下列錯誤狀態代碼。

備註

從 Windows 8 開始，驅動程式可以呼叫IoCreateSystemThread來建立裝置專用線程。 此例程會建立新的系統線程，該線程沒有線程環境區塊 (TEB) 或使用者模式內容，而且只會在核心模式中執行。

一般而言，驅動程式會在啟動裝置時呼叫 IoCreateSystemThread ，或驅動程式的 DispatchXxx例程開始接收I/O要求時呼叫。 例如，當 DispatchXxx 例程收到異步裝置控制要求時，驅動程式可能會呼叫此例程來建立線程。

如果 ProcessHandle 參數為 NULL，則建立的線程會與系統進程相關聯。 這類線程會繼續執行，直到系統關閉或線程結束為止。

在系統進程以外的進程內容中執行的驅動程式例程，必須為IoCreateSystemThread的 ObjectAttributes 參數設定 OBJ_KERNEL_HANDLE 屬性。 此屬性會將 IoCreateSystemThread 所傳回的句柄，限制為在核心模式中執行的進程。 否則，線程句柄可由驅動程序執行所在的進程存取。 驅動程式可以呼叫 InitializeObjectAttributes 宏，在對象屬性中設定OBJ_KERNEL_HANDLE屬性，如下列程式代碼範例所示。

OBJECT_ATTRIBUTES ObjectAttributes;

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

IoCreateSystemThread 類似於 PsCreateSystemThread 例程，但有額外的參數 IoObject，這是呼叫端驅動程式對象或裝置物件的指標。 IoCreateSystemThread 會使用此參數來確保驅動程式無法在建立的線程存在時卸除。 在排程 StartRoutine 在此線程中執行之前， IoCreateSystemThread 會採用 IoObject 物件的計數參考。 I/O 管理員會在建立的線程結束時釋放此參考。 因此，這個物件會在所建立線程的存留期內保存。

相較於 PsCreateSystemThread 例程所建立的系統線程， IoCreateSystemThread 所建立的線程不會呼叫 PsTerminateSystemThread 例程來終止本身。 相反地，I/O 管理員會在線程結束時代表建立的線程呼叫 PsTerminateSystemThread 。

規格需求

另請參閱

ACCESS_MASK

DEVICE_OBJECT

DRIVER_OBJECT

InitializeObjectAttributes

OBJECT_ATTRIBUTES

PsCreateSystemThread

PsTerminateSystemThread

ThreadStart

ZwClose