структура NET_PNP_EVENT (netpnp.h)
Структура 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.
NetEventAllowBindsAbove
Асинхронное событие, которое отменяет эффекты NetEventInhibitBindsAbove. Ниже приведены правила использования.
- Это событие может быть выдано только после начала MiniportInitializeEx и не должно выдаваться после возврата MiniportHaltEx .
- Это событие может быть выдано только в том случае, если адаптер мини-порта находится в состоянии D0.
- Блокировки не должны удерживаться при выдаче этого события.
- Это событие должно быть выдано в PASSIVE_LEVEL.
NetEventRequirePause
Синхронное событие, указывающее, что протоколы и фильтры, включая адаптер минипорта, должны быть приостановлены. Протоколы и фильтры, а также адаптер минипорта гарантированно будут приостановлены при возврате подпрограммы NdisMNetPnPEvent . Ниже приведены правила использования.
- Избегайте задержки между событиями NetEventAllowStart и NetEventRequirePause дольше 1000 миллисекунд, чтобы предотвратить задержку в пользовательских приложениях.
- Это событие может быть выдано только после начала MiniportInitializeEx и не должно выдаваться после возврата MiniportHaltEx .
- Нет никакой гарантии, что NDIS вызовет MiniportPause после выдачи этого события. В частности, если адаптер мини-порта уже приостановлен, NDIS не будет вводить дополнительный цикл запуска и приостановки. Это означает, что количество раз вызова MiniportPause не больше, меньше или равно сумме выдачи этого события.
- Так как это событие блокируется, оно не должно выдаваться каким-либо контекстом, который может вызвать взаимоблокировку.
- Блокировки не должны удерживаться при выполнении этого события.
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.
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, драйвер не должен ждать завершения любых ожидающих запросов ввода-вывода.
Требования
Требование | Значение |
---|---|
Минимальная версия клиента | Поддерживается в NDIS 5.1 и NDIS 6.0 и более поздних версиях. Дополнительные сведения о версии NDIS 5.1 этой структуры см. в разделе NET_PNP_EVENT (NDIS 5.1). |
Верхняя часть | netpnp.h (включая Ndis.h, Netpnp.h) |