Функция NdisCoOidRequest (ndis.h)

Статья
03/08/2023

Функция NdisCoOidRequest пересылает запрос целевым драйверам CoNDIS для запроса или задания сведений о целевом драйвере, указанных в OID.

Синтаксис

NDIS_STATUS NdisCoOidRequest(
  [in]           NDIS_HANDLE       NdisBindingHandle,
  [in, optional] NDIS_HANDLE       NdisAfHandle,
  [in, optional] NDIS_HANDLE       NdisVcHandle,
  [in, optional] NDIS_HANDLE       NdisPartyHandle,
  [in, out]      PNDIS_OID_REQUEST OidRequest
);

Параметры

[in] NdisBindingHandle

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

[in, optional] NdisAfHandle

Дескриптор, идентифицирующий семейство адресов (AF), совместно используемое клиентом, диспетчером вызовов и NDIS. Этот дескриптор был получен следующим образом:

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

Чтобы выполнить запрос от клиента или автономного диспетчера вызовов к базовому драйверу мини-порта, этот параметр должен иметь значение NULL.

[in, optional] NdisVcHandle

Дескриптор, идентифицирующий виртуальное подключение (VC), которое вызывающий объект запрашивает или задает сведения, если запрос зависит от VC. В противном случае, если этот параметр имеет значение NULL, запрос не зависит от VC. Для любого конкретного запроса VC вызывающий объект изначально получил этот дескриптор либо при создании VC с функцией NdisCoCreateVc , либо в качестве входного параметра для его функции ProtocolCoCreateVc . Для конкретного VC-запроса, который направляется к базовому драйверу мини-порта, этот дескриптор идентифицирует VC, а NdisAfHandle и NdisPartyHandle имеют значение NULL.

[in, optional] NdisPartyHandle

Дескриптор, который идентифицирует сторону в многоточейном VC, который запрашивает или задает сведения, если запрос относится к определенной стороне. В противном случае, если этот параметр имеет значение NULL, запрос не зависит от сторон. Для любого запроса конкретной стороны клиент первоначально получил этот дескриптор из успешного вызова функции NdisClAddParty или функции NdisClMakeCall или диспетчер вызовов получил этот дескриптор в качестве входного параметра для функции ProtocolCmAddParty . Если NdisAfHandle имеет значение NULL, NdisPartyHandle также имеет значение NULL.

[in, out] OidRequest

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

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

Целевой драйвер определяет, какой код NDIS_STATUS_XXX возвращаетNdisCoOidRequest , обычно одно из следующих значений:

Код возврата	Описание
NDIS_STATUS_SUCCESS	Операция запроса успешно завершена.
NDIS_STATUS_PENDING	Запрос обрабатывается асинхронно, и NDIS вызовет вызывающий объект. Функция ProtocolCoOidRequestComplete при выполнении запроса.
NDIS_STATUS_INVALID_OID	Код OID_XXX, указанный в элементе Oid структуры NDIS_OID_REQUEST в параметре OidRequest , недопустим или не поддерживается базовым драйвером.
NDIS_STATUS_INVALID_LENGTH или NDIS_STATUS_BUFFER_TOO_SHORT	Значение, указанное в элементе InformationBufferLength NDIS_OID_REQUEST структурированного буфера в OidRequest , не соответствует требованиям для заданного кода OID_XXX . Если информационный буфер слишком мал, член BytesNeeded NDIS_OID_REQUEST содержит правильное значение для InformationBufferLength, когда возвращается значение NdisCoOidRequest .
NDIS_STATUS_INVALID_DATA	Данные, предоставленные в InformationBuffer в заданной структуре NDIS_OID_REQUEST , недопустимы для заданного кода OID_XXX .
NDIS_STATUS_NOT_SUPPORTED или NDIS_STATUS_NOT_RECOGNIZED	Базовый драйвер не поддерживает запрошенную операцию.
NDIS_STATUS_RESOURCES	Не удалось выполнить запрос из-за нехватки ресурсов. Обычно это возвращаемое значение указывает, что попытка выделить память была неудачной, но это не обязательно указывает на то, что тот же запрос, если он будет отправлен позже, завершится ошибкой по той же причине.
NDIS_STATUS_NOT_ACCEPTED	Базовый драйвер попытался выполнить запрошенную операцию( обычно это запрос набора), но операция завершилась сбоем. Например, попытка задать слишком много адресов многоадресной рассылки может привести к тому, что NdisCoOidRequest вернет это значение.
NDIS_STATUS_CLOSING или NDIS_STATUS_CLOSING_INDICATING	Базовый драйвер не выполнил запрошенную операцию, так как выполняется операция закрытия.
NDIS_STATUS_RESET_IN_PROGRESS	Базовый драйвер мини-порта в настоящее время не может удовлетворить запрос, так как он в настоящее время сбрасывает затронутый сетевой адаптер. Функция ProtocolStatusEx вызывалась или будет вызываться с помощью NDIS_STATUS_RESET_START, чтобы указать, что выполняется сброс. Это возвращаемое значение не обязательно указывает на то, что тот же запрос, если он отправлен позже, завершится ошибкой по той же причине.
NDIS_STATUS_FAILURE	Обычно это значение представляет собой неспецифическое значение по умолчанию, которое возвращается, когда ни один из более конкретных NDIS_STATUS_XXX не привел к сбою запроса базового драйвера.
NDIS_STATUS_REQUEST_ABORTED	Драйвер мини-порта остановил обработку запроса. Например, NDIS называется miniportResetEx базового драйвера минипорта или Функция MiniportCancelOidRequest .

Клиенты CoNDIS и автономные диспетчеры вызовов могут вызывать функцию NdisCoOidRequest для отправки запроса OID для запроса или задания сведений, указанных OID, в целевом драйвере. Целевой драйвер может быть другим драйвером протокола CoNDIS или базовым драйвером.

Вызывающий объект NdisCoOidRequest должен выделить достаточный объем памяти для хранения буфера информации, связанного с указанным OID. Вызывающий объект также должен выделить и настроить буфер в OidRequest перед вызовом NdisCoOidRequest. Оба буфера должны быть выделены из непагрегированного пула, так как целевой драйвер может выполняться на вызове IRQL во время обработки запроса.

Некоторые ошибки, возвращаемые NdisCoOidRequest , можно исправить, в том числе следующие:

NDIS_STATUS_INVALID_OID
NDIS_STATUS_INVALID_LENGTH
NDIS_STATUS_BUFFER_TOO_SHORT
NDIS_STATUS_INVALID_DATA
NDIS_STATUS_RESOURCES
NDIS_STATUS_RESET_IN_PROGRESS

То есть драйвер может соответствующим образом изменить пакет в OidRequest , чтобы исправить код OID_XXX, размер или содержимое буфера в InformationBuffer и повторно отправить пакет запроса в NdisCoOidRequest. Тот же пакет может быть удовлетворен, когда драйвер повторно отправляет его в NdisCoOidRequest , если исходный вызов указал на выполнение сброса или что нехватка ресурсов, которая может быть временной, препятствует выполнению этого запроса.

В зависимости от значения параметра NdisAfHandle клиенты и автономные диспетчеры вызовов вызывают NdisCoOidRequest для взаимодействия друг с другом или с базовым драйвером мини-порта, ориентированным на подключение.

Если драйвер передает значение NULL для NdisVcHandle, запрос имеет глобальный характер, независимо от того, направляется ли запрос клиенту, диспетчеру вызовов или драйверу минипорта. Например, если вызывающий объект предоставляет для NdisVcHandle значение, отличное от NULL, запрос OID_GEN_CO_RCV_CRC_ERROR OID к базовому драйверу минипорта, ориентированному на подключение, возвращает количество ошибок циклической избыточности проверка (CRC), которые были обнаружены для конкретного виртуального сервера. Для того же запроса со значением NULL для NdisVcHandle базовый драйвер мини-порта возвращает общее количество ошибок CRC, которые были обнаружены для всех виртуальных машин.

Клиенты и автономные диспетчеры вызовов должны вызывать функцию NdisOidRequest для всех идентификаторов OID, не ориентированных на подключение, например тех, которые возвращаются в запросе OID_GEN_SUPPORTED_LIST , который обычно выдается во время инициализации после привязки драйвера протокола к базовому драйверу сетевой карты.

Если NdisCoOidRequest возвращает NDIS_STATUS_PENDING, запрос обрабатывается асинхронно и NDIS вызовет драйвер. Функция ProtocolCoOidRequestComplete при выполнении запроса. Если NdisCoOidRequest возвращает любое другое состояние, запрос завершается при возврате NdisCoOidRequest и NDIS не вызывает ProtocolCoOidRequestComplete.

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

Вызывать NdisCoOidRequest могут только клиенты и автономные диспетчеры вызовов, которые являются драйверами протоколов. McMs вызывают функцию NdisMCmOidRequest для взаимодействия со своими клиентами.

Требования

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