WDI IHV 驅動程式介面

WDI IHV 迷你埠驅動程式如同其他 NDIS 迷你埠驅動程式，應遵循 NDIS 迷你埠的開發實務和文件指南。 原生 WLAN 迷你埠驅動程式對 NDIS 處理程式的責任會在 MS 元件與 WDI IHV 驅動程式之間分割。 Microsoft WLAN 元件會負責適用於所有 Wi-Fi 迷你埠的 NDIS 需求，讓每個 IHV 都不需要重做所有工作。 以下說明當套用至 WDI IHV 迷你埠時，原生 WLAN IHV 迷你埠的 NDIS 處理程式的對應關係及其行為變更。

• 驅動程式安裝
• DriverEntry
• MiniportSetOptions
• MiniportInitializeEx
• MiniportHaltEx
• MiniportDriverUnload
• MiniportPause
• MiniportRestart
• MiniportResetEx
• MiniportDevicePnPEventNotify
• MiniportShutdownEx
• MiniportOidRequest
• MiniportCancelOidRequest
• NdisMIndicateStatusEx
• MiniportDirectOidRequest
• MiniportCancelDirectOidRequest
• MiniportSendNetBufferLists
• MiniportCancelSend（取消發送的迷你端口）
• MiniportReturnNetBufferLists
• WDI 處理程式：MiniportWdiOpenAdapter
• WDI 處理程式：MiniportWdiCloseAdapter

驅動程式安裝

WDI IHV 迷你埠驅動程式載入並安裝在系統上的方式沒有任何變更。 INF 和安裝程式類似於 IHV 原生 WLAN 迷你埠驅動程式。 與現有的 NDIS 驅動程式一樣，當 IHV 驅動程式需要載入以搭配 IHV 的 WLAN 網路卡運作時，作業系統會呼叫 IHV 微型端口驅動程式的 DriverEntry 例程函數。

DriverEntry

操作系統會直接呼叫 WDI IHV 迷你埠驅動程式的 DriverEntry 例程。 IHV 迷你埠遵循一般 NDIS 迷你埠 DriverEntry 例程的大部分指導方針。 其中一個例外狀況是，IHV 迷你埠會呼叫 NdisMRegisterWdiMiniportDriver 來告訴作業系統啟用 Microsoft WLAN 元件，而不是呼叫 NdisMRegisterMiniportDriver。

以下是 NdisMRegisterWdiMiniportDriver的主要參數。

• NDIS_MINIPORT_DRIVER_CHARACTERISTICS：這是原生 Wi-Fi 迷你埠用來向 NDIS 註冊的原始 NDIS 結構。 對於 WDI 模型，大部分的處理程序參數都是選擇性的。 唯一必要的處理程式是 MINIPORT_OID_REQUEST_HANDLER 與 MINIPORT_DRIVER_UNLOAD。 MINIPORT_OID_REQUEST_HANDLER 可用來將 WDI 訊息傳遞至 IHV 驅動程式。 如果指定了任何其他處理程式，Microsoft WLAN 元件通常會在進行了自身的處理後呼叫該處理程式。
• NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS：這是 WDI 迷你埠驅動程序必須實作的新處理程式集。 IHV 驅動程式會使用它來註冊控件路徑的其他處理程式，以及數據路徑的完整處理程式集。

當 IHV 迷你埠呼叫 NdisMRegisterWdiMiniportDriver 時，Microsoft WLAN 元件會更新 NDIS_MINIPORT_DRIVER_CHARACTERISTICS 的處理程式，並呼叫 NDIS 的 NdisMRegisterMiniportDriver。 更新已完成，讓 Microsoft WLAN 元件可以攔截負責 WDI IHV 迷你端口驅動程式的處理程序，並為其提供協助或簡化。

以下是 WDI IHV 迷你埠驅動程式的 DriverEntry 程式一般流程

如需有關 DriverEntry 的詳細資訊，請參閱 NDIS 迷你埠驅動程式的 DriverEntry。

MiniportSetOptions

如上方 DriverEntry 圖所示，如果 WDI IHV 小型埠已註冊 MiniportSetOptions 處理程式，作業系統會在小型埠驅動程式呼叫 NdisMRegisterWdiMiniportDriver 的過程中呼叫該函式。

如果 IHV 迷你埠驅動程式使用 NdisSetOptionalHandlers註冊任何選項處理程式，則 Microsoft 元件可能無法通過 WDI 層對這些處理程式進行序列化。 因此，IHV 元件負責處理這些處理程式的任何同步處理需求。

MiniportInitializeEx

WDI 模型會將 MiniportInitializeEx 行為分割成多個 WDI 介面呼叫。

1. 呼叫 MiniportWdiAllocateAdapter。

   當作業系統找到 IHV 硬體時，這是第一次呼叫 WDI IHV miniport 驅動程式。 在此呼叫中，WDI 迷你埠會執行建立裝置軟體表示法所需的動作（MiniportAdapterContext）。 它還會確定裝置的相關信息，以填入 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 結構中。 當 Microsoft 元件傳送 WDI 命令下去以執行特定初始化時，裝置的實際初始化和 Wi-Fi 堆疊才會完成。

   使用從 WDI IHV 迷你埠驅動程式取得的數據，Microsoft元件會呼叫 NdisMSetMiniportAttributes，並在 NDIS 上設定 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES。 大部分 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 欄位會填入 Microsoft 元件的預設值。 IHV 驅動程式必須填入 MiniportAdapterContext 和 InterfaceType 字段。

   一旦此呼叫從 IHV 迷你埠驅動程式傳回，就會開始透過其 MiniportOidRequest 處理程式接收 WDI 命令。 在此呼叫期間，Microsoft元件可能無法執行重設/復原作業，因此此處執行的任何活動都應該快速且可靠。

2. 呼叫 MiniportWdiOpenAdapter。

   MiniportWdiAllocateAdapter之後，Microsoft元件會呼叫 MiniportWdiOpenAdapter 以載入韌體並初始化硬體。

3. 多個 WDI 命令使用 MiniportOidRequest。

   MiniportWdiOpenAdapter之後，Microsoft 元件會將下列任務/屬性/呼叫傳送至 IHV 小型介面卡。

   1. 呼叫 MiniportWdiTalTxRxInitialize 來初始化數據路徑和交換處理程式。
   2. 呼叫 OID_WDI_GET_ADAPTER_CAPABILITIES 以取得配接器的功能。
   3. 呼叫 OID_WDI_SET_ADAPTER_CONFIGURATION 以設定配接器。
   4. 若尚未處於預期狀態，請呼叫 OID_WDI_TASK_SET_RADIO_STATE，以設定初始無線電狀態。
   5. 呼叫 MiniportWdiTalTxRxStart 來設定數據路徑。
   6. 呼叫 OID_WDI_TASK_CREATE_PORT 以建立初始埠。

   其他命令也可以傳送至 IHV 元件，作為 Microsoft 元件的 MiniportInitializeEx 處理的一部分。 不過，在 呼叫 miniportWdiStartOperation 之前，Microsoft元件不會傳送任何需要無線通訊的工作。 除了一律先傳送 OID_WDI_TASK_OPEN 以外，其他命令/呼叫的順序可能會變更。

   使用從 WDI IHV 迷你埠驅動程式取得的數據，Microsoft元件會呼叫 NdisMSetMiniportAttributes，並在 NDIS 上設定 NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES 和 NDIS_MINIPORT_ADAPTER_NATIVE_802_11_ATTRIBUTES。

4. 呼叫 MiniportWdiStartOperation。

   這是 NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 內的選擇性 WDI 迷你埠處理程式，IHV 驅動程式可用來執行任何其他 MiniportInitializeEx 工作。 IHV 迷你埠端也可以將其用作提示，指出 Microsoft 元件已完成對迷你埠的初始化，並且迷你埠端可以啟動任何所需的背景活動。

   下圖顯示 MiniportInitializeEx 的流程。

   

   如果中繼作業失敗，Microsoft元件會復原先前的作業，並讓迷你埠無法啟動。 例如，如果 OID_WDI_TASK_CREATE_PORT 失敗，則會清除數據路徑、傳送 OID_WDI_TASK_CLOSE，而迷你埠會失敗。

MiniportHaltEx

在原生 Wi-Fi 迷你埠中，會使用 MiniportHaltEx，告訴迷你埠停止作業並清除配接器實例。 在 WDI 模型中，Microsoft 元件會處理原始 MiniportHaltEx 呼叫，並將它分割成多個 WDI 介面呼叫。

1. 呼叫 MiniportWdiStopOperation。

   這是 NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 內選擇性的 WDI 迷你埠處理程式，IHV 驅動程式可用來復原它在miniportWdiStartOperation 中執行的作業。

2. 使用 MiniportOidRequest的多個 WDI 命令。

   MiniportWdiStopOperation之後，Microsoft 元件會將工作/屬性傳送至 IHV 迷你埠，以清除 IHV 驅動程式的目前狀態。 此清除作業可能包括下列事項。

   1. 呼叫 OID_WDI_TASK_DISCONNECT/OID_WDI_TASK_STOP_AP 以終止任何現有的連線。
   2. 呼叫 OID_WDI_TASK_DELETE_PORT 以刪除所有已建立的埠。
   3. 呼叫 MiniportWdiTalTxRxStop 以停止數據路徑。
   4. 呼叫 MiniportWdiTalTxRxDeinitialize 來取消初始化數據路徑。
   5. 呼叫 以清除硬體狀態。 此操作會使用已由 IHV 驅動程式註冊的 MiniportWdiCloseAdapter 傳送至 IHV。

3. 呼叫上述所有命令之後，Microsoft元件會呼叫 MiniportWdiFreeAdapter，讓 IHV 驅動程式刪除它可能擁有的任何軟體狀態。

下圖顯示 MiniportHaltEx 的流程。

如果裝置意外移除，或系統正在關閉電源，則不會執行 MiniportHaltEx 處理。 如需意外移除，請參閱 MiniportDevicePnPEventNotify 處理程序行為。 如需系統關機，請參閱 MiniportShutdownEx 處理程序。

MiniportDriverUnload

MiniportDriverUnload 是在卸載 WDI IHV 小型埠之前被呼叫的處理程式。 WDI IHV 迷你埠驅動程式會呼叫 Microsoft 元件以取消自己的註冊。 Microsoft元件會呼叫 NdisMDeregisterMiniportDriver。

下圖顯示 MiniportDriverUnload 的流程。

MiniportPause

NDIS MiniportPause 的需求是由 Microsoft 元件處理。 作為 MiniportPause 的一部分，Microsoft 元件會停止資料的路徑，並等待清除完成。 WDI IHV 迷你埠可以選擇性地註冊MiniportWdiPostAdapterPause 回呼，此回呼會在Microsoft元件完成資料路徑清除之後被呼叫。

下圖顯示 MiniportPause 的流程。

MiniportRestart

NDIS MiniportRestart 的需求由 Microsoft 組件負責處理。 作為 MiniportRestart 的一部分，Microsoft 元件會恢復它在 MiniportPause 階段執行的資料路徑暫停操作。 WDI IHV 迷你埠可以選擇性地註冊 MiniportWdiPostAdapterRestart 回呼，當 Microsoft 元件完成資料路徑重新啟動後即呼叫該回呼。

下圖顯示 MiniportRestart 的流程。

MiniportResetEx

MiniportResetEx 不會由Microsoft元件處理。 WDI IHV 迷你埠可以選擇性地註冊由 Microsoft 元件進行呼叫的 MiniportResetEx 回呼。

MiniportDevicePnPEventNotify

MiniportDevicePnPEventNotify 可用來通知 NDIS 驅動程式 PNP 事件，例如裝置的意外移除。 當 NDIS 傳送此通知時，會先轉送至 WDI IHV 迷你埠進行處理。 IHV 元件完成處理之後，Microsoft元件會針對此事件執行適當的處理。 轉送至 IHV 元件的呼叫不會與其他工作和回呼串行化。

下圖顯示 MiniportDevicePnPEventNotify 的流程。

MiniportShutdownEx

MiniportShutdownEx 可用來通知 NDIS 驅動程式系統關機事件。 當 NDIS 傳送此通知時，會先由Microsoft元件處理。 Microsoft元件完成處理之後，它會將事件傳遞至 WDI IHV 迷你埠進行處理。

下圖顯示 MiniportShutdownEx 的流程。

MiniportOidRequest

MiniportOidRequest 處理程式是 WDI IHV 迷你埠必須實作的必要處理程式。 Microsoft元件會使用它，將 WDI 命令提交至 IHV 迷你埠。 它也會將 Microsoft 組件未處理的 OID 轉送到 IHV 迷你埠。

MiniportOidRequest 將呼叫 WDI IHV miniport 視為 WDI 命令的 M1 訊息。 OID 的完成（無論是透過 NdisMOidRequestComplete，或透過從 MiniportOidRequest傳回非 PENDING）應該視為 WDI 工作/命令的 M3 訊息。

對於每個 WDI 命令，有兩個可能的欄位可以傳回 NDIS_STATUS 狀態碼 -- 一個是來自 MiniportOidRequest 呼叫的狀態碼（或 NdisMOidRequestComplete），另一個是 WDI_MESSAGE_HEADER 欄位中的狀態碼（無論是在 OID 完成時或透過 NdisMIndicateStatusEx）。 Microsoft 元件總是會先查看 OID 完成的 NDIS_STATUS，再查看 WDI_MESSAGE_HEADERStatus 欄位。 關於 WDI OID 處理，IHV 元件的期望如下。

1. WDI OID 會使用 NDIS_OID_REQUESTRequestType 的 NdisRequestMethod提交至 IHV 元件，而對應的訊息和訊息長度則分別位於 DATA.METHOD_INFORMATION.InformationBuffer 和 DATA.METHOD_INFORMATION.InputBufferLength 欄位中。
2. 如果處理命令時發生錯誤，IHV 元件會在 OID 完成中報告錯誤，並在發生 Wi-Fi 層級失敗時，將 WDI_MESSAGE_HEADER 的 [狀態] 字段設定為非成功。
3. 針對工作和屬性，要求的埠號碼位於 [WDI_MESSAGE_HEADERPortId] 欄位中。 NDIS_OID_REQUEST 中的 PortNumber 一律設定為 0。
4. 若要完成 OID，可以接受 MiniportOidRequest 傳回 NDIS_STATUS_PENDING，並可在稍後（同步或非同步地）使用 NdisMOidRequestComplete完成 OID。
5. 如果 IHV 元件以 NDIS_STATUS_SUCCESS 完成處理 OID，則必須將 OID 要求的 BytesWritten 欄位填入適當的位元組數，其中需包括 WDI_MESSAGE_HEADER的空間。
6. 如果 IHV 元件在 DATA.METHOD_INFORMATION.OutputBufferLength 欄位中沒有足夠空間來填滿回應，它會以 NDIS_STATUS_BUFFER_TOO_SHORT 完成 OID，並填入 DATA.METHOD_INFORMATION.BytesNeeded 欄位。 Microsoft元件可能會嘗試配置要求大小的緩衝區，並將新的要求提交至 IHV。
7. 如果是工作，則工作的 M4（NdisMIndicateStatusEx）只有在工作報告為成功啟動時才可以指示——這表示 OID 完成成功，以及在 OID 完成的 WDI_MESSAGE_HEADER 中的 狀態 為成功。

下圖顯示對應至單一 WDI 命令的 NDIS OID 要求範例。 當作業系統提交 OID 請求時，Microsoft 元件會將它轉換成 WDI OID 請求，並將 WDI OID 請求提交至 IHV 微型埠。 當 IHV 小型埠完成 OID 後，Microsoft 元件會適當地完成原始 OID 要求。

如果 OriginalOidRequest 對應至多個 WDI OidRequests 且其中一個 WDI 要求失敗，OriginalOidRequest 也會失敗。 如果中繼作業的子集已經完成，Microsoft元件會嘗試撤銷支援清理的作業。

下方圖表顯示由 Microsoft 元件完成處理的 NDIS OID 要求範例。 當作業系統提交 OID 要求時，Microsoft 元件會處理並完成此 OID。 此 OID 不會傳遞至 WDI IHV 迷你埠。

Microsoft元件無法理解的 OID 會直接轉送至 IHV 元件進行處理。

與原生 Wi-Fi 迷你埠相比，MiniportOidRequest 的行為不會變更 WDI IHV 迷你埠驅動程式。 呼叫會被順序處理，而 IHV 迷你埠可以選擇同步或非同步方式完成，並以呼叫 NdisMOidRequestComplete來執行。

Miniport取消OID請求

這是 WDI IHV 迷你埠使用的選擇性處理程式，需要處理未對應至 WDI 訊息的 OID。 此處理程式不會用於任何 WDI OID。 WDI OID 必須快速完成，而且不需要 IHV 微型端口驅動程式嘗試取消擱置的 OID。 使用適當的取消工作 OID 要求來處理 WDI 工作的取消。 針對未對應的物件識別碼 (OID)，預期的行為是由 NDIS 所定義。

NdisMIndicateStatusEx

WDI IHV 迷你埠會使用 NdisMIndicateStatusEx，將指示傳送至Microsoft元件。 這些指示可能是未經請求的指示，例如 TKIP MIC 失敗，或請求指示完成 （M4） 的工作。

下方圖表顯示一個 WDI 指示的範例，其對應於 NDIS/Native Wi-Fi 指示。 當 IHV 迷你埠將指示提交至 Microsoft 元件時，Microsoft 元件會將其轉換成現有的指示，並將其轉送至作業系統。

下圖顯示沒有對應 NDIS/Native Wi-Fi 指示的 WDI 指示範例。 這是由Microsoft元件處理。

下圖顯示Microsoft元件無法辨識的指示。 指示 as-is 會轉送至作業系統。

對於 WDI IHV 迷你埠驅動程式而言，NdisMIndicateStatusEx 的行為與原生 Wi-Fi 迷你埠相比並無改變。

MiniportDirectOidRequest

如果 WDI IHV 迷你埠驅動程式需要處理未對應至 WDI 訊息的 Direct OID，這是由 WDI IHV 迷你埠驅動程式註冊的選擇性處理程式。 Wi-Fi Direct 的所有現有 Direct OID 都會對應至 WDI 訊息，因此不需要此處理程式才能支援該功能。 不支援的 Direct OID 不會由Microsoft元件串行化。

MiniportCancelDirectOidRequest

這是 WDI IHV 迷你埠使用的選擇性處理程式，需要處理未對應至 WDI 訊息的 Direct OID。 針對未對應的 OID，預期的行為是由 NDIS 所定義。

MiniportSendNetBufferLists

此處理程式不會用於 WDI IHV 迷你埠驅動程式中，而且不應該提供。 Microsoft元件會使用透過 NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 註冊的數據路徑處理程式，將傳送封包提交至 IHV 迷你埠。

MiniportCancelSend

此處理程式不會用於 WDI IHV 迷你埠驅動程式中，而且不應該提供。

MiniportReturnNetBufferLists

此處理程式不會用於 WDI IHV Miniport 驅動程式中，而且不應該提供。 Microsoft元件會使用透過 NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS 註冊的數據路徑處理程式，將接收的封包傳回 IHV 迷你埠。

WDI 處理程式：MiniportWdiOpenAdapter

Microsoft元件會使用 MiniportWdiOpenAdapter 處理程式，在 IHV 驅動程式上起始開啟工作作業。 此呼叫必須快速完成，如果開啟作業已成功啟動，IHV 必須在此呼叫時回傳 NDIS_STATUS_SUCCESS，並呼叫 OpenAdapterComplete 處理常式，該處理常式是作為 MiniportWdiAllocateAdapter的 NDIS_WDI_INIT_PARAMETERS 參數傳遞進來的。

WDI 處理程式：MiniportWdiCloseAdapter

Microsoft 元件會使用 MiniportWdiCloseAdapter 處理程式，在 IHV 驅動程式上起始關閉任務作業。 此呼叫必須快速完成。如果開啟作業已成功啟動，IHV 必須在此呼叫中回傳 NDIS_STATUS_SUCCESS，並且必須呼叫傳遞至 MiniportWdiAllocateAdapter之 NDIS_WDI_INIT_PARAMETERS 參數中的 CloseAdapterComplete 處理程式。