[ Windows DDP ] 驅動程式的同步處理 : 核心模式下的同步物件 - 事件物件

前言 : 
在應用程式中, 程式設計師只能操作事件控制碼, 無法得到事件物件的指標. 在與事件相關的 Win32 API 函式內部, 會呼叫核心模式事件的相關函式. 
在內核函式中, 用 KEVENT 資料結構表示一個事件物件. 在使用事件物件前, 需要對其進行初始化. 內核函式 KeInitializeEvent 負責對事件物件初始化, 其宣告如下 : 

- Syntax :

view plaincopy to clipboardprint?

1. VOID KeInitializeEvent(  
2.   __out  PRKEVENT Event,  
3.   __in   EVENT_TYPE Type,  
4.   __in   BOOLEAN State  
5. );  

參數說明 : 

* Event : 這個參數是初始化事件物件的指標.
* Type : 這個參數是事件的類型. 事件類型分兩種, 一類是 "通知事件", 對應參數是 NotificationEvent, 另一類是 "同步事件", 對應參數 SynchronizationEvent.
* State : 這個參數如果為真, 事件物件的初始化狀態為激發狀態, 如果為假, 則為未激發狀態.

如果新建的事件物件是 "通知物件", 當事件物件變為激發狀態時, 程式設計師需要手動將其改回未激發狀態. 如果新建事件物件是 "同步事件", 當事件物件為激發狀態時, 如遇到 KeWaitForXXX 等內核函式, 事件則自動變回未激發狀態. 
下面的例子展示如何在驅動程式中使用事件物件. 這個例子首先新建一個事件物件, 然後新建一個新的執行緒, 並將事件物件的指標傳遞給執行緒, 主執行緒等待事件物件. 新建的執行緒完成任務後, 將事件物件設為激發狀態, 主執行緒得以繼續執行. 

- Driver.cpp : 使用內核模式物件範例

view plaincopy to clipboardprint?

1. VOID MyProcessFun(IN PVOID pContext)  
2. {  
3.     PKEVENT pEvent = (PKEVENT)pContext; // 獲得事件指標  
4.     KdPrint(("Enter MyProcessFun\n"));  
5.     KeSetEvent(pEvent, IO_NO_INCREMENT, FALSE);  
6.     KdPrint(("Leave MyProcessFun\n"));  
7.     PsTerminateSystemThread(STATUS_SUCCESS);  
8. }  
9.   
10. #pragma PAGEDCODE  
11. VOID Test()  
12. {  
13.     HANDLE hMyThread;  
14.     KEVENT kEvent;  
15.     KeInitializeEvent(&kEvent, NotificationEvent, FALSE); // 初始化內核事件  
16.     NTSTATUS status = PsCreateSystemThread(&hMyThread, 0, NULL, NtCurrentProcess(), NULL, MyProcessFun, &kEvent);  
17.     // 接下來很重要, 如果下面不等待, 則新建的 Thread 引用了本函式堆疊上的變數, 當函式退出同時堆疊上變數被收回  
18.     // 則新建的Thread 引用的參數會出現錯誤.  
19.     KeWaitForSingleObject(&kEvent, Executive, KernelMode, FALSE, NULL);  
20. }  

驅動程式與應用程式互動事件物件 : 
前面已經介紹過, 應用程式中新建的事件和在內核中新建的事件物件, 本質上是同一個東西. 在使用者模式時, 它用控制碼包裝, 在核心模式下, 它用 KEVENT 資料結構代表. 在應用程式中, 所有內核物件都不會被使用者看到, 使用者看到的是代表內核物件的物件控制碼. 這裡要介紹的就是如何在應用程式和驅動程式中共用一個事件物件. 
需要解決的第一個問題就是如何將使用者模式下新建的事件傳遞給驅動程式. 解決的辦法是採用 DeviceIoControl API 函式. 在使用者模式下新建一個同步物件, 然後用 DeviceIoControl 把事件控制碼傳遞給驅動程式. 需要指出的是控制碼與處理程序是相關的, 也就意味著一個處理程序中的控制碼只能在這個處理程序中生效. 控制碼相當於事件物件在處理程序中的索引, 透過這個索引作業系統就會得到事件物件的指標. DDK 提供了內核函式將控制碼轉化為指標, 該函式是 ObReferenceObjectByHandle. 
ObReferenceObjectByHandle 函式在得到指標的同時, 會為物件的指標維護一個計數. 每次呼叫 ObReferenceObjectByHandle 會使計數加 1. 因此為計數平衡, 在使用完 ObReferenceObjectByHandle 函式後需要呼叫 ObDereferenceObject 函式. ObDereferenceObject 使計數減一. 
ObReferenceObjectByHandle 函式會返回一個狀態值, 表明是否成功取得指標. 

驅動程式與驅動程式互動事件物件 : 
有時候還需要在驅動程式之間互動事件物件. 例如驅動程式 A 的某個派遣函式要與驅動程式 B 的派遣函式進行同步, 就需要兩個驅動程式之間互動事件物件. 關鍵的問題就是如何讓驅動程式 A 獲取驅動程式 B 中新建的事件物件. 最簡單的方法就是驅動程式 B 新建一個有 "名字" 的事件物件, 這樣驅動程式 A 就可以根據 "名字" 尋找到事件物件的指標. 
新建有名字的事件物件可以透過 IoCreateNotificationEvent 和 IoCreateSynchronizationEvent 內核函式. 其中第一個函式新建 "通知事件" 而 第二個函式新建 "同步事件". 這兩個差別已經在介紹 KeInitializationEvent 函式時後說過. 
這兩個函式都用 UNICODE_STRING 字串描述內核事件物件的名字, 如果內核中不存在指定名稱的內核事件物件, 函式會新建該名稱的內核事件物件. 如果已經存在了該名稱的內核事件物件, 則函式會打開這個內核事件物件. 這兩個函式的到內核事件物件的控制碼, 為了進一步得到內核事件物件的指標, 可以使用前面介紹的內核函式 ObReferenceObjectByHandle. 因此在不同的驅動程式中, 只要知道事件物件的名稱, 就可以互動事件物件. 給內核事件物件命名時, 最好不要用很簡單的名字, 否則會發生命明衝突.