SET_OPTIONS função de retorno de chamada (ndis.h)

Artigo
08/07/2023

O NDIS chama a função XxxSetOptions de um driver para permitir que o driver registre serviços opcionais. Essa função é definida como MiniportSetOptions para drivers de miniporto, ProtocolSetOptions para drivers de protocolo ou FilterSetOptions para drivers de filtro.

Nota Você deve declarar a função usando o tipo Xxx_SET_OPTIONS . Para obter mais informações, consulte a seção Exemplos.

Sintaxe

SET_OPTIONS SetOptions;

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

Parâmetros

[in] NdisDriverHandle

Um identificador que identifica um driver. O NDIS retorna esse identificador para o driver quando ele retorna da função de registro de driver ( NdisMRegisterMiniportDriver para drivers de miniport, NdisRegisterProtocolDriver para drivers de protocolo e NdisFRegisterFilterDriver para drivers de filtro).

[in] DriverContext

O identificador que o driver passou para NdisRegisterXxxDriver que identifica a área de contexto do driver, em que Xxx é o tipo de driver (Miniport, Protocolo ou Filtro).

Retornar valor

XxxSetOptions retorna um dos seguintes valores de status:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	XxxSetOptions registrou com êxito os serviços e recursos opcionais do driver.
NDIS_STATUS_RESOURCES	XxxSetOptions não pôde alocar os recursos necessários para o driver.
NDIS_STATUS_XXX ou NTSTATUS_XXX	Falha na tentativa do driver de registrar opções. Normalmente, esse erro status é propagado de uma função NdisXxx ou de uma rotina de suporte no modo kernel.

Comentários

XxxSetOptions é uma função opcional. O NDIS chama XxxSetOptions dentro do contexto da chamada do driver para o Função NdisRegisterXxxDriver , em que Xxx é o tipo de driver (Miniport, Protocolo ou Filtro).

XxxSetOptions registra serviços opcionais e pode alocar outros recursos de driver. Para registrar as funções opcionais MiniportXxx, ProtocolXxx ou FilterXxx , o driver chama a função NdisSetOptionalHandlers . O driver passa o identificador do parâmetro NdisDriverHandle no parâmetro NdisHandle de NdisSetOptionalHandlers e passa uma estrutura de características no parâmetro OptionalHandlers .

Os drivers de miniport podem ser aplicados aos serviços opcionais definidos nas seguintes estruturas de características:

NDIS_MINIPORT_CO_CHARACTERISTICS

NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS(consulte a documentação de descarregamento de chaminéS TCP NDIS 6.0)

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS(consulte a documentação de descarregamento de chaminéS TCP NDIS 6.0)

Os drivers de protocolo podem ser aplicados aos serviços opcionais definidos nas seguintes estruturas de características:

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

Não há serviços de driver de filtro opcionais na versão atual do Windows.

O NDIS pode chamar outras funções MiniportXxx, ProtocolXxx ou FilterXxx do driver a qualquer momento após o retorno de XxxSetOptions . O driver deve estar preparado para ser chamado novamente em sua função de inicialização:(MiniportInitializeEx para drivers de miniport, ProtocolBindAdapterEx para drivers de protocolo e FilterAttach para drivers de filtro).

Para drivers de miniporta, os adaptadores de miniporto estão no estado Parado antes que o NDIS chame MiniportInitializeEx. Para drivers de protocolo, as associações de protocolo estão no estado Unbound antes que o NDIS chame ProtocolBindAdapterEx. Para drivers de filtro, os módulos de filtro estão no estado Desanexado antes que o NDIS chame FilterAttach.

Se uma tentativa de alocar recursos ou serviços falhar, XxxSetOptions deverá desfazer todas as alocações que tiveram êxito antes de retornar o controle com um status diferente de NDIS_STATUS_SUCCESS.

XxxDriverUnload dos drivers de miniport e filtro deve desfazer todas as operações que foram executadas em XxxSetOptions

O NDIS chama XxxSetOptions em IRQL = PASSIVE_LEVEL.

Exemplos

Para definir uma função XxxSetOptions , primeiro você deve fornecer uma declaração de função que identifique o tipo de função que você está definindo. O Windows fornece um conjunto de tipos de função para drivers. Declarar uma função usando os tipos de função ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para escrever drivers para o sistema operacional Windows.

No arquivo de cabeçalho Ndis.h, a função de retorno de chamada SET_OPTIONS é definida da seguinte maneira:

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

Isso permite que todos os drivers NDIS implementem suas funções de retorno de chamada XxxSetOptions com a mesma sintaxe. Os drivers de miniporta usam o tipo MINIPORT_SET_OPTIONS , os drivers de protocolo usam o tipo PROTOCOL_SET_OPTIONS e os drivers de filtro usam o tipo FILTER_SET_OPTIONS .

Por exemplo, para definir uma função MiniportSetOptions chamada "MySetOptions", use o tipo MINIPORT_SET_OPTIONS conforme mostrado neste exemplo de código:

MINIPORT_SET_OPTIONS MySetOptions;

Em seguida, implemente sua função da seguinte maneira:

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

O tipo de função SET_OPTIONS é definido no arquivo de cabeçalho Ndis.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função SET_OPTIONS no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers NDIS.

Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Com suporte no NDIS 6.0 e posterior.
Plataforma de Destino	Windows
Cabeçalho	ndis.h (inclua Ndis.h)
IRQL	PASSIVE_LEVEL