DriverEntry的第一個(gè)參數(shù)是一個(gè)指針，指向一個(gè)剛被初始化的驅(qū)動(dòng)程序?qū)ο螅搶?duì)象就代表你的驅(qū)動(dòng)程序。WDM驅(qū)動(dòng)程序的DriverEntry例程應(yīng)完成對(duì)這個(gè)對(duì)象的初始化并返回。非WDM驅(qū)動(dòng)程序需要做大量額外的工作，它們必須探測(cè)自己的硬件，為硬件創(chuàng)建設(shè)備對(duì)象(用于代表硬件)，配置并初始化硬件使其正常工作。而對(duì)于WDM驅(qū)動(dòng)程序，頗麻煩的硬件探測(cè)和配置工作由PnP管理器自動(dòng)完成，我將在第六章討論P(yáng)nP。如果你想知道非WDM驅(qū)動(dòng)程序是如何初始化自身的，參見(jiàn)Art Baker的《The Windows NT Device Driver Book (Prentice Hall, 1997)》、Viscarola和Mason的《Windows NT Device Driver Development (Macmillan, 1998)》。
DriverEntry的第二個(gè)參數(shù)是設(shè)備服務(wù)鍵的鍵名。這個(gè)串不是長(zhǎng)期存在的(函數(shù)返回后可能消失)，如果以后想使用該串就必須先把它復(fù)制到安全的地方。
對(duì)于WDM驅(qū)動(dòng)程序的DriverEntry例程，其主要工作是把各種函數(shù)指針填入驅(qū)動(dòng)程序?qū)ο蟆＿@些指針為操作系統(tǒng)指明了驅(qū)動(dòng)程序容器中各種子例程的位置。它們包括下面這些指針成員(驅(qū)動(dòng)程序?qū)ο笾?：
- DriverUnload 指向驅(qū)動(dòng)程序的清除例程。I/O管理器會(huì)在卸載驅(qū)動(dòng)程序前調(diào)用該例程。通常，WDM驅(qū)動(dòng)程序的DriverEntry例程一般不分配任何資源，所以DriverUnload例程也沒(méi)有什么清除工作要做。
- DriverExtension->AddDevice 指向驅(qū)動(dòng)程序的AddDevice函數(shù)。PnP管理器將為每個(gè)硬件實(shí)例調(diào)用一次AddDevice例程。由于AddDevice例程對(duì)WDM驅(qū)動(dòng)程序特別重要，所以我將在本章下一節(jié)單獨(dú)講述它。
- DriverStartIo 如果驅(qū)動(dòng)程序使用標(biāo)準(zhǔn)的IRP排隊(duì)方式，應(yīng)該設(shè)置該成員，使其指向驅(qū)動(dòng)程序的StartIo例程。如果你不理解什么是“標(biāo)準(zhǔn)”排隊(duì)方式，不要著急，到第五章你就會(huì)完全明白，許多驅(qū)動(dòng)程序都使用這種方法。
- MajorFunction 是一個(gè)指針數(shù)組，I/O管理器把每個(gè)數(shù)組元素都初始化成指向一個(gè)啞派遣函數(shù)，這個(gè)啞派遣函數(shù)僅返回失敗。驅(qū)動(dòng)程序可能僅需要處理幾種類(lèi)型的IRP，所以至少應(yīng)該設(shè)置與那幾種IRP類(lèi)型相對(duì)應(yīng)的指針元素，使它們指向相應(yīng)的派遣函數(shù)。我將在第五章詳細(xì)討論IRP和派遣函數(shù)。現(xiàn)在，你僅需要知道至少有三種IRP必須處理。
下面是一個(gè)近乎完整的DriverEntry例程：
extern "C"
NTSTATUS
DriverEntry(IN PDRIVER_OBJECT DriverObject, IN PUNICODE_STRING RegistryPath)
{
DriverObject->DriverUnload = DriverUnload; <--1
DriverObject->DriverExtension->AddDevice = AddDevice;
DriverObject->DriverStartIo = StartIo;
DriverObject->MajorFunction[IRP_MJ_PNP] = DispatchPnp; <--2
DriverObject->MajorFunction[IRP_MJ_POWER] = DispatchPower;
DriverObject->MajorFunction[IRP_MJ_SYSTEM_CONTROL] = DispatchWmi;
... <--3
servkey.Buffer = (PWSTR) ExAllocatePool(PagedPool, RegistryPath->Length + sizeof(WCHAR)); <--4
if (!servkey.Buffer)
return STATUS_INSUFFICIENT_RESOURCES;
servkey.MaximumLength = RegistryPath->Length + sizeof(WCHAR);
RtlCopyUnicodeString(&servkey, RegistryPath);
return STATUS_SUCCESS; <--5
}
|
- 前三條語(yǔ)句為驅(qū)動(dòng)程序的其它入口點(diǎn)設(shè)置了函數(shù)指針。在這里，我用了能表達(dá)其功能的名字命名了這些函數(shù)：DriverUnload、AddDevice、StartIo。
- 每個(gè)WDM驅(qū)動(dòng)程序必須能處理PNP、POWER、SYSTEM_CONTROL這三種請(qǐng)求；應(yīng)該在這里為這些請(qǐng)求指定派遣函數(shù)。在早期的Windows 2000 DDK中，IRP_MJ_SYSTEM_CONTROL曾被稱(chēng)作IRP_MJ_WMI，所以我把系統(tǒng)控制派遣函數(shù)命名為DispatchWmi。
- 在省略號(hào)處，你可以插入設(shè)置其它MajorFunction指針的代碼。
- 如果驅(qū)動(dòng)程序需要訪問(wèn)設(shè)備的服務(wù)鍵，可以在這里備份RegistryPath串。例如，如果驅(qū)動(dòng)程序要作為WMI生產(chǎn)者(見(jiàn)第十章)，則需要備份這個(gè)串。這里我假設(shè)已經(jīng)在某處聲明了一個(gè)類(lèi)型為UNICODE_STRING的全局變量servkey。
- 返回STATUS_SUCCESS指出函數(shù)成功。如果函數(shù)失敗，應(yīng)該返回NTSTATUS.H中的一個(gè)錯(cuò)誤代碼，或者返回用戶(hù)定義的錯(cuò)誤代碼。STATUS_SUCCESS的值為0。
DriverUnload例程
在WDM驅(qū)動(dòng)程序中，DriverUnload例程的作用就是釋放DriverEntry例程在全局初始化過(guò)程中申請(qǐng)的任何資源，但它幾乎沒(méi)什么可做。如果你在DriverEntry中備份了RegistryPath串，應(yīng)該在這里釋放備份所占用的內(nèi)存：
VOID DriverUnload(PDRIVER_OBJECT DriverObject)
{
RtlFreeUnicodeString(&servkey);
}
|
如果DriverEntry例程返回一個(gè)失敗狀態(tài)代碼，系統(tǒng)將不再調(diào)用DriverUnload例程。所以，不能讓DriverEntry例程出錯(cuò)后產(chǎn)生任何副作用，必須在它返回錯(cuò)誤代碼前消除副作用。