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

Artigo
08/07/2023

A função ProtocolClIncomingCall é usada por clientes orientados a conexão que aceitam chamadas de entrada. Esses clientes devem ter funções ProtocolClIncomingCall . Caso contrário, a função ProtocolClIncomingCall registrada de um driver de protocolo pode simplesmente retornar NDIS_STATUS_NOT_SUPPORTED.

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

Sintaxe

PROTOCOL_CL_INCOMING_CALL ProtocolClIncomingCall;

NDIS_STATUS ProtocolClIncomingCall(
  [in]      NDIS_HANDLE ProtocolSapContext,
  [in]      NDIS_HANDLE ProtocolVcContext,
  [in, out] PCO_CALL_PARAMETERS CallParameters
)
{...}

Parâmetros

[in] ProtocolSapContext

Especifica o identificador que o cliente forneceu originalmente quando registrou o SAP, que o gerenciador de chamadas correspondeu a essa oferta de chamada de entrada.

[in] ProtocolVcContext

Especifica o identificador para a área de contexto por VC do cliente, anteriormente retornada ao NDIS por sua função ProtocolCoCreateVc .

[in, out] CallParameters

Ponteiro para um buffer, formatado como uma estrutura CO_CALL_PARAMETERS , que contém os parâmetros de chamada para essa chamada oferecida.

Retornar valor

ProtocolClIncomingCall pode retornar um dos seguintes códigos de status:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	O cliente aceitou a oferta de chamada de entrada.
NDIS_STATUS_PENDING	O cliente está tratando essa solicitação de forma assíncrona e chamará o Função NdisClIncomingCallComplete quando a operação de fechamento é concluída.
NDIS_STATUS_XXX	O cliente rejeitou a oferta de chamada de entrada por algum motivo determinado pelo driver.

Comentários

Uma chamada para ProtocolClIncomingCall indica que o gerenciador de chamadas recebeu uma solicitação pela rede de um par de sinalização para estabelecer uma conexão com esse cliente. Ou seja, a solicitação para configurar essa conexão foi direcionada para um SAP registrado anteriormente com o gerenciador de chamadas por esse cliente.

Dependendo do protocolo de sinalização com suporte do gerenciador de chamadas, ProtocolClIncomingCall pode modificar os parâmetros de tráfego como parte do processo de negociação da aceitação de uma oferta de chamada de entrada e/ou, se o gerenciador de chamadas der suporte a QoS, a especificação de qualidade do serviço em CallParameters . O cliente deve copiar todas as informações necessárias posteriormente dessa estrutura em buffer se aceitar a chamada oferecida.

Supondo que o gerenciador de chamadas encontre as modificações do cliente, se houver, aceitáveis, o NDIS chama a função ProtocolClIncomingCallConnected do cliente quando se torna possível que as transferências ocorram na VC ativa que representa a conexão com o cliente no nó remoto que iniciou originalmente a oferta de chamada. Se o cliente retornar parâmetros de chamada modificados que são inaceitáveis, o gerenciador de chamadas poderá derrubar a VC que criou para essa oferta, causando assim chamadas para o cliente As funções ProtocolClIncomingCloseCall e ProtocolCoDeleteVc .

Exemplos

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

PROTOCOL_CL_INCOMING_CALL MyClIncomingCall;

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

_Use_decl_annotations_
NDIS_STATUS
 MyClIncomingCall(
    NDIS_HANDLE  ProtocolSapContext,
    NDIS_HANDLE  ProtocolVcContext,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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