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

Статья
08/07/2023

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

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

Синтаксис

PROTOCOL_DIRECT_OID_REQUEST_COMPLETE ProtocolDirectOidRequestComplete;

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

Параметры

[in] ProtocolBindingContext

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

[in] OidRequest

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

[in] Status

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

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

None

Remarks

ProtocolDirectOidRequestComplete является необязательной функцией. Если драйвер протокола не использует прямые запросы OID, он может задать точке входа для этой функции значение NULL при вызовеФункция NdisRegisterProtocolDriver.

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

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

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

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

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

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

Примеры

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

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

PROTOCOL_DIRECT_OID_REQUEST_COMPLETE MyDirectOidRequestComplete;

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

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

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

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

Требования

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