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

Статья
02/29/2024

Функция ProtocolCoOidRequest обрабатывает запросы OID, которые клиенты CoNDIS или автономные диспетчеры вызовов инициируют с помощью вызовов функции NdisCoOidRequest или запускаемых драйвером диспетчера вызовов мини-порта (MCM) путем вызовов функции NdisMCmOidRequest .

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

Синтаксис

PROTOCOL_CO_OID_REQUEST ProtocolCoOidRequest;

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

Параметры

[in] ProtocolAfContext

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

[in] ProtocolVcContext

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

[in] ProtocolPartyContext

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

[in, out] OidRequest

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

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

ProtocolCoOidRequest может возвращать одно из следующих данных:

Код возврата	Описание
NDIS_STATUS_SUCCESS	Клиент или диспетчер вызовов выполнили запрошенную операцию.
NDIS_STATUS_PENDING	Клиент или диспетчер вызовов обрабатывает этот запрос асинхронно и вызываетФункция NdisCoOidRequestComplete илиФункция NdisMCmOidRequestComplete по завершении запрошенной операции.
NDIS_STATUS_INVALID_LENGTH или NDIS_STATUS_BUFFER_TOO_SHORT	Драйвер не выполняет запрос, так как вызывающий объект функции NdisCoOidRequest или NdisMCmOidRequest не предоставил достаточное значение для элемента InformationBufferструктуры NDIS_OID_REQUEST для данного запроса. Драйвер задает член BytesNeeded NDIS_OID_REQUEST в буфере в параметре OidRequest значение, зависящее от OID элемента InformationBufferLength , необходимое для выполнения запрошенной операции.
NDIS_STATUS_XXX	Клиенту или диспетчеру вызовов не удалось выполнить запрос по определенной драйверу причине, такой как недопустимые входные данные, указанные для набора.
NDIS_STATUS_NOT_SUPPORTED	Клиенту или диспетчеру вызовов не удалось выполнить этот запрос, так как он не распознал код OID_GEN_CO_XXX в элементе Oid в буфере в NdisRequest.

Клиенты CoNDIS и диспетчеры вызовов отправляют информацию друг другу, указывая значение, отличное от NULL , в параметре NdisAfHandle при вызове функции NdisCoOidRequest . Аналогичным образом MCM вызывают NdisMCmOidRequest с явными значениями для NdisAfHandle для передачи информации клиентам. Такие вызовы NdisCoOidRequest или NdisMCmOidRequest приводят к тому, что NDIS вызывает функцию ProtocolCoOidRequest целевого клиента, диспетчера вызовов или MCM, связанную с указанным дескриптором AF.

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

Если параметры NdisVcHandle и NdisPartyHandleдля NdisCoOidRequest или NdisMCmOidRequest имеют значение NULL, запрос является глобальным по своей природе. То есть явное значение для NdisVcHandle или NdisPartyHandle указывает на то, что ProtocolCoOidRequest должен удовлетворять заданному запросу на основе VC или отдельной стороны соответственно.

Буфер в параметре OidRequest был выделен из непагрегированного пула и, следовательно, доступен при вызове IRQL. Вызывающий объект NdisCoOidRequest(или NdisMCmOidRequest) должен освободить этот буфер и внутренний буфер в элементе InformationBufferструктуры NDIS_OID_REQUEST , на которую указывает OidRequest .

Если ProtocolCoOidRequest возвращает NDIS_STATUS_PENDING, драйвер должен впоследствии вызватьФункция NdisCoOidRequestComplete илиФункция NdisMCmOidRequestComplete для драйвера MCM, когда драйвер завершает запрос.

Примеры

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

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

PROTOCOL_CO_OID_REQUEST MyCoOidRequest;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

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

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

Требования

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