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

Статья
08/07/2023

Функция ProtocolCoOidRequestComplete завершает обработку асинхронного запроса OID CoNDIS.

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

Синтаксис

PROTOCOL_CO_OID_REQUEST_COMPLETE ProtocolCoOidRequestComplete;

void ProtocolCoOidRequestComplete(
  [in]      NDIS_HANDLE ProtocolAfContext,
  [in]      NDIS_HANDLE ProtocolVcContext,
  [in]      NDIS_HANDLE ProtocolPartyContext,
  [in, out] PNDIS_OID_REQUEST OidRequest,
  [in]      NDIS_STATUS Status
)
{...}

Параметры

[in] ProtocolAfContext

Дескриптор, идентифицирующий область контекста семейства адресов (AF). Если драйвер является клиентом, он предоставил этот дескриптор при вызовеФункция NdisClOpenAddressFamilyEx для подключения к диспетчеру вызовов. Если драйвер является диспетчером вызовов или диспетчером вызовов минипорта (MCM), он предоставил этот дескриптор из функции ProtocolCmOpenAf .

[in] ProtocolVcContext

Дескриптор, идентифицирующий активное виртуальное подключение (VC), для которое драйвер запросил или задал сведения, если запрос был специфичен для VC. В противном случае этот параметр имеет значение NULL.

[in] ProtocolPartyContext

Дескриптор, который идентифицирует сторону в многоточейном VC, для которую драйвер запрос запрашивал или для установки сведений, если запрос относится к определенной стороне. В противном случае этот параметр имеет значение NULL.

[in, out] OidRequest

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

[in] Status

Окончательное состояние запроса. Целевой драйвер или NDIS определяет это окончательное состояние. Этот параметр определяет, что ProtocolCoOidRequestComplete выполняет с данными в OidRequest.

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

None

Remarks

NDIS вызывает функцию ProtocolCoOidRequestComplete для завершения обработки клиента CoNDIS, диспетчера вызовов или запроса OID MCM, для которого функция NdisCoOidRequest или функция NdisMCmOidRequest вернули NDIS_STATUS_PENDING.

Чтобы зарегистрировать ProtocolCoOidRequestComplete в качестве клиента, драйвер инициализирует NDIS_CO_CLIENT_OPTIONAL_HANDLERS структуру и передает ее в параметр OptionalHandlers функции NdisSetOptionalHandlers . Чтобы зарегистрировать ProtocolCoOidRequestComplete в качестве диспетчера вызовов, драйвер инициализирует NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS структуру и передает ее в параметр OptionalHandlersэлемента NdisSetOptionalHandlers.

Целевой драйвер — это драйвер, обслуживающий запрос сведений об идентификаторе. Вызов целевого драйвера к NdisMCoOidRequestComplete, NdisCoOidRequestComplete илиФункция NdisMCmOidRequestComplete вызвала функцию ProtocolCoOidRequestComplete. NDIS перенаправит значение параметра Status , переданное этим функциям в качестве входного параметра Status , в ProtocolCoOidRequestComplete.

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

Если параметр Status имеет значение NDIS_STATUS_SUCCESS, то элемент BytesRead или BytesWrittenструктуры NDIS_OID_REQUEST , на которую указывает параметр OidRequest , указывает, сколько сведений было передано из буфера в элементе InformationBuffer NDIS_OID_REQUEST целевому драйверу или сколько сведений было возвращено в InformationBuffer соответственно.
Если драйвер сделал запрос, ProtocolCoOidRequestComplete может использовать данные, возвращаемые в InformationBuffer , в соответствии со значением, указанным в элементе Oid NDIS_OID_REQUEST.
Если параметр Status имеет значение NDIS_STATUS_INVALID_LENGTH или NDIS_STATUS_BUFFER_TOO_SHORT, то элемент BytesNeeded структуры NDIS_OID_REQUEST, на который указывает OidRequest , указывает значение элемента InformationBufferLength NDIS_OID_REQUEST, необходимое для выполнения запрошенной операции.
В таких случаях ProtocolCoOidRequestComplete может выделить достаточно буферного пространства для запроса, настроить другую структуру NDIS_OID_REQUEST с необходимым значением для InformationBufferLength и повторить запрос OID.
Если status является значением NDIS_STATUS_ XXX , которое является неустранимой ошибкой, ProtocolCoOidRequestComplete должен освободить память для структуры NDIS_OID_REQUEST. ProtocolCoOidRequestComplete также должен определить, следует ли драйверу закрыть привязку или настроить сведения о состоянии привязки для обработки продолжающихся операций сетевого ввода-вывода в привязке.

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

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

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

Примеры

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

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

PROTOCOL_CO_OID_REQUEST_COMPLETE MyCoOidRequestComplete;

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

_Use_decl_annotations_
VOID
 MyCoOidRequestComplete(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

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

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

Требования

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