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

Artigo
02/07/2025

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

Observação 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 não vinculada.

[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.

Valor de retorno

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 não vinculada e a operação será concluída de forma assíncrona. O driver de protocolo deve chamar o função NdisCompleteUnbindAdapterEx após a conclusão da operação não vinculada.

Observações

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 a uma associação. Um driver de protocolo não pode falhar em uma operação não vinculada.

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 do lado 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 OID_PM_REMOVE_PROTOCOL_OFFLOAD.

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 não vinculada, ProtocolUnbindAdapterEx poderá retornar NDIS_STATUS_SUCCESS. Se NdisCloseAdapterEx retornar NDIS_STATUS_PENDING, ProtocolUnbindAdapterEx deverá aguardar que o NDIS chame ProtocolCloseAdapterCompleteEx antes que possa retornar NDIS_STATUS_SUCCESS.

ProtocolUnbindAdapterEx pode retornar NDIS_STATUS_PENDING para adiar a conclusão da operação não vinculada para um momento posterior. Se ProtocolUnbindAdapterEx retornar NDIS_STATUS_PENDING, o driver deverá eventualmente chamar o função NdisCompleteUnbindAdapterEx para concluir a operação não vinculada. Se a função NdisCloseAdapterEx retornada NDIS_STATUS_PENDING, o driver poderá concluir a operação não vinculada no ProtocolCloseAdapterCompleteEx. ProtocolUnbindAdapterEx pode armazenar o identificador em UnbindContext na área de contexto em ProtocolBindingContext antes de chamar NdisCloseAdapterEx. Se ProtocolUnbindAdapterEx 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 obter indicações de recebimento e status do adaptador de miniporto subjacente até que a operação de fechamento seja concluída.

Chamadas de NDIS ProtocolUnbindAdapterEx em IRQL = PASSIVE_LEVEL.

atualizando o gerenciamento de energia e as configurações do RSS

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

Remover os padrões de velório de gerenciamento de energia em PADRÕES (WOL) 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 OID_PM_REMOVE_WOL_PATTERN.
Remover descarregamentos do protocolo de gerenciamento de energia do adaptador de miniporto com o OID_PM_REMOVE_PROTOCOL_OFFLOAD OID.

exemplos de

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 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
de cliente com suporte mínimo	Com suporte para NDIS 6.0 e posterior.
da Plataforma de Destino	Windows
cabeçalho	ndis.h (inclua Ndis.h)
IRQL	PASSIVE_LEVEL