SET_OPTIONS função de retorno de chamada (ndis.h)
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.
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 |
|---|---|
|
XxxSetOptions registrou com êxito os serviços e recursos opcionais do driver. |
|
XxxSetOptions não pôde alocar os recursos necessários para o driver. |
|
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);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 |