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

Artigo
08/07/2023

A função ProtocolClMakeCallComplete é usada por clientes NDIS orientados à conexão que fazem chamadas de saída. Esses clientes devem ter funções ProtocolClMakeCallComplete para concluir as operações assíncronas iniciadas com NdisClMakeCall. Caso contrário, a função ProtocolClMakeCallComplete registrada de um driver de protocolo pode simplesmente retornar o controle.

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

Sintaxe

PROTOCOL_CL_MAKE_CALL_COMPLETE ProtocolClMakeCallComplete;

void ProtocolClMakeCallComplete(
  [in]           NDIS_STATUS Status,
  [in]           NDIS_HANDLE ProtocolVcContext,
  [in, optional] NDIS_HANDLE NdisPartyHandle,
  [in]           PCO_CALL_PARAMETERS CallParameters
)
{...}

Parâmetros

[in] Status

Especifica o status final da chamada original do cliente para NdisClMakeCall, que pode ser um dos seguintes:

NDIS_STATUS_SUCCESS

A tentativa do cliente de configurar uma conexão virtual com êxito. Consequentemente, o cliente pode continuar a fazer transferências na VC ativa usando o NdisVcHandle retornado por NdisCoCreateVc, que o cliente armazenou em sua área de contexto por VC em ProtocolVcContext .

NDIS_STATUS_RESOURCES

O NDIS, o gerenciador de chamadas ou um driver subjacente não puderam alocar recursos suficientes para configurar a conexão.

NDIS_STATUS_XXX

O gerenciador de chamadas ou o driver de miniporto subjacente falharam ao estabelecer uma conexão ativa e o NDIS propagava essa falha determinada pelo driver status para o cliente.

[in] ProtocolVcContext

Especifica o identificador para a área de contexto por VC do cliente, que o cliente originalmente forneceu ao NDIS quando chamou NdisCoCreateVc para configurar a VC para sua chamada de saída.

[in, optional] NdisPartyHandle

Se Status for NDIS_STATUS_SUCCESS e o cliente tiver criado uma VC de vários pontos passando um identificador ProtocolPartyContext explícito para NdisClMakeCall, este será um NdisPartyHandle válido. Caso contrário, esse parâmetro será NULL.

ProtocolClMakeCallComplete deve salvar qualquer entrada válida NdisPartyHandle, geralmente na área de contexto por parte do cliente. O cliente deve usar esse identificador se (ou quando) fizer uma chamada subsequente para NdisClDropParty ou NdisClCloseCall que se refere a essa parte.

[in] CallParameters

Ponteiro para uma estrutura de CO_CALL_PARAMETERS em buffer. O cliente alocou esse buffer e inicializou essa estrutura com dados determinados pelo cliente antes de passar esse ponteiro para NdisClMakeCall. Ao processar a solicitação do cliente, o gerenciador de chamadas pode modificar esses dados para refletir os resultados de sua negociação com a rede ou com um par de sinalização.

Retornar valor

Nenhum

Comentários

Uma chamada para ProtocolClMakeCallComplete indica que o gerenciador de chamadas concluiu o processamento da solicitação do cliente para estabelecer uma conexão virtual com NdisClMakeCall.

Se a tentativa do cliente de estabelecer uma chamada de saída não for bem-sucedida ( o Status de entrada é qualquer coisa, exceto NDIS_STATUS_SUCCESS), ProtocolClMakeCallComplete deverá fazer o seguinte:

Libere ou prepare-se para reutilizar a área ProtocolPartyContext , se houver, e o buffer em CallParameters que o cliente alocou.
Desmarque a VC criada pelo cliente com uma chamada para NdisCoDeleteVc e libere ou prepare-se para reutilizar a área ProtocolVcContext alocada pelo cliente.

Caso contrário, ProtocolClMakeCallComplete deverá fazer o seguinte:

Verifique o membro Flags da estrutura em CallParameters para ver se CALL_PARAMETERS_CHANGED está definido, o que indica que o gerenciador de chamadas modificou os parâmetros de chamada fornecidos pelo cliente.
Nesse caso, examine os dados em CallParameters para determinar se eles são aceitáveis para essa conexão.
Por exemplo, o cliente pode reter os parâmetros de chamada em buffer para a VC ativa, salvar o NdisPartyHandle se esse for um VC de vários pontos e geralmente preparar o cliente para transferências subsequentes e outras operações na VC ativa se encontrar os parâmetros de chamada fornecidos satisfatórios.
Caso contrário, o protocolo de sinalização determina se o cliente pode tentar renegociar parâmetros de chamada aceitáveis com o gerenciador de chamadas.
Por exemplo, um gerenciador de chamadas específico pode permitir que seus clientes chamem NdisClModifyCallQoS uma ou mais vezes nessas circunstâncias.
Se os parâmetros de chamada modificados por CM forem inaceitáveis e uma renegociação adicional for impossível, ProtocolClMakeCallComplete deverá derrubar a chamada com NdisClCloseCall.
Nesse caso, ProtocolClMakeCallCompletenão deve tentar liberar recursos alocados pelo cliente no retorno de NdisClCloseCall , mas pode simplesmente retornar o controle. Em vez disso, o cliente deve liberar os recursos alocados (ou prepará-los para reutilização) em sua função ProtocolClCloseCallComplete .

Exemplos

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

PROTOCOL_CL_MAKE_CALL_COMPLETE MyClMakeCallComplete;

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

_Use_decl_annotations_
VOID
 MyClMakeCallComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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