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

Статья
08/07/2023

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

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

Синтаксис

PROTOCOL_BIND_ADAPTER_EX ProtocolBindAdapterEx;

NDIS_STATUS ProtocolBindAdapterEx(
  [in] NDIS_HANDLE ProtocolDriverContext,
  [in] NDIS_HANDLE BindContext,
  [in] PNDIS_BIND_PARAMETERS BindParameters
)
{...}

Параметры

[in] ProtocolDriverContext

Дескриптор выделенной драйвером контекстной области, в которой драйвер хранит сведения о состоянии и конфигурации. Драйвер протокола передал эту область контекста вФункция NdisRegisterProtocolDriver.

[in] BindContext

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

[in] BindParameters

Указатель на структуру NDIS_BIND_PARAMETERS , созданную NDIS.

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

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

Код возврата	Описание
NDIS_STATUS_SUCCESS	ProtocolBindAdapterEx успешно завершил привязку к базовому адаптеру мини-порта.
NDIS_STATUS_PENDING	ProtocolBindAdapterEx не завершил операцию привязки, и операция будет выполнена асинхронно. Драйвер протокола должен вызватьФункция NdisCompleteBindAdapterEx по завершении операции.
NDIS_STATUS_RESOURCES	ProtocolBindAdapterEx не удалось выделить ресурсы, необходимые драйверу для выполнения операций сетевого ввода-вывода.
NDIS_STATUS_XXX или NTSTATUS_XXX	Попытка драйвера протокола настроить привязку завершилась сбоем. Обычно такое состояние ошибки распространяется из функции NdisXxx или подпрограммы поддержки режима ядра.

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

ProtocolBindAdapterEx выделяет достаточно памяти для хранения сведений контекста привязки и вызывает функцию NdisOpenAdapterEx для привязки к базовому адаптеру мини-порта. ProtocolBindAdapterEx передает указатель на сведения о контексте привязки в параметре ProtocolBindingContextобъекта NdisOpenAdapterEx. ProtocolBindAdapterEx передает значение элемента AdapterName из своего параметра BindParameters в качестве члена AdapterName параметра OpenParametersобъекта NdisOpenAdapterEx.

Прежде чем драйвер вызовет NdisOpenAdapterEx, драйвер может передать указатель bindParameters на функцию NdisOpenConfigurationEx для чтения параметров конфигурации, связанных с адаптером мини-порта.

После успешного открытия адаптера мини-порта драйвер может передать дескриптор из параметра NdisHandleNdisOpenAdapterExв NdisOpenConfigurationEx , чтобы получить дескриптор в расположение реестра, где хранятся параметры конфигурации для привязки протокола.

ProtocolBindAdapterEx передает NdisOpenAdapterEx указатель на массив значений средних типов, который содержит список типов носителей, которые может поддерживать драйвер протокола. Этот список представляет собой подмножество типов NDIS_MEDIUM . NDIS указывает выбранный тип среды в параметре SelectedMediumIndex структуры OpenParameters.

Если NdisOpenAdapterEx возвращает состояние ошибки, ProtocolBindAdapterEx возвращает это состояние ошибки, освобождает все ресурсы привязки, выделенные драйвером протокола, и немедленно возвращает управление.

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

Если NdisOpenAdapterEx возвращает NDIS_STATUS_PENDING, NDIS вызывает драйвер протокола Функция ProtocolOpenAdapterCompleteEx после завершения операции открытия. ProtocolOpenAdapterCompleteEx может выполнять операции привязки. ProtocolBindAdapterEx может хранить дескриптор BindContext в области контекста привязки. NDIS передает ProtocolBindingContext в качестве входного параметра в функцию ProtocolOpenAdapterCompleteEx драйвера.

Если NdisOpenAdapterEx возвращает NDIS_STATUS_PENDING, NDIS задает элемент SelectedMediumIndex структуры в параметре OpenParameters и значение параметра NdisBindingHandle после возврата NdisOpenAdapterEx . NDIS задает эти значения перед вызовом ProtocolOpenAdapterCompleteEx. Таким образом, драйвер протокола должен хранить открытую структуру параметров и дескриптор привязки протокола в области контекста в ProtocolBindingContext(или любом расположении, которое является допустимым до тех пор, пока NDIS не вызовет ProtocolOpenAdapterCompleteEx).

Драйвер протокола не может выполнять запросы OID к привязке до завершения операции открытия. Так как после завершения операции открытия привязка находится в приостановленном состоянии, драйвер протокола не может отправлять запросы до тех пор, пока NDIS не перезапустит привязку.

После завершения операции открытия ProtocolBindAdapterEx может вернуть NDIS_STATUS_SUCCESS для завершения операции привязки. ProtocolBindAdapterEx может возвращать NDIS_STATUS_PENDING, чтобы отложить завершение операций привязки на более позднее время. Если ProtocolBindAdapterEx возвращает NDIS_STATUS_PENDING, драйвер должен вызватьФункция NdisCompleteBindAdapterEx после завершения операции привязки.

Драйверы протоколов должны использовать структуру NDIS_BIND_PARAMETERS для определения возможностей базового адаптера мини-порта. После завершения операции открытия в зависимости от базового носителя драйвер протокола может вызвать функцию NdisOidRequest , чтобы запросить у базового драйвера минипорта (или NDIS) дополнительные возможности адаптера мини-порта. Дополнительные сведения о запросах OID см. в разделе Запросы OID драйвера протокола.

NDIS может вызывать драйвер протокола Функция ProtocolReceiveNetBufferLists после того, как драйвер настраивает фильтр пакетов для привязки с помощью OID_GEN_CURRENT_PACKET_FILTER OID. Если базовый адаптер мини-порта не использует фильтр пакетов для входящих пакетов, признаки получения включаются после завершения операции открытия. Драйверы протокола могут получать сведения о состоянии функции ProtocolStatusEx после завершения операции открытия.

Каждый драйвер протокола должен выделять достаточное количество NET_BUFFER и NET_BUFFER_LIST пулы структуры. Драйвер выделяет дескрипторы сетевых данных из этих пулов для последующих операций отправки.

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

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

Если драйвер протокола успешно открывает адаптер мини-порта, но операция привязки завершается сбоем (например, в результате неудачного запроса OID), драйвер должен закрыть адаптер мини-порта из контекста ProtocolBindAdapterEx или ProtocolUnbindAdapterEx. Например, драйвер вызывает NdisCloseAdapterEx из ProtocolBindAdapterEx и ожидает завершения операции закрытия, прежде чем драйвер вернется из ProtocolBindAdapterEx. В качестве альтернативы, если драйвер вернул NDIS_STATUS_PENDING из ProtocolBindAdapterEx, драйвер может вызвать функцию NdisUnbindAdapter и вызвать NdisCloseAdapterEx в функции ProtocolUnbindAdapterEx .

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

Примеры

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

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

PROTOCOL_BIND_ADAPTER_EX MyBindAdapterEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyBindAdapterEx(
    NDIS_HANDLE  ProtocolDriverContext,
    NDIS_HANDLE  BindContext,
    PNDIS_BIND_PARAMETERS  BindParameters
    )
  {...}

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

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

Требования

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