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

Статья
02/26/2024

NDIS вызывает функцию XxxSetOptions драйвера, чтобы разрешить драйверу регистрировать дополнительные службы. Эта функция определяется как MiniportSetOptions для драйверов мини-портов, ProtocolSetOptions для драйверов протоколов или FilterSetOptions для драйверов фильтров.

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

Синтаксис

SET_OPTIONS SetOptions;

NDIS_STATUS SetOptions(
  [in] NDIS_HANDLE NdisDriverHandle,
  [in] NDIS_HANDLE DriverContext
)
{...}

Параметры

[in] NdisDriverHandle

Дескриптор, идентифицирующий драйвер. NDIS возвращает этот дескриптор драйверу, когда он возвращается из функции регистрации драйвера ( NdisMRegisterMiniportDriver для драйверов минипорта, NdisRegisterProtocolDriver для драйверов протокола и NdisFRegisterFilterDriver для драйверов фильтров).

[in] DriverContext

Дескриптор, переданный драйвером в NdisRegisterXxxDriver , идентифицирующий область контекста драйвера, где Xxx — это тип драйвера (минипорт, протокол или фильтр).

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

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

Код возврата	Описание
NDIS_STATUS_SUCCESS	XxxSetOptions успешно зарегистрировал дополнительные службы и ресурсы драйвера.
NDIS_STATUS_RESOURCES	XxxSetOptions не удалось выделить ресурсы, необходимые драйверу.
NDIS_STATUS_XXX или NTSTATUS_XXX	Попытка драйвера зарегистрировать параметры завершилась сбоем. Обычно такое состояние ошибки распространяется из функции NdisXxx или подпрограммы поддержки режима ядра.

XxxSetOptions — это необязательная функция. NDIS вызывает XxxSetOptions в контексте вызова драйвера кФункция NdisRegisterXxxDriver, где Xxx — это тип драйвера (минипорт, протокол или фильтр).

XxxSetOptions регистрирует дополнительные службы и может выделять другие ресурсы драйвера. Чтобы зарегистрировать необязательные функции MiniportXxx, ProtocolXx или FilterXxx , драйвер вызывает функцию NdisSetOptionalHandlers . Драйвер передает дескриптор из параметра NdisDriverHandle в параметре NdisHandleNdisSetOptionalHandlers и передает структуру характеристик в параметр OptionalHandlers .

Драйверы miniport могут применяться к дополнительным службам, определенным в следующих структурах характеристик:

NDIS_MINIPORT_CO_CHARACTERISTICS

NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS (см. документацию по разгрузке дымохода TCP NDIS 6.0)

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS(см. документацию по разгрузке дымохода TCP NDIS 6.0)

Драйверы протокола могут применяться к необязательным службам, определенным в следующих структурах характеристик:

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

В текущей версии Windows нет дополнительных служб драйверов фильтров.

NDIS может вызывать другие функции драйвера MiniportXxx, ProtocolXxx или FilterXxx в любое время после возврата XxxSetOptions . Драйвер должен быть готов к обратному вызову при его функции инициализации:(MiniportInitializeEx для драйверов miniport, ProtocolBindAdapterEx для драйверов протоколов и FilterAttach для драйверов фильтров).

Для драйверов минипорта адаптеры минипорта находятся в состоянии Остановлено до вызова NDIS MiniportInitializeEx. Для драйверов протокола привязки протокола находятся в состоянии Unbound перед вызовом NDIS ProtocolBindAdapterEx. Для драйверов фильтров модули фильтров находятся в состоянии "Отсоединенный" , прежде чем NDIS вызовет FilterAttach.

Если попытка выделить ресурсы или службы завершается сбоем, XxxSetOptions должен отменить все выделения, которые были успешно выполнены, прежде чем вернуть управление с состоянием, отличающимся от NDIS_STATUS_SUCCESS.

XxxDriverUnload мини-порта и фильтров должны отменить все операции, выполненные в XxxSetOptions.

NDIS вызывает XxxSetOptions в IRQL = PASSIVE_LEVEL.

Примеры

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

В файле заголовка Ndis.h функция обратного вызова SET_OPTIONS определяется следующим образом:

typedef SET_OPTIONS (*SET_OPTIONS_HANDLER);
typedef SET_OPTIONS (MINIPORT_SET_OPTIONS);
typedef SET_OPTIONS (PROTOCOL_SET_OPTIONS);
typedef SET_OPTIONS (FILTER_SET_OPTIONS);

Это позволяет всем драйверам NDIS реализовать функции обратного вызова XxxSetOptions с одинаковым синтаксисом. Драйверы минипорта используют тип MINIPORT_SET_OPTIONS , драйверы протокола — тип PROTOCOL_SET_OPTIONS , а драйверы фильтров — тип FILTER_SET_OPTIONS .

Например, чтобы определить функцию MiniportSetOptions с именем MySetOptions, используйте тип MINIPORT_SET_OPTIONS , как показано в этом примере кода:

MINIPORT_SET_OPTIONS MySetOptions;

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

_Use_decl_annotations_
NDIS_STATUS
 MySetOptions(
    NDIS_HANDLE  NdisDriverHandle,
    NDIS_HANDLE  DriverContext
    )
  {...}

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

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

Требования

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