SET_OPTIONS función de devolución de llamada (ndis.h)

Artículo
02/07/2025

NDIS llama a la función XxxSetOp tions de un controlador para permitir que el controlador registre servicios opcionales. Esta función se define como miniportSetOptions para controladores de miniport, ProtocolSetOptions para controladores de protocolo o filterSetOptions para controladores de filtro.

Nota Debe declarar la función mediante el tipo de Xxx_SET_OPTIONS. Para obtener más información, vea la sección Ejemplos.

Sintaxis

SET_OPTIONS SetOptions;

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

Parámetros

[in] NdisDriverHandle

Identificador que identifica un controlador. NDIS devuelve este identificador al controlador cuando vuelve de la función de registro del controlador ( NdisMRegisterMiniportDriver para controladores de miniport, NdisRegisterProtocolDriver para controladores de protocolo y NdisFRegisterFilterDriver para controladores de filtro).

[in] DriverContext

Identificador que el controlador pasó a NdisRegisterXxxDriver que identifica el área de contexto del controlador, donde Xxx es el tipo de controlador (Miniport, Protocol o Filter).

Valor devuelto

xxxSetOptions devuelve uno de los siguientes valores de estado:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	XxxSetOptions registrar correctamente los servicios y recursos opcionales del controlador.
NDIS_STATUS_RESOURCES	xxxSetOptions no pudo asignar los recursos que requiere el controlador.
NDIS_STATUS_XXX o NTSTATUS_XXX	Error al intentar registrar las opciones del controlador. Normalmente, este estado de error se propaga desde una función de Ndisfunción xxx o una rutina de compatibilidad en modo kernel.

Observaciones

xxxSetOptions es una función opcional. NDIS llama a XxxSetOptions en el contexto de la llamada del controlador a . función NdisRegisterXxxDriver, donde Xxx es el tipo de controlador (Miniport, Protocol o Filter).

XxxSetOptions registra servicios opcionales y puede asignar otros recursos de controlador. Para registrar funciones opcionales MiniportXxx, ProtocolXxxo FilterXxx, el controlador llama a la función NdisSetOptionalHandlers. El controlador pasa el identificador del parámetro NdisDriverHandle en el parámetro NdisHandle de NdisSetOptionalHandlers y pasa una estructura de características en el parámetro OptionalHandlers.

Los controladores de miniport pueden aplicarse a los servicios opcionales definidos en las siguientes estructuras de características:

NDIS_MINIPORT_CO_CHARACTERISTICS

NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS(consulte documentación de descarga de chimenea TCP 6.0 de NDIS 6.0)

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS(consulte documentación de descarga de NDIS 6.0 TCP chimney)

Los controladores de protocolo se pueden aplicar a los servicios opcionales definidos en las siguientes estructuras de características:

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

No hay ningún servicio de controlador de filtro opcional en la versión actual de Windows.

NDIS puede llamar a las demás funciones del controlador MiniportXxx, ProtocolXxxo Funciones filterXxx en cualquier momento después de XxxSetOptions. El controlador debe prepararse para volver a llamarse en su función de inicialización:(MiniportInitializeEx para controladores de miniport, ProtocolBindAdapterEx para controladores de protocolo y FilterAttach para controladores de filtro).

Para los controladores de miniporte, los adaptadores de minipuerto se encuentran en el estado detenido antes de que el NDIS llame a MiniportInitializeEx. En el caso de los controladores de protocolo, los enlaces de protocolo se encuentran en el estado Unbound antes de que el NDIS llame a ProtocolBindAdapterEx. En el caso de los controladores de filtro, los módulos de filtro se encuentran en el estado desasociado antes de que el NDIS llame a FilterAttach.

Si se produce un error en un intento de asignar recursos o servicios, XxxSetOptions debe deshacer todas las asignaciones que se realizaron correctamente antes de devolver el control con un estado distinto de NDIS_STATUS_SUCCESS.

Los controladores de miniportar y filtrar xxxDriverUnload deben deshacer todas las operaciones que se realizaron en XxxSetOptions

NDIS llama a XxxSetOptions en IRQL = PASSIVE_LEVEL.

Ejemplos de

Para definir un función xxxSetOptions, primero debe proporcionar una declaración de función que identifique el tipo de función que va a definir. Windows proporciona un conjunto de tipos de función para controladores. Declarar una función mediante los tipos de función ayuda a análisis de código para controladores, comprobador de controladores estáticos (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

En el archivo de encabezado Ndis.h, la función de devolución de llamada SET_OPTIONS se define de la siguiente manera:

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

Esto permite que todos los controladores NDIS implementen sus funciones de devolución de llamada XxxSetOptions con la misma sintaxis. Los controladores de miniportar usan el tipo de MINIPORT_SET_OPTIONS, los controladores de protocolo usan el tipo de PROTOCOL_SET_OPTIONS y los controladores de filtro usan el tipo de FILTER_SET_OPTIONS.

Por ejemplo, para definir una función MiniportSetOptions denominada "MySetOptions", use el tipo MINIPORT_SET_OPTIONS tal como se muestra en este ejemplo de código:

MINIPORT_SET_OPTIONS MySetOptions;

A continuación, implemente la función de la siguiente manera:

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

El tipo de función SET_OPTIONS se define en el archivo de encabezado Ndis.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función SET_OPTIONS en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declaración de funciones mediante el uso de tipos de roles de función para controladores NDIS.

Para obtener información sobre Use_decl_annotations, vea Anotación del comportamiento de la función.

Requisitos

Requisito	Valor
cliente mínimo admitido	Se admite en NDIS 6.0 y versiones posteriores.
de la plataforma de destino de	Windows
encabezado de	ndis.h (incluya Ndis.h)
irQL	PASSIVE_LEVEL