NET_PNP_EVENT 結構 (netpnp.h)

  • 發行項

NET_PNP_EVENT 結構描述網路 隨插即用 (PnP) 事件、NDIS PnP 事件或電源管理事件。

語法

typedef struct _NET_PNP_EVENT {
  NET_PNP_EVENT_CODE NetEvent;
  PVOID              Buffer;
  ULONG              BufferLength;
  ULONG_PTR          NdisReserved[4];
  ULONG_PTR          TransportReserved[4];
  ULONG_PTR          TdiReserved[4];
  ULONG_PTR          TdiClientReserved[4];
} NET_PNP_EVENT, *PNET_PNP_EVENT;

成員

NetEvent

將事件描述為下列其中一項的事件程式代碼：

NetEventSetPower

表示電源管理員已傳送 Set Power 要求，指定轉換至系統電源狀態。 NDIS 會將此狀態轉譯為裝置的適當裝置電源狀態。

如需詳細資訊，請參閱＜備註＞一節。

NetEventQueryPower

表示電源管理員已傳送查詢電源要求，要求轉換至系統電源狀態。 NDIS 會將此狀態轉譯為裝置的適當裝置電源狀態。

如需詳細資訊，請參閱＜備註＞一節。

NetEventQueryRemoveDevice

指出 PnP 管理員已傳送查詢移除裝置要求。 PnP 管理員會傳送此要求，以查詢是否可以移除裝置，而不需要中斷作業。

NetEventCancelRemoveDevice

指出 PnP 管理員已傳送取消移除裝置要求。 PnP 管理員會在 PnP 管理員傳送查詢移除裝置要求之後，傳送此要求來取消移除裝置。

NetEventReconfigure

指出網路元件的元件的元件已變更。 例如，如果使用者透過 Network 和 Dial-up Connections 資料夾變更 TCP/IP 的 IP 位址，NDIS 會指出 NetEventReconfigure 事件為 TCP/IP 通訊協定。 此外，中繼驅動程式通常會使用此事件作為呼叫 的觸發程式 NdisIMInitializeDeviceInstanceEx 函式並啟動其虛擬迷你埠。 如需 NetEventReconfigure 的詳細資訊，請參閱 NetEventIMReEnableDevice。

NetEventBindList

表示通訊協定驅動程式已重新設定其系結清單處理順序。 此清單指出在處理時套用至系結的相對順序，例如，可能會路由傳送至數個系結之一的使用者要求。 以這個事件傳遞的緩衝區包含格式化為 Null 終止 Unicode 字串的裝置名稱清單。 每個裝置名稱的格式都與傳遞至 ProtocolBindAdapterEx 函式呼叫的 AdapterName 成員相同。

NetEventBindsComplete

表示通訊協定驅動程式已系結至其可系結的所有 NIC。 除非將 PnP NIC 插入系統，否則 NDIS 不會向通訊協定指出任何其他 NIC。

NetEventPnPCapabilities

表示使用者已啟用或停用基礎配接器的喚醒功能。 (系結是由傳遞至 ProtocolNetPnPEvent 函式的 ProtocolBindingContext 參數所指定。)

NetEventPause

指出指定的通訊協議系結應該進入暫停狀態。 系結會在 NDIS 完成系結的所有未完成傳送要求之後，進入暫停狀態。

NetEventRestart

表示指定的通訊協議系結已進入重新啟動狀態。 通訊協定驅動程式準備好繼續傳送和接收系結的作業之後，系結就會進入執行中狀態。

NetEventPortActivation

指出與指定系結相關聯的埠清單啟用。

NetEventPortDeactivation

指出與指定系結相關聯的埠清單停用。

NetEventIMReEnableDevice

指出 NDIS 6.0 或更新版本的中繼驅動程式虛擬迷你埠的組態已變更。 NetEventIMReEnableDevice 類似於 NetEventReconfigure 事件，但中繼驅動程式會接收單一虛擬迷你埠的這個事件， 而 NetEventReconfigure 事件則適用於所有中繼驅動程式的虛擬迷你埠。 例如，中繼驅動程式會在使用者停用時收到 NetEventIMReEnableDevice 事件，然後從 裝置管理員 或其他來源啟用單一虛擬迷你埠。 如需中繼驅動程式電源管理的範例，請參閱 GitHub 上 Windows 驅動程式範例存放庫中提供的 NDIS MUX 中繼驅動程式和通知物件驅動程式範例。

NetEventNDKEnable

表示目前已啟用網路直接核心 (NDK) 。

NetEventNDKDisable

表示目前已停用 NDK。

NetEventFilterPreDetach

表示篩選即將中斷連結，因此篩選條件可以執行 FilterDetach 處理程式中無法執行的任何必要清除 (，因為該時間會關閉 OID 和指示路徑) 。

NetEventBindFailed

表示已發生系結事件失敗。

NetEventSwitchActivate

表示 Hyper-V 可延伸交換器已完成啟用，而且交換器延伸模組現在可以安全地查詢進一步的交換器設定。 指示只會用於擴充功能迷你埠所發出的 Hyper-V 可延伸交換器堆疊中。 如需詳細資訊 ，請參閱查詢 Hyper-V 可延伸交換器組態 和 NDIS_SWITCH_PARAMETERS 。

NetEventInhibitBindsAbove

同步事件，可防止其他篩選和通訊協定系結至迷你埠配接器。 先前系結的任何篩選或通訊協議都會在事件完成之前解除系結。 使用規則如下。

  • 請避免讓迷你埠配接器處於禁止狀態，超過 1000 毫秒。
  • 此事件只能在 MiniportInitializeEx 開始之後發出，而且不得在 MiniportHaltEx傳 回之後發出。
  • 只有在迷你埠配接器處於 D0 狀態時，才能發出此事件。
  • 因為此事件遭到封鎖，所以不應該由任何會導致死結的內容發出。
  • 發出此事件時，不得保留鎖定。
  • 此事件必須在PASSIVE_LEVEL發出。
從 NDIS 6.50 版開始，此事件可從 NDIS 6.50 版開始使用，且必須搭配 V2 或更新版本的 NET_PNP_EVENT使用。 此事件可選擇性地由迷你埠驅動程序發出。 通訊協議和篩選無法接收此事件或發出它。

NetEventAllowBindsAbove

反轉 NetEventInhibitBindsAbove 效果的異步事件。 使用規則如下。

  • 此事件只能在 MiniportInitializeEx 開始之後發出，而且不得在 MiniportHaltEx傳 回之後發出。
  • 只有在迷你埠配接器處於 D0 狀態時，才能發出此事件。
  • 發出此事件時，不得保留鎖定。
  • 此事件必須在PASSIVE_LEVEL發出。
從 NDIS 6.50 版開始，此事件可從 NDIS 6.50 版開始使用，且必須搭配 V2 或更新版本的 NET_PNP_EVENT使用。 此事件可選擇性地由迷你埠驅動程序發出。 通訊協議和篩選無法接收此事件或發出它。

NetEventRequirePause

指出通訊協議和篩選條件的同步事件，包括迷你埠配接器必須暫停。 當 NdisMNetPnPEvent 例程傳回時，保證會暫停通訊協議和篩選和迷你埠配接器。 使用規則如下。

  • 避免在 NetEventAllowStart 和 NetEventRequirePause 事件之間延遲超過 1000 毫秒，以避免在使用者應用程式中延遲。
  • 此事件只能在 MiniportInitializeEx 開始之後發出，而且不得在 MiniportHaltEx傳 回之後發出。
  • 無法保證 NDIS 會在發出此事件之後呼叫 MiniportPause 。 特別是，如果您的迷你埠配接器已暫停，NDIS 將不會引進額外的啟動暫停迴圈。 這表示所呼叫 MiniportPause 的次數不大於、小於或等於發出此事件的數量。
  • 因為此事件遭到封鎖，所以不應該由任何會導致死結的內容發出。
  • 發出此事件時，不得保留鎖定。
此事件從 NDIS 6.50 版開始可供使用，且必須搭配 V2 或更新版本的 NET_PNP_EVENT 使用。 迷你埠驅動程式可以選擇性地發出此事件。 通訊協議和篩選器無法接收此事件或發出此事件。

NetEventAllowStart

異步事件，指出包含迷你埠配接器的通訊協議和篩選不需要暫停。 使用規則如下。 在 NdisMNetPnPEvent 例程傳回之後，通訊協議和篩選中的任何驅動程式都無法保證暫停狀態。

  • 此事件只能在 MiniportInitializeEx 開始之後發出，而且不得在 MiniportHaltEx 傳回之後發出。
  • 由於此事件遭到封鎖，因此不應由任何會導致死結的內容發出。
  • 發出此事件時，不得保留鎖定。
此事件從 NDIS 6.50 版開始可供使用，且必須搭配 V2 或更新版本的 NET_PNP_EVENT 使用。 迷你埠驅動程式可以選擇性地發出此事件。 通訊協議和篩選器無法接收此事件或發出此事件。

Buffer

緩衝區的位址，其中包含 NetEvent 成員中所指出事件特有的資訊。 針對每種事件類型，緩衝區包含下列資訊：

NetEventSetPower

緩衝區包含裝置正在轉換的裝置電源狀態。

當 NDIS 呼叫通訊協定驅動程式的 ProtocolNetPnPEvent 函式時，裝置狀態會NDIS_DEVICE_POWER_STATE，可以是下列其中一個值：

NdisDeviceStateUnspecified

網路裝置不支援電源管理。

NdisDeviceStateD0

裝置提供完整功能和效能的完整電源狀態。

NdisDeviceStateD1

低電源狀態，裝置不會接受來自主機的要求，裝置收到的數據不會傳輸至主機記憶體，而且不會發生中斷。 某些裝置內容可能會遺失。 根據 NIC 及其迷你埠驅動程式的功能，裝置可能會產生喚醒訊號。

NdisDeviceStateD2

類似於 NdisDeviceStateD1 的低電源狀態，不同之處在於通常省下更多電源和較少內容，而且需要更多時間才能轉換至完整電源狀態。

NdisDeviceStateD3

關閉狀態，其中已從裝置完全移除電源。

針對通訊協定驅動程式， NdisDeviceStateD0 表示 NIC 完全提供電源，並可用於正常作業。 任何其他裝置狀態都表示裝置未完全提供電源，而且無法傳送和接收網路數據。

NetEventQueryPower

緩衝區包含針對裝置要求的裝置電源狀態。 裝置狀態NDIS_DEVICE_POWER_STATE (，如 NetEventSetPower 值描述) 所述。

NetEventQueryRemoveDevice

緩衝區內容為 NULL。

NetEventCancelRemoveDevice

緩衝區內容為 NULL。

NetEventReconfigure

緩衝區可以包含通訊協定特定的數據。 通訊協定驅動程式負責驗證此數據。

NetEventBindList

緩衝區包含網路元件的修訂系結清單， NET_PNP_EVENT_NOTIFICATION 結構正在傳遞至 。 系結清單是一系列以 Null 終止的 Unicode 字串，具有REG_MULTI_SZ格式。 每個字串都是配接器名稱。 系結至通訊協定的 TDI 用戶端會使用此系結清單來重新排序其系結。 通訊協定驅動程式負責驗證此清單。

NetEventBindsComplete

緩衝區內容為 NULL。

NetEventPnPCapabilities

緩衝區是包含位掩碼的 ULONG。 在位掩碼中設定NDIS_DEVICE_WAKE_UP_ENABLE旗標時，會啟用 NIC 的喚醒功能。 否則，會停用 NIC 的喚醒功能。 (系結是由傳遞至 ProtocolNetPnPEvent.) 的 ProtocolBindingContext 參數所指定。當設定為零時，此旗標表示已停用 NIC 的喚醒功能。

NetEventPause

緩衝區包含 NDIS_PROTOCOL_PAUSE_PARAMETERS 結構。

NetEventRestart

緩衝區可能包含 NULL 或 NDIS_PROTOCOL_RESTART_PARAMETERS 結構。 NDIS 會在 NDIS_PROTOCOL_RESTART_PARAMETERS 結構的 RestartAttributes 成員中，提供NDIS_RESTART_ATTRIBUTES結構的指標。

注意 如果緩衝區為 NULL，則重新啟動屬性在上一次重新啟動之後尚未變更。
 

NetEventPortActivation

緩衝區包含 NDIS_PORT 結構清單中的第一個專案，可識別 NDIS 將啟動的埠。 您可以使用 NDIS_PORT 結構的 Next 成員來取得清單中的下一個結構。

NetEventPortDeactivation

緩衝區包含埠號碼數位，其類型NDIS_PORT_NUMBER (定义为 ULONG) ，可識別 NDIS 將停用的 NDIS 埠。 若要計算數位中的元素數目，請將 BufferLength 成員的值除以 sizeof (NDIS_PORT_NUMBER) 指定於 NET_PNP_EVENT_NOTIFICATIONnetPnPEvent 成員的 NET_PNP_EVENT 結構中。

NetEventIMReEnableDevice

緩衝區包含類型為 NDIS_STRING 變數的指標，其中包含以 Null 終止的 Unicode 字串，為已啟用之裝置命名虛擬迷你埠的裝置物件。 字串是完整路徑名稱，例如 \Device\DeviceName。

NetEventNDKEnable

Buffer 成員為 NULL。

NetEventNDKDisable

Buffer 成員為 NULL。

NetEventFilterPreDetach

Buffer 成員為 NULL。

NetEventBindFailed

緩衝區包含 NDIS_BIND_FAILED_NOTIFICATION 結構。

NetEventSwitchActivate

緩衝區內容為 NULL。

NetEventAllowBindsAbove

緩衝區內容為 NULL。

NetEventInhibitBindsAbove

緩衝區內容為 NULL。

NetEventAllowStart

緩衝區內容為 NULL。

NetEventRequirePause

緩衝區內容為 NULL。

BufferLength

Buffer 上事件特定資訊的位元元數目。

NdisReserved[4]

保留供 NDIS 使用的區域。

TransportReserved[4]

保留供傳輸驅動程式使用的區域。

TdiReserved[4]

保留給 TDI 使用的區域。

TdiClientReserved[4]

保留給 TDI 用戶端使用的區域。

備註

在 NDIS 6.0 和更新版本中，當操作系統發出系統 PnP 事件或電源管理事件給代表迷你埠適配卡的目標裝置物件時，NDIS 會將事件轉譯成 NET_PNP_EVENT_NOTIFICATION 結構。 NET_PNP_EVENT_NOTIFICATION 結構的 NetPnPEvent 成員是NET_PNP_EVENT結構。

NDIS 會藉由呼叫通訊協定驅動程式的 ProtocolNetPnPEvent 函式，將指標傳遞給系結至迷你埠配接器的每個通訊協定驅動程式NET_PNP_EVENT結構。 通訊協定驅動程式應該儲存此指標，因為指標是 NdisCompleteNetPnPEvent 函式的輸入參數，驅動程式會呼叫此函式以異步方式完成 ProtocolNetPnPEvent 呼叫。

NDIS 會藉由呼叫篩選驅動程式的 FilterNetPnPEvent 函式，將指標傳遞給每個系結至迷你埠配接器的篩選驅動程式NET_PNP_EVENT結構。 篩選驅動程式不需要儲存此指標，因為驅動程式必須同步完成 FilterNetPnPEvent 呼叫。

從 NDIS 6.30 開始，當 NDIS 呼叫 ProtocolNetPnPEvent 或 FilterNetPnPEvent 函式時，通訊協定或篩選驅動程式必須遵循下列指導方針：

  • 如果NET_PNP_EVENT結構的 NetEvent 成員設定為 NetEventSetPower，驅動程式必須停止產生新的 I/O 要求。 此外，驅動程式不得等候完成任何擱置的 I/O 要求。

    當通訊協定或篩選驅動程式從 ProtocolNetPnPEvent 或 FilterNetPnPEvent 傳回之後，如果下列條件成立，NDIS 將不會暫停並重新啟動這些驅動程式：

    • 基礎迷你埠驅動程式會在 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 結構中設定 NDIS_MINIPORT_ATTRIBUTES_NO_PAUSE_ON_SUSPEND 旗標。 驅動程式會在其對 NdisMSetMiniportAttributes 函式的呼叫中傳遞這個結構的指標。
    • 附加至迷你埠驅動程式的所有篩選驅動程式都支援 NDIS 6.30 或更新版本的 NDIS。
    • 系結至迷你埠驅動程式的所有通訊協定驅動程式都支援 NDIS 6.30 或更新版本的 NDIS。
  • 如果NET_PNP_EVENT結構的 NetEvent 成員設定為 NetEventSetPower 或 NetEventQueryPower，驅動程式不得等候任何擱置的 I/O 要求完成。
NET_PNP_EVENT 結構中的 NetEvent 成員會識別 隨插即用 或電源管理事件的類型。 Buffer 包含事件類型特有的資訊。

規格需求

需求 值
最低支援的用戶端 NDIS 5.1 和 NDIS 6.0 和更新版本支援。 如需此結構的 NDIS 5.1 版本詳細資訊，請參閱 NET_PNP_EVENT (NDIS 5.1) 。
標頭 netpnp.h (包括 Ndis.h、Netpnp.h)

另請參閱

FilterNetPnPEvent

NDIS_BIND_FAILED_NOTIFICATION

NDIS_PORT

NDIS_PROTOCOL_PAUSE_PARAMETERS NDIS_PROTOCOL_RESTART_PARAMETERS

NDIS_RESTART_ATTRIBUTES

NDIS_SWITCH_PARAMETERS

NET_PNP_EVENT_NOTIFICATION

NdisCompleteNetPnPEvent

NdisIMInitializeDeviceInstanceEx

ProtocolBindAdapterEx

ProtocolNetPnPEvent

查詢 Hyper-V 可延伸交換器設定