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

Статья
08/07/2023

Функция ProtocolOidRequestComplete завершает обработку инициированного драйвером протокола запроса OID, для которого функция NdisOidRequest возвращала NDIS_STATUS_PENDING.

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

Синтаксис

PROTOCOL_OID_REQUEST_COMPLETE ProtocolOidRequestComplete;

void ProtocolOidRequestComplete(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNDIS_OID_REQUEST OidRequest,
  [in] NDIS_STATUS Status
)
{...}

Параметры

[in] ProtocolBindingContext

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

[in] OidRequest

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

[in] Status

Окончательное состояние запроса. Это окончательное состояние определяет базовый драйвер или NDIS. Этот параметр определяет, что ProtocolOidRequestComplete выполняет с информацией в OidRequest.

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

None

Remarks

ProtocolOidRequestComplete использует входное значение Status следующим образом:

Если состояние имеет значение NDIS_STATUS_SUCCESS, элемент BytesRead или BytesWritten структуры NDIS_OID_REQUEST был задан NDIS или базовым драйвером, чтобы указать, сколько данных, предоставленных драйвером протокола, было передано из буфера в InformationBuffer в сетевой адаптер в операции set или сколько сведений было возвращено в InformationBuffer в ответ на операцию запроса.
Если драйвер протокола сделал запрос, ProtocolOidRequestComplete может использовать данные, возвращаемые в InformationBuffer , любым способом, определенным драйвером протокола, в зависимости от значения члена Oid .

Например, если драйвер протокола изначально инициировал OID_GEN_MAXIMUM_SEND_PACKETS запросе ProtocolOidRequestComplete может настроить переменные состояния в области ProtocolBindingContext для регулирования числа невыполненных отправлений, которые драйвер настроит для последующих вызовов функции NdisSendNetBufferLIsts .
Если параметр Status имеет значение NDIS_STATUS_INVALID_LENGTH или NDIS_STATUS_BUFFER_TOO_SHORT, член BytesNeeded указывает конкретное значение OID элемента InformationBufferLength , необходимое для выполнения запрошенной операции.
В таких случаях ProtocolOidRequestComplete может выделить достаточное пространство буфера для запроса, настроить другую структуру NDIS_OID_REQUEST с необходимым InformationBufferLength и тем же Oid и повторить вызов функции NdisOidRequest .

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

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

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

Дополнительные сведения о системных идентификаторах OID см. в разделе NDIS OID.

ProtocolOidRequestComplete можно вызвать до того, как драйвер протокола успеет проверить код состояния, возвращенный NdisOidRequest в состоянии.

NDIS вызывает ProtocolOidRequestComplete по адресу IRQL <= DISPATCH_LEVEL.

Примеры

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

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

PROTOCOL_OID_REQUEST_COMPLETE MyOidRequestComplete;

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

_Use_decl_annotations_
VOID
 MyOidRequestComplete(
    NDIS_HANDLE  ProtocolBindingContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

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

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

Требования

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