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

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 — это тип драйвера (Miniport, Protocol или Filter).

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

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

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

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

NDIS_PROTOCOL_CO_CHARACTERISTICS
NDIS_CO_CLIENT_OPTIONAL_HANDLERS
NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

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

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

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

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

Miniport и filter drivers ' 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

См. также раздел

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS NDIS_CO_CLIENT_OPTIONAL_HANDLERS NDIS_PROTOCOL_CO_CHARACTERISTICS

NdisOpenAdapterEx

NdisRegisterProtocolDriver

NdisSetOptionalHandlers

ProtocolBindAdapterEx