Функция 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 и NdisPartyHandleNULL.

[in, optional] NdisPartyHandle

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

[in, out] OidRequest

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

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

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

Возвращаемый код	Описание
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, запрос является глобальным в природе, направляется ли запрос клиенту, диспетчеру вызовов или драйверу минипорта. Например, если вызывающий объект предоставляет значение, отличное отNULL, для NdisVcHandle, OID_GEN_CO_RCV_CRC_ERROR запрос OID для базового драйвера минипорта, ориентированного на подключение, возвращает количество ошибок циклического избыточности (CRC), которые были обнаружены для определенного VC. Для того же запроса с 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 (include Ndis.h)
библиотеки	Ndis.lib
IRQL	<= DISPATCH_LEVEL
правил соответствия DDI	Irql_Connection_Function(ndis)