функция обратного вызова PROTOCOL_NET_PNP_EVENT (ndis.h)

Статья
08/07/2023

NDIS вызывает функцию ProtocolNetPnPEvent, чтобы указать сетевое событие Plug and Play, событие 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 . Событие NetEventXxx, обозначенное с помощью null ProtocolBindingContext, применяется ко всем привязкам. NetEventBindList и NetEventBindsComplete всегда указываются со значением NULLProtocolBindingContext. NetEventReconfigure можно указать с помощью указанного protocolBindingContext или nullProtocolBindingContext.

[in] NetPnPEventNotification

Указатель на NET_PNP_EVENT_NOTIFICATION структура, описывающая событие Plug and Play или событие управления питанием, которое NDIS указывает драйверу протокола.

Возвращаемое значение

ProtocolNetPnPEvent может возвращать любое из следующих элементов:

Код возврата	Описание
NDIS_STATUS_SUCCESS	Драйвер протокола успешно обработал указанное событие сетевого Plug and Play, событие NDIS PnP или событие управления питанием. Значение этого кода состояния зависит от кода NetEvent в буферизованном NET_PNP_EVENT_NOTIFICATION структура в NetPnPEvent: NetEventSetPower Драйвер протокола выполнил все действия, связанные с драйвером, которые необходимы для подготовки устройства к переходу в запрошенное состояние питания устройства. NetEventQueryPower Базовый адаптер может перейти в запрошенное состояние питания устройства. NetEventQueryRemoveDevice Базовый адаптер можно удалить. NetEventCancelRemoveDevice Драйвер протокола выполнил все действия, относящиеся к драйверу, необходимые для подготовки к отмене удаления базового адаптера. NetEventReconfigure Драйвер протокола принял измененную конфигурацию. NetEventBindList Драйвер протокола имеет новый список привязок и выполнил связанную обработку. NetEventBindsComplete Драйвер протокола подтвердил указание NDIS о том, что драйвер протокола привязан ко всем доступным базовым адаптерам. NetEventPnPCapabilities Драйвер протокола подтвердил, что он получил текущие возможности пробуждения базового адаптера, связанного с указанной привязкой. NetEventPause Указанная привязка протокола перешла в состояние Приостановка . Привязка перейдет в состояние Приостановлено после того, как NDIS завершит все незавершенные запросы на отправку привязки. Дополнительные сведения об операциях приостановки см. в разделе Приостановка привязки. NetEventRestart Указанная привязка протокола перешла в состояние Перезапуск . Когда драйвер протокола будет готов к возобновлению операций отправки и получения для привязки, привязка переходит в состояние Выполняется . NetEventPortActivation Драйвер протокола подтвердил активацию порта, связанного с указанной привязкой. Дополнительные сведения об активации порта см. в разделе Активация порта NDIS. NetEventPortDeactivation Драйвер протокола подтвердил активацию порта, связанного с указанной привязкой.
NDIS_STATUS_PENDING	Драйвер протокола возвращает свой ответ на указанное событие асинхронно с помощью вызоваФункция NdisCompleteNetPnPEvent.
NDIS_STATUS_RESOURCES	Драйверу протокола не удалось получить необходимые системные ресурсы для удовлетворения указанного Plug and Play или события управления питанием.
NDIS_STATUS_NOT_SUPPORTED	Драйверы протокола NDIS 6.0 и более поздних версий не должны возвращать это состояние. NDIS 5. Драйвер протокола x, который не поддерживает Plug and Play, может вернуть это состояние в ответ на NetEventSetPower, чтобы указать, что NDIS должен отменить привязку к базовому адаптеру.
NDIS_STATUS_FAILURE	Драйвер протокола не выполнил указанное событие по причинам, отличным от указанных в предыдущем списке.

Драйвер протокола может завершиться сбоем событий NetEventQueryRemoveDevice и NetEventPortActivation .

Если драйвер протокола завершается сбоем события NetEventPortActivation , он не должен использовать связанные порты в последующих операциях.

Драйвер протокола всегда должен успешно выполнять события NetEventRestart, NetEventIMReEnableDevice, NetEventCancelRemoveDevice, NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPause, NetEventPortDeactivation и NetEventPnPCapabilities , возвращая NDIS_STATUS_SUCCESS.

Функция ProtocolNetPnPEvent требуется в драйверах протоколов для поддержки Plug and Play и управления питанием. NDIS вызывает ProtocolNetPnPEvent, чтобы уведомить драйвер протокола о возникновении события сетевого Plug and Play, события NDIS PnP или события управления питанием.

The NET_PNP_EVENT_NOTIFICATION структура, передаваемая в ProtocolNetPnPEvent , описывает это событие. ПротоколNetPnPEvent интерпретирует два основных элемента информации в структуре NET_PNP_EVENT_NOTIFICATION:

Код в элементе NetEvent, определяющий тип события Plug and Play или управления питанием.
Сведения о событиях. Например, при использовании события NetEventSetPower член Buffer содержит состояние питания устройства, в которое переходит устройство.

Драйвер протокола должен сохранить указатель NetPnPEvent . Этот указатель является обязательным входным параметром для функции NdisCompleteNetPnPEvent , которую драйвер протокола должен впоследствии вызвать, если ProtocolNetPnPEvent возвращает NDIS_STATUS_PENDING.

Драйвер протокола всегда должен успешно выполнять событие NetEventQueryPower . После установки активного подключения драйвер протокола может вызвать функцию PoRegisterSystemState , чтобы зарегистрировать состояние непрерывной занятости. До тех пор, пока действует государственная регистрация, диспетчер питания не пытается переводить систему в спящий режим. Когда подключение становится неактивным, драйвер протокола отменяет регистрацию состояния, вызывая функцию PoUnregisterSystemState . Драйвер протокола никогда не должен пытаться предотвратить переход системы в спящее состояние путем сбоя события NetEventQueryPower . Обратите внимание, что за событием NetEventQueryPower всегда следует событие NetEventSetPower . Событие NetEventSetPower , указывающее текущее состояние питания базового устройства, фактически отменяет событие NetEventQueryPower .

Если драйвер протокола не может освободить устройство (например, из-за того, что устройство используется), событие NetEventQueryRemoveDevice должно завершиться ошибкой, возвращая NDIS_STATUS_FAILURE.

Драйвер протокола всегда должен выполнять успешное выполнение NetEventCancelRemoveDevice, NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPnPCapabilities, NetEventPause или NetEventPortDeactivation , возвращая NDIS_STATUS_SUCCESS.

При обработке NetEventReconfigure или NetEventBindList драйвер протокола должен проверять данные, связанные с событием. Дополнительные сведения о таких данных см. в разделе NET_PNP_EVENT_NOTIFICATION.

NDIS вызывает ProtocolNetPnPEvent в IRQL = PASSIVE_LEVEL.

Примеры

Чтобы определить функцию ProtocolNetPnPEvent , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции. Windows предоставляет набор типов функций для драйверов. Объявление функции с помощью типов функций помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить функцию ProtocolNetPnPEvent с именем MyNetPnPEvent, используйте тип 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 см. в статье О поведении функции.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в NDIS 6.0 и более поздних версиях.
Целевая платформа	Windows
Header	ndis.h (включая Ndis.h)
IRQL	PASSIVE_LEVEL