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

Статья
08/07/2023

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

Примечание Функцию необходимо объявить с помощью типа PROTOCOL_UNBIND_ADAPTER_EX . Дополнительные сведения см. в следующем разделе Примеры.

Синтаксис

PROTOCOL_UNBIND_ADAPTER_EX ProtocolUnbindAdapterEx;

NDIS_STATUS ProtocolUnbindAdapterEx(
  [in] NDIS_HANDLE UnbindContext,
  [in] NDIS_HANDLE ProtocolBindingContext
)
{...}

Параметры

[in] UnbindContext

Дескриптор, определяющий область контекста NDIS для этой операции отмены привязки.

[in] ProtocolBindingContext

Дескриптор области контекста, выделенной драйвером протокола. Драйвер протокола хранит сведения о контексте для каждой привязки в этой области контекста. Драйвер предоставил этот дескриптор NDIS, когда драйвер вызывал функцию NdisOpenAdapterEx .

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

ProtocolUnbindAdapterEx возвращает одно из следующих значений состояния:

Код возврата	Описание
NDIS_STATUS_SUCCESS	ProtocolUnbindAdapterEx успешно отсоединяется от базового адаптера мини-порта.
NDIS_STATUS_PENDING	ProtocolUnbindAdapterEx не завершил операцию отмены привязки, и операция будет выполнена асинхронно. Драйвер протокола должен вызватьФункция NdisCompleteUnbindAdapterEx после завершения операции отмены привязки.

ProtocolUnbindAdapterEx является обязательной функцией. В качестве взаимной функции ProtocolBindAdapterEx NDIS вызывает ProtocolUnbindAdapterEx , чтобы освободить ресурсы, выделенные драйвером для операций сетевого ввода-вывода, относящихся к привязке. Драйвер протокола не может завершить операцию отмены привязки.

Перед вызовом ProtocolUnbindAdapterEx NDIS приостанавливает привязку протокола. Чтобы приостановить привязку, NDIS вызывает функцию ProtocolNetPnPEvent и определяет событие NetEventPause .

ProtocolUnbindAdapterEx должен вызвать функцию NdisCloseAdapterEx , чтобы закрыть привязку к базовому адаптеру мини-порта. Если NdisCloseAdapterEx возвращает NDIS_STATUS_SUCCESS, операция закрытия завершена. Если NdisCloseAdapterEx возвращает NDIS_STATUS_PENDING, NDIS вызывает драйвер протокола. Функция ProtocolCloseAdapterCompleteEx после завершения операции закрытия.

Перед вызовом NdisCloseAdapterEx драйвер протокола должен очистить список адресов многоадресной рассылки и фильтры пакетов для привязки. Драйвер протокола устанавливает для списка адресов многоадресной рассылки привязки значение NULL, а фильтр пакетов — нулевое значение. Дополнительные сведения см. в разделе OID_802_3_MULTICAST_LIST и OID_GEN_CURRENT_PACKET_FILTER.

Если указан шаблон пробуждения, драйвер протокола должен удалить его с OID_PNP_REMOVE_WAKE_UP_PATTERN OID и очистить параметры масштабирования на стороне получения с помощью OID_GEN_RECEIVE_SCALE_PARAMETERS OID. Драйвер протокола NDIS 6.20 и более поздних версий должен удалить шаблон пробуждения по локальной сети с OID_PM_REMOVE_WOL_PATTERN OID и удалить разгрузку протокола с низким энергопотреблением с OID_PM_REMOVE_PROTOCOL_OFFLOAD OID.

ProtocolUnbindAdapterEx не должен освобождать память в ProtocolBindingContext до завершения операции закрытия. NDIS передает дескриптор в ProtocolBindingContextв ProtocolCloseAdapterCompleteEx.

Если драйвер протокола завершил операцию отмены привязки, ProtocolUnbindAdapterEx может вернуть NDIS_STATUS_SUCCESS. Если NdisCloseAdapterEx возвращает NDIS_STATUS_PENDING, ProtocolUnbindAdapterEx должен ожидать, пока NDIS вызовет ProtocolCloseAdapterCompleteEx , прежде чем он сможет вернуть NDIS_STATUS_SUCCESS.

ProtocolUnbindAdapterEx может возвращать NDIS_STATUS_PENDING, чтобы отложить завершение операции отмены привязки на более позднее время. Если ProtocolUnbindAdapterEx возвращает NDIS_STATUS_PENDING, драйвер должен в конечном итоге вызватьФункция NdisCompleteUnbindAdapterEx для завершения операции отмены привязки. Если функция NdisCloseAdapterEx вернула NDIS_STATUS_PENDING, драйвер может завершить операцию отмены привязки в ProtocolCloseAdapterCompleteEx. ProtocolUnbindAdapterEx может хранить дескриптор в UnbindContext в области контекста ProtocolBindingContext перед вызовом NdisCloseAdapterEx. Если протокол ProtocolUnbindAdapterEx сохранил дескриптор, ProtocolCloseAdapterCompleteEx может передать дескриптор NdisCompleteUnbindAdapterEx для завершения операции отмены привязки.

Как только ProtocolUnbindAdapterEx вызывает NdisCloseAdapterEx, дескриптор, полученный из функции NdisOpenAdapterEx в параметре NdisBindingHandle , становится недействительным. ProtocolUnbindAdapterEx не может выполнять последующие вызовы функций NdisXxx с этим дескриптором. Драйвер может получать сведения о получении и состоянии от базового адаптера мини-порта до завершения операции закрытия.

NDIS вызывает ProtocolUnbindAdapterEx по адресу IRQL = PASSIVE_LEVEL.

Обновление параметров управления питанием и RSS

Драйверы протоколов NDIS 6.0 и 6.1 должны выполнять следующие операции, если это применимо:

Удалите шаблоны пробуждения управления питанием по локальной сети (WOL) из адаптера мини-порта с помощью OID_PNP_REMOVE_WAKE_UP_PATTERN OID.
Очистите параметры масштабирования на стороне получения с помощью OID_GEN_RECEIVE_SCALE_PARAMETERS OID.

Драйверы протокола NDIS 6.20 и более поздних версий должны выполнять следующие операции:

Удалите шаблоны WOL для управления питанием из адаптера мини-порта с помощью OID_PM_REMOVE_WOL_PATTERN OID.
Удалите разгрузки протокола управления питанием из адаптера мини-порта с помощью OID_PM_REMOVE_PROTOCOL_OFFLOAD OID.

Примеры

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

Например, чтобы определить функцию ProtocolUnbindAdapterEx с именем MyUnbindAdapterEx, используйте тип PROTOCOL_UNBIND_ADAPTER_EX , как показано в следующем примере кода:

PROTOCOL_UNBIND_ADAPTER_EX MyUnbindAdapterEx;

Затем реализуйте функцию следующим образом:

_Use_decl_annotations_
NDIS_STATUS
 MyUnbindAdapterEx(
    NDIS_HANDLE  UnbindContext,
    NDIS_HANDLE  ProtocolBindingContext
    )
  {...}

Тип функции PROTOCOL_UNBIND_ADAPTER_EX определен в файле заголовка Ndis.h. Чтобы более точно определить ошибки при запуске средств анализа кода, не забудьте добавить заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует использование заметок, которые применяются к типу функции PROTOCOL_UNBIND_ADAPTER_EX в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в статье Объявление функций с помощью типов ролей функций для драйверов NDIS.

Сведения о Use_decl_annotations см. в статье Поведение функции с заметками.

Требования

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