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

Artigo
02/07/2025

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, essa função de de ProtocolClMakeCallComplete do driver de protocolo pode simplesmente retornar o controle.

Observação 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 foi bem-sucedida. Consequentemente, o cliente pode continuar a fazer transferências no VC ativo 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 propagou esse status de falha determinado pelo driver 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 o VC para sua chamada de saída.

[in, optional] NdisPartyHandle

Se status for NDIS_STATUS_SUCCESS e o cliente tiver criado um 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.

Valor de retorno

Nenhum

Observações

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 (a entrada status for qualquer coisa, exceto NDIS_STATUS_SUCCESS), ProtocolClMakeCallComplete deverá fazer o seguinte:

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

Caso contrário, ProtocolClMakeCallComplete deve fazer o seguinte:

Verifique o Flags membro 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 manter os parâmetros de chamada em buffer para o VC ativo, salvar o NdisPartyHandle se esse for um VC de vários pontos e geralmente deixar o cliente pronto para transferências subsequentes e outras operações no VC ativo se achar 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 nova renegociação for impossível, ProtocolClMakeCallComplete deverá derrubar a chamada com NdisClCloseCall.
Nesse caso, ProtocolClMakeCallComplete não deve tentativa de 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 de

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 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 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
de cliente com suporte mínimo	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.
da Plataforma de Destino	Windows
cabeçalho	ndis.h (inclua Ndis.h)
IRQL	<= DISPATCH_LEVEL