структура NET_PNP_EVENT (netpnp.h)

Статья
08/07/2023

Структура NET_PNP_EVENT описывает событие сетевого Plug and Play (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

Указывает, что диспетчер управления питанием отправил запрос на настройку питания, который указывает переход в состояние питания системы. NDIS преобразует это состояние в соответствующее состояние питания устройства.

Дополнительные сведения см. в разделе «Примечания».

NetEventQueryPower

Указывает, что диспетчер управления питанием отправил запрос на питание запроса, который запрашивает переход в состояние питания системы. NDIS преобразует это состояние в соответствующее состояние питания устройства.

Дополнительные сведения см. в разделе «Примечания».

NetEventQueryRemoveDevice

Указывает, что диспетчер PnP отправил запрос на удаление устройства. Диспетчер PnP отправляет этот запрос, чтобы запросить, можно ли удалить устройство без нарушения работы.

NetEventCancelRemoveDevice

Указывает, что диспетчер PnP отправил запрос отмены удаления устройства. Диспетчер PnP отправляет этот запрос, чтобы отменить удаление устройства после того, как диспетчер PnP отправит запрос на удаление устройства.

NetEventReconfigure

Указывает, что конфигурация для сетевого компонента изменилась. Например, если пользователь с помощью Connections сети и удаленного доступа изменяет IP-адрес tcp/IP, NDIS указывает, что событие NetEventReconfigure будет указано на протокол TCP/IP. Кроме того, промежуточный драйвер обычно использует это событие в качестве триггера для вызова Функция NdisIMInitializeDeviceInstanceEx и запуск виртуальных минипортов. Дополнительные сведения о NetEventReconfigure см. в разделе NetEventIMReEnableDevice.

NetEventBindList

Указывает драйверу протокола, что порядок обработки списка привязок был перенастроен. Этот список указывает относительный порядок, который применяется к привязкам при обработке, например, пользовательского запроса, который может быть перенаправлен на одну из нескольких привязок. Буфер, передаваемый с этим событием, содержит список имен устройств, отформатированных в виде строк Юникода, заканчивающихся null. Формат имени каждого устройства идентичен члену AdapterName , который передается в вызов функции ProtocolBindAdapterEx .

NetEventBindsComplete

Указывает, что драйвер протокола привязывается ко всем сетевым адаптерам, к которым он может привязаться. NDIS не будет указывать больше сетевых адаптеров для протокола, если сетевой адаптер PnP не подключен к системе.

NetEventPnPCapabilities

Указывает, что пользователь включил или отключил возможности пробуждения базового адаптера. (Привязка задается параметром ProtocolBindingContext , который передается функции ProtocolNetPnPEvent .)

NetEventPause

Указывает, что указанная привязка протокола должна перейти в состояние Приостановка. Привязка перейдет в состояние Приостановлено после того, как NDIS завершит все невыполненные запросы на отправку привязки.

NetEventRestart

Указывает, что указанная привязка протокола перешла в состояние Перезапуск. Когда драйвер протокола будет готов к возобновлению операций отправки и получения для привязки, привязка переходит в состояние Выполняется.

NetEventPortActivation

Указывает активацию списка портов, связанных с указанной привязкой.

NetEventPortDeactivation

Указывает на деактивацию списка портов, связанных с указанной привязкой.

NetEventIMReEnableDevice

Указывает, что конфигурация изменилась для виртуального мини-порта промежуточного драйвера NDIS 6.0 или более поздней версии. NetEventIMReEnableDevice похож на событие NetEventReconfigure , за исключением того, что промежуточный драйвер получает это событие для одного виртуального мини-порта, а событие NetEventReconfigure применяется ко всем виртуальным минипортам промежуточного драйвера. Например, промежуточный драйвер получает событие NetEventIMReEnableDevice, когда пользователь отключает, а затем включает один виртуальный мини-порт из диспетчер устройств или другого источника. Примеры управления питанием промежуточных драйверов см. в примерах NDIS MUX Intermediate Driver and Notify Object Driver в репозитории примеров драйверов Windows на сайте GitHub.

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 и должно использоваться с версией 2 или более поздней версией NET_PNP_EVENT. Это событие может быть при необходимости выдано драйвером мини-порта. Протоколы и фильтры не могут получать это событие или выдавать его.

NetEventAllowBindsAbove

Асинхронное событие, которое отменяет эффекты NetEventInhibitBindsAbove. Ниже приведены правила использования.

Это событие может быть выдано только после начала MiniportInitializeEx и не должно выдаваться после возврата MiniportHaltEx .
Это событие может быть выдано только в том случае, если адаптер мини-порта находится в состоянии D0.
Блокировки не должны удерживаться при выдаче этого события.
Это событие должно быть выдано в PASSIVE_LEVEL.

NetEventRequirePause

Синхронное событие, указывающее, что протоколы и фильтры, включая адаптер минипорта, должны быть приостановлены. Протоколы и фильтры, а также адаптер минипорта гарантированно будут приостановлены при возврате подпрограммы NdisMNetPnPEvent . Ниже приведены правила использования.

Избегайте задержки между событиями NetEventAllowStart и NetEventRequirePause дольше 1000 миллисекунд, чтобы предотвратить задержку в пользовательских приложениях.
Это событие может быть выдано только после начала MiniportInitializeEx и не должно выдаваться после возврата MiniportHaltEx .
Нет никакой гарантии, что NDIS вызовет MiniportPause после выдачи этого события. В частности, если адаптер мини-порта уже приостановлен, NDIS не будет вводить дополнительный цикл запуска и приостановки. Это означает, что количество раз вызова MiniportPause не больше, меньше или равно сумме выдачи этого события.
Так как это событие блокируется, оно не должно выдаваться каким-либо контекстом, который может вызвать взаимоблокировку.
Блокировки не должны удерживаться при выполнении этого события.

Это событие доступно начиная с NDIS версии 6.50 и должно использоваться с версией 2 или более поздней версией NET_PNP_EVENT. Это событие при необходимости может быть выдано драйвером мини-порта. Протоколы и фильтры не могут получать это событие или выдавать его.

NetEventAllowStart

Асинхронное событие, указывающее, что протоколы и фильтры, включая адаптер мини-порта, не нужно приостанавливать. Ниже приведены правила использования. После возврата подпрограммы NdisMNetPnPEvent нет гарантированного состояния приостановки для любого драйвера в протоколах и фильтрах.

Это событие может быть выдано только после начала MiniportInitializeEx и не должно выдаваться после возврата MiniportHaltEx .
Так как это событие блокируется, оно не должно выдаваться каким-либо контекстом, который может вызвать взаимоблокировку.
Блокировки не должны удерживаться при выполнении этого события.

Buffer

Адрес буфера, который содержит сведения, относящиеся к событию, указанному в элементе NetEvent . Для каждого типа события буфер содержит следующие сведения:

NetEventSetPower

Буфер содержит состояние питания устройства, в которое переходит устройство.

Когда NDIS вызывает функцию ProtocolNetPnPEvent драйвера протокола, состояние устройства NDIS_DEVICE_POWER_STATE, которое может быть одним из следующих значений:

NdisDeviceStateUnspecified

Сетевое устройство не поддерживает управление питанием.

NdisDeviceStateD0

Состояние с полным питанием, в котором устройство обеспечивает полную функциональность и производительность.

NdisDeviceStateD1

Состояние с низким энергопотреблением, в котором запросы передачи от узла не учитываются устройством, данные, полученные устройством, не передаются в память узла, и прерывания не могут возникать. Некоторые контексты устройства могут быть потеряны. В зависимости от возможностей сетевой карты и драйвера мини-порта устройство может генерировать сигнал пробуждения.

NdisDeviceStateD2

Состояние с низким энергопотреблением, похожее на NdisDeviceStateD1, за исключением того, что обычно экономится больше энергии и меньше контекста, а для перехода в состояние с полным питанием требуется больше времени.

NdisDeviceStateD3

Состояние выключения, в котором питание полностью отключено от устройства.

Для драйверов протоколов NdisDeviceStateD0 означает, что сетевой адаптер полностью питается и доступен для нормальной работы. Любое другое состояние устройства означает, что устройство не полностью питается и недоступно для отправки и получения сетевых данных.

NetEventQueryPower

Буфер содержит состояние питания устройства, запрошенное для устройства. Состояние устройства NDIS_DEVICE_POWER_STATE (описано в описании значения NetEventSetPower ).

NetEventQueryRemoveDevice

Содержимое буфера равно NULL.

NetEventCancelRemoveDevice

Содержимое буфера равно NULL.

NetEventReconfigure

Буфер может содержать данные, относящиеся к протоколу. Драйвер протокола отвечает за проверку этих данных.

NetEventBindList

Буфер содержит измененный список привязок для сетевого компонента, который NET_PNP_EVENT_NOTIFICATION передается структура. Список привязок, представляющий собой последовательность строк Юникода, завершаемых null, имеет REG_MULTI_SZ формат. Каждая из строк является именем адаптера. Клиенты TDI, привязанные к протоколу, используют этот список привязок для изменения порядка привязок. Драйвер протокола отвечает за проверку этого списка.

NetEventBindsComplete

Содержимое буфера равно NULL.

NetEventPnPCapabilities

Буфер — это ULONG, содержащий битовую маску. Если в битовой маске установлен флаг NDIS_DEVICE_WAKE_UP_ENABLE, активируются возможности пробуждения сетевой карты. В противном случае возможности пробуждения сетевого адаптера будут отключены. (Привязка задается параметром ProtocolBindingContext , который передается в ProtocolNetPnPEvent.) Если задано значение 0, этот флаг указывает, что возможности пробуждения сетевой карты отключены.

NetEventPause

Буфер содержит NDIS_PROTOCOL_PAUSE_PARAMETERS структура.

NetEventRestart

Буфер может содержать значение NULL или NDIS_PROTOCOL_RESTART_PARAMETERS структура. NDIS предоставляет указатель на структуру NDIS_RESTART_ATTRIBUTES в элементе RestartAttributes структуры NDIS_PROTOCOL_RESTART_PARAMETERS.

Примечание Если буфер имеет значение NULL, атрибуты перезапуска не изменились с момента предыдущего перезапуска.

NetEventPortActivation

Буфер содержит первую запись в списке NDIS_PORT структур, определяющих порты, которые будет активировать NDIS. Чтобы получить следующую структуру в списке, можно использовать следующий элемент структуры NDIS_PORT.

NetEventPortDeactivation

Буфер содержит массив номеров портов типа NDIS_PORT_NUMBER (определяемых как ULONG), которые определяют порты NDIS, которые будут отключены NDIS. Чтобы вычислить количество элементов в массиве, разделите значение элемента BufferLength , который находится в структуре NET_PNP_EVENT , указанной в элементе NetPnPEventNET_PNP_EVENT_NOTIFICATION, на sizeof(NDIS_PORT_NUMBER).

NetEventIMReEnableDevice

Буфер содержит указатель на переменную типа NDIS_STRING, содержащую строку Юникода, завершающуюся null, которая называет объект устройства виртуального мини-порта для включаемого устройства. Строка представляет собой полное имя пути, например \Device\DeviceName.

NetEventNDKEnable

Элемент Буфера имеет значение NULL.

NetEventNDKDisable

Элемент Буфера имеет значение NULL.

NetEventFilterPreDetach

Элемент Буфера имеет значение NULL.

NetEventBindFailed

Буфер содержит структуру NDIS_BIND_FAILED_NOTIFICATION .

NetEventSwitchActivate

Содержимое буфера равно NULL.

NetEventAllowBindsAbove

Содержимое буфера равно NULL.

NetEventInhibitBindsAbove

Содержимое буфера равно NULL.

NetEventAllowStart

Содержимое буфера равно NULL.

NetEventRequirePause

Содержимое буфера равно NULL.

BufferLength

Количество байтов сведений о событиях в буфере.

NdisReserved[4]

Область, зарезервированная для использования NDIS.

TransportReserved[4]

Область, зарезервированная для использования водителем транспорта.

TdiReserved[4]

Область, зарезервированная для использования TDI.

TdiClientReserved[4]

Область, зарезервированная для использования клиентом TDI.

В NDIS 6.0 и более поздних версиях, когда операционная система выдает системное событие PnP или событие управления питанием целевому объекту устройства, представляющего адаптер мини-порта, NDIS преобразует событие в структура NET_PNP_EVENT_NOTIFICATION . Элемент NetPnPEvent структуры NET_PNP_EVENT_NOTIFICATION является NET_PNP_EVENT структурой.

NDIS передает указатель на структуру NET_PNP_EVENT для каждого драйвера протокола, привязанного к адаптеру мини-порта, путем вызова функции ProtocolNetPnPEvent драйвера протокола. Драйвер протокола должен сохранить этот указатель, так как указатель является входным параметром для функции NdisCompleteNetPnPEvent , которую драйвер вызывает для асинхронного завершения вызова ProtocolNetPnPEvent .

NDIS передает указатель на структуру NET_PNP_EVENT для каждого драйвера фильтра, привязанного к адаптеру мини-порта, путем вызова функции FilterNetPnPEvent драйвера фильтра. Драйверу фильтра не нужно сохранять этот указатель, так как драйвер должен завершить вызов FilterNetPnPEvent синхронно.

Начиная с NDIS 6.30, драйвер протокола или фильтра должен следовать этим рекомендациям при вызове NDIS функций ProtocolNetPnPEvent или FilterNetPnPEvent :

Если для элемента NetEventструктуры NET_PNP_EVENT задано значение NetEventSetPower, драйвер должен прекратить создание новых запросов ввода-вывода. Кроме того, драйвер не должен ждать завершения любых ожидающих запросов ввода-вывода.
После возврата драйвера протокола или фильтра из ProtocolNetPnPEvent или FilterNetPnPEvent NDIS не будет приостанавливать и перезапускать эти драйверы во время перехода состояния питания, если выполняются следующие условия:
- Базовый драйвер мини-порта устанавливает флаг NDIS_MINIPORT_ATTRIBUTES_NO_PAUSE_ON_SUSPEND в структуре NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES . Драйвер передает указатель на эту структуру в вызове функции NdisMSetMiniportAttributes .
- Все драйверы фильтров, подключенные к драйверу мини-порта, поддерживают NDIS 6.30 или более поздние версии NDIS.
- Все драйверы протокола, привязанные к драйверу мини-порта, поддерживают NDIS 6.30 или более поздние версии NDIS.
Если для элемента NetEventструктуры NET_PNP_EVENT задано значение NetEventSetPower или NetEventQueryPower, драйвер не должен ждать завершения любых ожидающих запросов ввода-вывода.

Элемент NetEvent в структуре NET_PNP_EVENT определяет тип события Plug and Play или управления питанием. Буфер содержит сведения, относящиеся к типу события.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в NDIS 5.1 и NDIS 6.0 и более поздних версиях. Дополнительные сведения о версии NDIS 5.1 этой структуры см. в разделе NET_PNP_EVENT (NDIS 5.1).
Верхняя часть	netpnp.h (включая Ndis.h, Netpnp.h)