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

Artigo
08/07/2023

A função ProtocolClOpenAfCompleteEx conclui a abertura de uma AF (família de endereços) iniciada quando um cliente CoNDIS chamado NdisClOpenAddressFamilyEx .

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

Sintaxe

PROTOCOL_CL_OPEN_AF_COMPLETE_EX ProtocolClOpenAfCompleteEx;

void ProtocolClOpenAfCompleteEx(
  [in] NDIS_HANDLE ProtocolAfContext,
  [in] NDIS_HANDLE NdisAfHandle,
  [in] NDIS_STATUS Status
)
{...}

Parâmetros

[in] ProtocolAfContext

Um identificador fornecido pelo cliente para sua área de contexto para um AF de endereço. O cliente alocou essa área de contexto e passou esse identificador para o NDIS em sua chamada para o Função NdisClOpenAddressFamilyEx .

[in] NdisAfHandle

Um identificador fornecido pelo NDIS para um AF, se Status for NDIS_STATUS_SUCCESS. Caso contrário, esse parâmetro será NULL. Esse identificador representa uma associação que o NDIS estabeleceu entre o cliente e um gerenciador de chamadas associado a um adaptador de miniporto CoNDIS. Se o identificador não for NULL, o cliente deverá salvar o identificador para uso em chamadas subsequentes para as funções NdisClXxx e NdisCoXxx .

[in] Status

O status final da chamada do cliente para NdisClOpenAddressFamilyEx, que pode ser qualquer um dos seguintes:

NDIS_STATUS_SUCCESS

O AF foi aberto, para que o cliente possa inicializar seu estado em ProtocolAfContext e usar o identificador retornado de NdisAfHandle em chamadas subsequentes para funções NdisClXxx e NdisCoXxx , como NdisCoOidRequest.

NDIS_STATUS_RESOURCES

A operação solicitada falhou porque o NDIS ou o gerenciador de chamadas não pôde alocar memória suficiente ou inicializar o estado que um deles usa para acompanhar a abertura do af do cliente que ProtocolAfContext especifica.

NDIS_STATUS_FAILURE

Falha no NDIS na chamada, possivelmente por um dos seguintes motivos:

O AF especificado não corresponde a nenhum AF registrado para o driver de miniporto subjacente ao qual o chamador está associado.
A associação do adaptador do chamador está sendo fechada.
O gerenciador de chamadas que registrou o AF especificado está fechando sua associação ao adaptador de miniporto subjacente.

Retornar valor

Nenhum

Comentários

A função ProtocolClOpenAfCompleteEx é necessária para clientes CoNDIS. Os clientes coNDIS devem fornecer ProtocolClOpenAfCompleteEx para concluir as operações assíncronas iniciadas pelos clientes chamando o Função NdisClOpenAddressFamilyEx .

O NDIS chama ProtocolClOpenAfCompleteEx para indicar que alguns ou todos os seguintes ocorreram:

Se todos os parâmetros do clienteA função ProtocolCoAfRegisterNotify passada para a função NdisClOpenAddressFamilyEx era válida, o NDIS chamou a função ProtocolCmOpenAf do gerenciador de chamadas que acabou de registrar o AF especificado com NDIS.
O gerenciador de chamadas examinou a especificação que a função ProtocolCoAfRegisterNotify do cliente passou para NdisClOpenAddressFamilyEx no parâmetro AddressFamily e retornou se era válida para esse gerenciador de chamadas para o NDIS.

Se a tentativa do cliente de abrir um AF falhar, o NDIS limpará seu estado salvo antes de chamar ProtocolClOpenAfCompleteEx. Nesse caso, ProtocolClOpenAfCompleteEx pode liberar os recursos alocados pelo cliente para sua chamada para NdisClOpenAddressFamilyEx ou prepará-los para reutilização.

Caso contrário, ProtocolClOpenAfCompleteEx deverá configurar qualquer estado determinado pelo cliente que o cliente precisará para operações subsequentes no AF recém-aberto. Em particular, o cliente deve salvar o identificador do parâmetro NdisAfHandle , normalmente na área de contexto ProtocolAfContext do cliente.

Se o cliente aceitar chamadas recebidas, ele poderá alocar uma área de estado de ponto de acesso por serviço (SAP) e chamar a função NdisClRegisterSap . Se o cliente fizer chamadas de saída, ele poderá alocar uma área de estado de VC (conexão por virtual) e criar uma VC com a função NdisCoCreateVc para se preparar para uma solicitação de entrada de um dos próprios clientes do cliente para fazer uma chamada de saída para um nó remoto.

O NDIS chama ProtocolClOpenAfCompleteEx em IRQL = PASSIVE_LEVEL.

Exemplos

Para definir uma função ProtocolClOpenAfCompleteEx , 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 ProtocolClOpenAfCompleteEx chamada "MyClOpenAfCompleteEx", use o tipo PROTOCOL_CL_OPEN_AF_COMPLETE_EX conforme mostrado neste exemplo de código:

PROTOCOL_CL_OPEN_AF_COMPLETE_EX MyClOpenAfCompleteEx;

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

_Use_decl_annotations_
VOID
 MyClOpenAfCompleteEx(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisAfHandle,
    NDIS_STATUS  Status
    )
  {...}

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