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

Artículo
03/05/2024

NDIS llama a la función XxxSetOptions de un controlador para permitir que el controlador registre servicios opcionales. Esta función se define como MiniportSetOptions para controladores de minipuerto, ProtocolSetOptions para controladores de protocolo o FilterSetOptions para controladores de filtro.

Nota Debe declarar la función mediante el tipo 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 registró correctamente los recursos y servicios 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 NdisXxx o una rutina de compatibilidad con modo kernel.

Comentarios

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, ProtocolXxx o 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 minipuerto se pueden aplicar 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 la documentación de descarga de chimenea TCP de NDIS 6.0)

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

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 MiniportXxx, ProtocolXxx o FilterXxx del controlador en cualquier momento después de que se devuelva XxxSetOptions. El controlador debe estar preparado para volver a llamarse en su función de inicialización:(MiniportInitializeEx para controladores de minipuerto, ProtocolBindAdapterEx para controladores de protocolo y FilterAttach para controladores de filtro).

En el caso de los controladores de minipuerto, los adaptadores de minipuerto están en estado Detenido antes de que el NDIS llame a MiniportInitializeEx. En el caso de los controladores de protocolo, los enlaces de protocolo están en estado Unbound antes de que el NDIS llame a ProtocolBindAdapterEx. En el caso de los controladores de filtro, los módulos de filtro están en 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 que devuelva el control con un estado distinto de NDIS_STATUS_SUCCESS.

Miniportar y filtrar controladores xxxDriverUnload deben deshacer todas las operaciones que se realizaron en XxxSetOptions

NDIS llama a XxxSetOptions en IRQL = PASSIVE_LEVEL.

Ejemplos

Para definir una 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 Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación a encontrar 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 minipuerto 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 de MINIPORT_SET_OPTIONS 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, consulte 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, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Se admite en NDIS 6.0 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	PASSIVE_LEVEL