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

Artigo
08/07/2023

A função ProtocolClIncomingCloseCall é usada por todos os clientes NDIS orientados à conexão. Todos esses clientes devem ter funções ProtocolClIncomingCloseCall totalmente funcionais.

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

Sintaxe

PROTOCOL_CL_INCOMING_CLOSE_CALL ProtocolClIncomingCloseCall;

void ProtocolClIncomingCloseCall(
  [in] NDIS_STATUS CloseStatus,
  [in] NDIS_HANDLE ProtocolVcContext,
  [in] PVOID CloseData,
  [in] UINT Size
)
{...}

Parâmetros

[in] CloseStatus

Especifica o status que indica a causa da remoção da conexão, que geralmente é NDIS_STATUS_SUCCESS para indicar que a parte remota da chamada solicitou que a conexão fosse fechada. Qualquer outro valor indica que problemas na rede fizeram com que o gerenciador de chamadas encerrasse a conexão.

[in] ProtocolVcContext

Especifica o identificador para a área de contexto por VC do cliente para a VC na qual a conexão está sendo fechada. Seja qual for o valor de CloseStatus, o cliente não pode enviar nem receber dados na VC designada pelo NdisVcHandle que armazenou nessa área de contexto.

[in] CloseData

Ponteiro para um buffer que contém uma mensagem de fechamento específica do protocolo, possivelmente uma fornecida pelo cliente remoto que o gerenciador de chamadas recebeu pela rede ou esse parâmetro pode ser NULL.

Quando CloseStatus é NDIS_STATUS_SUCCESS, esse parâmetro é NULL se o meio de rede subjacente não dá suporte a transferências de dados ao fechar uma conexão. No entanto, qualquer gerenciador de chamadas específico pode definir uma estrutura para passar informações de diagnóstico adicionais para seus clientes em desativações de chamada causadas por problemas na rede.

[in] Size

Especifica o tamanho em bytes do buffer em CloseData, zero se CloseData for NULL.

Retornar valor

Nenhum

Comentários

Uma chamada para ProtocolClIncomingCloseCall indica que ocorreu o seguinte:

O gerenciador de chamadas recebeu uma solicitação pela rede para fechar uma conexão estabelecida, identificada pelo NdisVcHandle que o cliente armazenou em sua área de contexto por VC em ProtocolVcContext .
O gerenciador de chamadas detectou que os problemas de rede impedirão novas transferências de dados na conexão estabelecida.

Em ambos os casos, ProtocolClIncomingCloseCall deve executar quaisquer operações determinadas pelo protocolo, como notificar os próprios clientes do cliente de que a conexão está sendo interrompida. Por exemplo, se a chamada a ser fechada for uma VC de vários pontos criada pelo cliente, ProtocolClIncomingCloseCall deverá chamar NdisClDropParty uma ou mais vezes até que apenas uma única parte permaneça em sua VC de vários pontos.

Se a VC fornecida for uma conexão de ponto único ou multiponto, ProtocolClIncomingCloseCall deve chamar NdisClCloseCall para reconhecer que o cliente não tentará enviar nem esperar receber dados nesta VC específica. Se o gerenciador de chamadas criou essa VC, ProtocolClIncomingCloseCall deverá retornar o controle depois de chamar NdisClCloseCall. É responsabilidade do gerenciador de chamadas destruir ou reutilizar qualquer VC que ele criou.

Se o cliente criou originalmente essa VC para uma chamada de saída, ProtocolClIncomingCloseCall poderá fazer um dos seguintes procedimentos depois de chamar NdisClDropParty quantas vezes forem necessárias, se houver, e NdisClCloseCall:

Se CloseStatus for NDIS_STATUS_SUCCESS, desative a VC com NdisCoDeleteVc e libere a área de contexto por VC do cliente ou prepare-a para reutilização em uma chamada subsequente para NdisCoCreateVc.
Se CloseStatus for NDIS_STATUS_SUCCESS, mantenha a VC que o cliente criou e prepare sua área de contexto por VC para reutilização em uma chamada subsequente para NdisClMakeCall.
Caso contrário, desative a VC com NdisCoDeleteVc e libere sua área de contexto por VC se o gerenciador de chamadas indicasse que a rede se tornou inoperante.

Exemplos

Para definir uma função ProtocolClIncomingCloseCall , 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.

Por exemplo, para definir uma função ProtocolClIncomingCloseCall chamada "MyClIncomingCloseCall", use o tipo PROTOCOL_CL_INCOMING_CLOSE_CALL conforme mostrado neste exemplo de código:

PROTOCOL_CL_INCOMING_CLOSE_CALL MyClIncomingCloseCall;

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

_Use_decl_annotations_
VOID
 MyClIncomingCloseCall(
    NDIS_STATUS  CloseStatus,
    NDIS_HANDLE  ProtocolVcContext,
    PVOID  CloseData,
    UINT  Size
    )
  {...}

O tipo de função PROTOCOL_CL_INCOMING_CLOSE_CALL é 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_CL_INCOMING_CLOSE_CALL 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 drivers NDIS 6.0 e NDIS 5.1 (consulte ProtocolClIncomingCloseCall (NDIS 5.1)) no Windows Vista. Com suporte para drivers NDIS 5.1 (consulte ProtocolClIncomingCloseCall (NDIS 5.1)) no Windows XP.
Plataforma de Destino	Windows
Cabeçalho	ndis.h (inclua Ndis.h)
IRQL	<= DISPATCH_LEVEL