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

Artigo
08/07/2023

O NDIS chama a função ProtocolUnbindAdapterEx de um driver de protocolo para solicitar que o driver seja desassociado de um adaptador de miniporte subjacente.

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

Sintaxe

PROTOCOL_UNBIND_ADAPTER_EX ProtocolUnbindAdapterEx;

NDIS_STATUS ProtocolUnbindAdapterEx(
  [in] NDIS_HANDLE UnbindContext,
  [in] NDIS_HANDLE ProtocolBindingContext
)
{...}

Parâmetros

[in] UnbindContext

O identificador que identifica a área de contexto do NDIS para essa operação desassociada.

[in] ProtocolBindingContext

Um identificador para uma área de contexto alocada pelo driver de protocolo. O driver de protocolo mantém as informações de contexto por associação nessa área de contexto. O driver forneceu esse identificador para o NDIS quando o driver chamou a função NdisOpenAdapterEx .

Retornar valor

ProtocolUnbindAdapterEx retorna um dos seguintes valores de status:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	ProtocolUnbindAdapterEx desvinculado com êxito de um adaptador de miniporto subjacente.
NDIS_STATUS_PENDING	ProtocolUnbindAdapterEx não concluiu a operação desassociada e a operação será concluída de forma assíncrona. O driver de protocolo deve chamar o A função NdisCompleteUnbindAdapterEx após a conclusão da operação desassociada.

Comentários

ProtocolUnbindAdapterEx é uma função necessária. Como recíproco da função ProtocolBindAdapterEx , o NDIS chama ProtocolUnbindAdapterEx para liberar os recursos alocados pelo driver para operações de E/S de rede específicas de uma associação. Um driver de protocolo não pode falhar em uma operação desassociada.

Antes de chamar ProtocolUnbindAdapterEx, o NDIS pausa a associação de protocolo. Para pausar a associação, o NDIS chama a função ProtocolNetPnPEvent e especifica um evento NetEventPause .

ProtocolUnbindAdapterEx deve chamar a função NdisCloseAdapterEx para fechar a associação ao adaptador de miniporto subjacente. Se NdisCloseAdapterEx retornar NDIS_STATUS_SUCCESS, a operação de fechamento será concluída. Se NdisCloseAdapterEx retornar NDIS_STATUS_PENDING, o NDIS chamará o driver de protocolo Função ProtocolCloseAdapterCompleteEx após a conclusão da operação de fechamento.

Antes de chamar NdisCloseAdapterEx, o driver de protocolo deve limpar a lista de endereços multicast e os filtros de pacote para a associação. O driver de protocolo define a lista de endereços multicast de associação como NULL e o filtro de pacote como zero. Para obter mais informações, consulte OID_802_3_MULTICAST_LIST e OID_GEN_CURRENT_PACKET_FILTER.

Se um padrão de ativação tiver sido especificado, o driver de protocolo deverá removê-lo com o OID OID_PNP_REMOVE_WAKE_UP_PATTERN e limpar os parâmetros de dimensionamento lateral de recebimento com o OID OID_GEN_RECEIVE_SCALE_PARAMETERS . Um driver de protocolo NDIS 6.20 e posterior deve remover um padrão wake-on-LAN com o OID OID_PM_REMOVE_WOL_PATTERN e remover um descarregamento de protocolo de baixa potência com o OID_PM_REMOVE_PROTOCOL_OFFLOAD OID.

ProtocolUnbindAdapterEx não deve liberar a memória em ProtocolBindingContext até que a operação de fechamento seja concluída. O NDIS passa o identificador em ProtocolBindingContext para ProtocolCloseAdapterCompleteEx.

Se o driver de protocolo tiver concluído a operação desassociada, ProtocolUnbindAdapterEx poderá retornar NDIS_STATUS_SUCCESS. Se NdisCloseAdapterEx retornar NDIS_STATUS_PENDING, ProtocolUnbindAdapterEx deverá aguardar o NDIS chamar ProtocolCloseAdapterCompleteEx antes que possa retornar NDIS_STATUS_SUCCESS.

ProtocolUnbindAdapterEx pode retornar NDIS_STATUS_PENDING para adiar a conclusão da operação desassociada para uma hora posterior. Se ProtocolUnbindAdapterEx retornar NDIS_STATUS_PENDING, o driver deverá chamar o Função NdisCompleteUnbindAdapterEx para concluir a operação desassociada. Se a função NdisCloseAdapterEx retornar NDIS_STATUS_PENDING, o driver poderá concluir a operação desassociada em ProtocolCloseAdapterCompleteEx. ProtocolUnbindAdapterEx pode armazenar o identificador em UnbindContext na área de contexto em ProtocolBindingContext antes de chamar NdisCloseAdapterEx. Se ProtocolUnbindAdapterEx tiver armazenado o identificador, ProtocolCloseAdapterCompleteEx poderá passar o identificador para NdisCompleteUnbindAdapterEx para concluir a operação não vinculada.

Assim que ProtocolUnbindAdapterEx chama NdisCloseAdapterEx, o identificador obtido da função NdisOpenAdapterEx no parâmetro NdisBindingHandle torna-se inválido. ProtocolUnbindAdapterEx não pode fazer chamadas subsequentes para funções NdisXxx com esse identificador. O driver pode receber e status indicações do adaptador de miniporto subjacente até que a operação de fechamento seja concluída.

O NDIS chama ProtocolUnbindAdapterEx em IRQL = PASSIVE_LEVEL.

Atualizando configurações de RSS e gerenciamento de energia

Os drivers de protocolo NDIS 6.0 e 6.1 devem executar as seguintes operações quando aplicável:

Remover padrões wol (ativação de gerenciamento de energia) do adaptador de miniporto com o OID_PNP_REMOVE_WAKE_UP_PATTERN OID.
Limpar os parâmetros de dimensionamento do lado de recebimento com o OID_GEN_RECEIVE_SCALE_PARAMETERS OID.

Os drivers de protocolo NDIS 6.20 e posteriores devem executar as seguintes operações:

Remova os padrões wol de gerenciamento de energia do adaptador de miniporto com o OID_PM_REMOVE_WOL_PATTERN OID.
Remover descarregamentos de protocolo de gerenciamento de energia do adaptador de miniporto com o OID_PM_REMOVE_PROTOCOL_OFFLOAD OID.

Exemplos

Para definir uma função ProtocolUnbindAdapterEx , 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 gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função ProtocolUnbindAdapterEx chamada "MyUnbindAdapterEx", use o tipo PROTOCOL_UNBIND_ADAPTER_EX conforme mostrado neste exemplo de código:

PROTOCOL_UNBIND_ADAPTER_EX MyUnbindAdapterEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyUnbindAdapterEx(
    NDIS_HANDLE  UnbindContext,
    NDIS_HANDLE  ProtocolBindingContext
    )
  {...}

O tipo de função PROTOCOL_UNBIND_ADAPTER_EX é 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 PROTOCOL_UNBIND_ADAPTER_EX 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 para NDIS 6.0 e posterior.
Plataforma de Destino	Windows
Cabeçalho	ndis.h (inclua Ndis.h)
IRQL	PASSIVE_LEVEL