PROTOCOL_NET_PNP_EVENT回呼函式 (ndis.h)

發行項
02/26/2024

NDIS 會呼叫 ProtocolNetPnPEvent 函式，向通訊協定驅動程式指出網路隨插即用事件、NDIS PnP 事件或電源管理事件。

注意您必須使用 PROTOCOL_NET_PNP_EVENT 類型來宣告函式。如需詳細資訊，請參閱下列範例一節。

語法

PROTOCOL_NET_PNP_EVENT ProtocolNetPnpEvent;

NDIS_STATUS ProtocolNetPnpEvent(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_PNP_EVENT_NOTIFICATION NetPnPEventNotification
)
{...}

參數

[in] ProtocolBindingContext

通訊協定驅動程式配置內容區域的句柄，此驅動程式會維護每個系結運行時間狀態資訊。通訊協定驅動程式在呼叫 NdisOpenAdapterEx 函式時提供了此句柄。以 NULLProtocolBindingContext 表示的 NetEventXxx 事件適用於所有系結。 NetEventBindList 和 NetEventBindsComplete 一律會以 NULLProtocolBindingContext 表示。 NetEventReconfigure 可以使用指定的 ProtocolBindingContext 或 NULLProtocolBindingContext 來表示。

[in] NetPnPEventNotification

的指標 NET_PNP_EVENT_NOTIFICATION結構，描述 NDIS 指出給通訊協定驅動程式的隨插即用事件或電源管理事件。

傳回值

ProtocolNetPnPEvent 可以傳回下列任一項：

傳回碼	Description
NDIS_STATUS_SUCCESS	通訊協定驅動程式已成功處理指定的網路隨插即用事件、NDIS PnP 事件或電源管理事件。此狀態代碼的意義取決於緩衝中的 NetEvent 程式代碼netPnPEvent 的NET_PNP_EVENT_NOTIFICATION結構： NetEventSetPower 通訊協定驅動程式已執行任何必要的驅動程式特定動作，以準備裝置轉換為要求的裝置電源狀態。 NetEventQueryPower 基礎適配卡可以轉換為要求的裝置電源狀態。 NetEventQueryRemoveDevice 您可以移除基礎配接器。 NetEventCancelRemoveDevice 通訊協定驅動程式已執行任何必要的驅動程式特定動作，以準備取消移除基礎適配卡。 NetEventReconfigure 通訊協定驅動程式已接受已變更的組態。 NetEventBindList 通訊協定驅動程式具有新的系結清單，並已執行相關的處理。 NetEventBindsComplete 通訊協定驅動程式已認可 NDIS 指出通訊協定驅動程式系結至所有可用的基礎適配卡。 NetEventPnPCapabilities 通訊協定驅動程式已確認它已收到與指定系結相關聯之基礎適配卡的目前喚醒功能。 NetEventPause 指定的通訊協議系結已進入暫停狀態。系結會在 NDIS 完成系結的所有未處理傳送要求之後進入暫停狀態。如需暫停作業的詳細資訊，請參閱暫停系結。 NetEventRestart 指定的通訊協議系結已進入重新啟動狀態。當通訊協定驅動程式準備好繼續傳送和接收系結的作業之後，系結就會進入執行中狀態。 NetEventPortActivation 通訊協定驅動程式已認可與指定系結相關聯的埠啟用。如需埠啟用的詳細資訊，請參閱啟用 NDIS 埠。 NetEventPortDeactivation 通訊協定驅動程式已認可與指定系結相關聯的埠啟用。
NDIS_STATUS_PENDING	通訊協定驅動程式會使用對的呼叫，以異步方式傳回對指示事件的回應 NdisCompleteNetPnPEvent 函式。
NDIS_STATUS_RESOURCES	通訊協定驅動程式無法取得必要的系統資源，以滿足指定的隨插即用或電源管理事件。
NDIS_STATUS_NOT_SUPPORTED	NDIS 6.0 和更新版本的通訊協定驅動程式不得傳回此狀態。 NDIS 5。不支援隨插即用的 x 通訊協定驅動程式可以傳回此狀態以回應 NetEventSetPower，以指出 NDIS 應該從基礎適配卡解除系結。
NDIS_STATUS_FAILURE	通訊協定驅動程序因為上述清單中所述的原因而失敗指示的事件。

通訊協議驅動程式可能會使 NetEventQueryRemoveDevice 和 NetEventPortActivation 事件失敗。

如果通訊協定驅動程式失敗 NetEventPortActivation 事件，則不應該在後續作業中使用任何相關聯的埠。

通訊協定驅動程式應該一律成功 NetEventRestart、NetEventIMReEnableDevice、NetEventCancelRemoveDevice、NetEventReconfigure、NetEventBindList、NetEventBindsComplete、NetEventPause、NetEventPortDeactivation 和 NetEventPnPCapabilities 事件，方法是傳回NDIS_STATUS_SUCCESS。

備註

通訊協議驅動程式需要 ProtocolNetPnPEvent 函式，才能支援隨插即用和電源管理。 NDIS 會呼叫 ProtocolNetPnPEvent 來通知通訊協定驅動程式網路隨插即用事件、NDIS PnP 事件或電源管理事件已發生。

The NET_PNP_EVENT_NOTIFICATION 傳遞至 ProtocolNetPnPEvent 的結構會描述事件。 ProtocolNetPnPEvent 會解譯NET_PNP_EVENT_NOTIFICATION結構中的兩個基本資訊：

NetEvent 成員中的程式代碼，可識別隨插即用或 Power Management 事件的類型。
事件特定資訊。例如，使用 NetEventSetPower 事件， Buffer 成員會包含裝置正在轉換的裝置電源狀態。

通訊協定驅動程式應該儲存 NetPnPEvent 指標。此指標是 NdisCompleteNetPnPEvent 函式的必要輸入參數，如果 ProtocolNetPnPEvent 傳回NDIS_STATUS_PENDING，通訊協定驅動程式就必須接著呼叫此參數。

通訊協定驅動程序應該一律會成功 NetEventQueryPower 事件。建立作用中聯機之後，通訊協定驅動程式可以呼叫 PoRegisterSystemState 函式來註冊持續忙碌狀態。只要狀態註冊生效，電源管理員就不會嘗試讓系統進入睡眠狀態。聯機變成非使用中之後，通訊協定驅動程式會藉由呼叫 PoUnregisterSystemState 函式來取消狀態註冊。通訊協議驅動程式不應該嘗試防止系統因為 失敗 NetEventQueryPower 事件而轉換至睡眠狀態。請注意 ，NetEventQueryPower 事件一律接著 NetEventSetPower 事件。 NetEventSetPower 事件，指定基礎裝置目前作用中的電源狀態會取消 NetEventQueryPower 事件。

例如，如果通訊協定驅動程式無法釋放裝置 (，因為裝置正在使用中) 它必須藉由傳回NDIS_STATUS_FAILURE來失敗 NetEventQueryRemoveDevice 事件。

通訊協議驅動程式應該一律成功 NetEventCancelRemoveDevice、NetEventReconfigure、NetEventBindList、NetEventBindsComplete、NetEventPnPCapabilities、NetEventPause 或 NetEventPortDeactivation，方法是傳回NDIS_STATUS_SUCCESS。

處理 NetEventReconfigure 或 NetEventBindList 時，通訊協定驅動程式應該驗證與事件相關聯的數據。如需這類數據的詳細資訊，請參閱 NET_PNP_EVENT_NOTIFICATION。

NDIS 會在 IRQL = PASSIVE_LEVEL呼叫 ProtocolNetPnPEvent 。

例子

若要定義 ProtocolNetPnPEvent 函式，您必須先提供函式宣告來識別您要定義的函式類型。 Windows 提供一組驅動程式的函式類型。使用函式類型宣告函式有助於驅動程式的程式代碼分析、靜態驅動程式驗證程式 (SDV) ，以及其他驗證工具尋找錯誤，而且是撰寫 Windows 作業系統驅動程式的需求。

例如，若要定義名為「 MyNetPnPEvent」的 ProtocolNetPnPEvent 函式，請使用 PROTOCOL_NET_PNP_EVENT 類型，如下列程式代碼範例所示：

PROTOCOL_NET_PNP_EVENT MyNetPnPEvent;

然後，實作您的函式，如下所示：

_Use_decl_annotations_
NDIS_STATUS
 MyNetPnPEvent(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_PNP_EVENT_NOTIFICATION  NetPnPEvent
    )
  {...}

PROTOCOL_NET_PNP_EVENT函式類型定義於 Ndis.h 頭檔中。若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 Use_decl_annotations 批註新增至函式定義。 Use_decl_annotations批註可確保使用頭檔中套用至PROTOCOL_NET_PNP_EVENT函式類型的註釋。如需函數宣告需求的詳細資訊，請參閱使用 NDIS 驅動程式的函式角色類型來宣告函式。

如需 Use_decl_annotations的詳細資訊，請參閱標註函式行為。