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

Статья
08/07/2023

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

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

Синтаксис

MINIPORT_CO_OID_REQUEST MiniportCoOidRequest;

NDIS_STATUS MiniportCoOidRequest(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] NDIS_HANDLE MiniportVcContext,
       PNDIS_OID_REQUEST NdisRequest
)
{...}

Параметры

[in] MiniportAdapterContext

Дескриптор контекстной области, выделенной драйвером мини-порта в функции MiniportInitializeEx . Драйвер мини-порта использует эту контекстную область для хранения сведений о состоянии адаптера мини-порта.

[in] MiniportVcContext

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

NdisRequest

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

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

MiniportCoOidRequest может возвращать одно из следующих значений состояния:

Код возврата	Описание
NDIS_STATUS_SUCCESS	Драйвер мини-порта задал или получил данные в соответствии с запросом.
NDIS_STATUS_PENDING	Драйвер мини-порта выполнит запрос асинхронно. После того как драйвер мини-порта завершит всю обработку, он должен вызватьФункция NdisMCoOidRequestComplete для информирования NDIS о том, что запрос завершен.
NDIS_STATUS_INVALID_OID	Запрос, указанный параметром OidRequest , был недопустимым или не распознавался.
NDIS_STATUS_NOT_SUPPORTED	Запрос, указанный параметром OidRequest , был распознаен, но не поддерживается драйвером мини-порта.
NDIS_STATUS_BUFFER_TOO_SHORT	Буфер, предоставленный параметром OidRequest , был слишком мал для хранения запрошенных данных.
NDIS_STATUS_INVALID_LENGTH	Значение, указанное в элементе InformationBufferLength структуры NDIS_OID_REQUEST в OidRequest , неверно для указанного кода OID_XXX .
NDIS_STATUS_INVALID_DATA	Один или несколько параметров, указанных для запроса в OidRequest iwas, недопустимы.
NDIS_STATUS_NOT_ACCEPTED	После вызова NDIS Функция MiniportDevicePnPEventNotify, указывая на неожиданное удаление, NDIS вызывает функцию MiniportHaltEx драйвера. Если драйвер получает какие-либо запросы OID до вызова NDIS MiniportHaltEx, он должен немедленно завершить такие запросы со значением состояния NDIS_STATUS_NOT_ACCEPTED.
NDIS_STATUS_REQUEST_ABORTED	Драйвер мини-порта остановил обработку запроса. Например, NDIS называется MiniportResetEx илиФункция MiniportCancelOidRequest.

Чтобы зарегистрировать MiniportCoOidRequest, драйверы минипорта вызывают функцию NdisSetOptionalHandlers из функции MiniportSetOptions . В MiniportSetOptions драйвер мини-порта инициализирует NDIS_MINIPORT_CO_CHARACTERISTICS структуру и передает ее в параметр OptionalHandlersэлемента NdisSetOptionalHandlers.

NDIS вызывает функцию MiniportCoOidRequest либо от своего имени, либо от имени связанного драйвера протокола, который вызвал функцию NdisCoOidRequest . Водители минипорта должны изучить запрос, предоставленный в OidRequest , и выполнить запрошенное действие. Дополнительные сведения о OID, обрабатываемых драйверами мини-портов, см. в разделе NDIS OID.

Обратите внимание, что NDIS не проверяет содержимое, относящееся к OID, в OidRequest . Поэтому сам драйвер должен проверить это содержимое. Если драйвер определяет, что заданное значение выходит за пределы, он должен завершить запрос и вернуть NDIS_STATUS_INVALID_DATA.

Если MiniportCoOidRequest возвращает NDIS_STATUS_PENDING, NDIS может вызвать MiniportCoOidRequest с другим запросом для адаптера минипорта, указанного в MiniportAdapterContext, до завершения ожидающего запроса. NDIS не сериализует запросы OID, ориентированные на подключение.

Примеры

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

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

MINIPORT_CO_OID_REQUEST MyCoOidRequest;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  MiniportAdapterContext,
    NDIS_HANDLE  MiniportVcContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

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

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

Требования

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