PROTOCOL_CM_MAKE_CALL função de retorno de chamada (ndis.h)
A função ProtocolCmMakeCall é uma função necessária que configura parâmetros específicos de mídia para uma VC (conexão virtual) e ativa a conexão virtual.
Sintaxe
PROTOCOL_CM_MAKE_CALL ProtocolCmMakeCall;
NDIS_STATUS ProtocolCmMakeCall(
[in] NDIS_HANDLE CallMgrVcContext,
[in, out] PCO_CALL_PARAMETERS CallParameters,
[in, optional] NDIS_HANDLE NdisPartyHandle,
[out, optional] PNDIS_HANDLE CallMgrPartyContext
)
{...}
Parâmetros
[in] CallMgrVcContext
Especifica o identificador para uma área de contexto alocada pelo gerenciador de chamadas na qual os gerenciadores de chamadas mantêm seu estado por VC. O gerenciador de chamadas forneceu esse identificador para o NDIS de sua função ProtocolCoCreateVc .
[in, out] CallParameters
Ponteiro para uma estrutura de CO_CALL_PARAMETERS que contém os parâmetros, especificados por um cliente orientado a conexão, para essa chamada de saída.
[in, optional] NdisPartyHandle
Especifica um identificador, fornecido pelo NDIS, que identifica exclusivamente a parte inicial na conexão virtual de vários pontos. Esse identificador é opaco para o gerenciador de chamadas e reservado para uso da biblioteca NDIS. Esse identificador será NULL se o cliente não estiver configurando uma chamada de vários pontos de saída.
[out, optional] CallMgrPartyContext
No retorno, especifica um identificador para uma área de contexto fornecida pelo gerenciador de chamadas na qual o gerenciador de chamadas mantém o estado sobre a parte inicial na chamada de vários pontos. Se NdisPartyHandle for NULL, esse identificador deverá ser definido como NULL.
Retornar valor
ProtocolCmMakeCall retorna o status de suas operações como um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
|
Indica que o gerenciador de chamadas alocou com êxito os recursos necessários para fazer a chamada e foi capaz de ativar a conexão virtual com o driver de miniporto. |
|
Indica que o gerenciador de chamadas concluirá a solicitação para fazer uma chamada de forma assíncrona. Quando o gerenciador de chamadas tiver concluído todas as operações para fazer uma chamada, ele deverá chamar NdisCmMakeCallComplete para sinalizar ao NDIS que essa chamada foi concluída. |
|
Indica que o gerenciador de chamadas não pôde alocar e/ou inicializar seus recursos para ativar a conexão virtual conforme solicitado pelo cliente. |
|
Indica que o gerenciador de chamadas não pôde ativar uma conexão virtual porque o chamador solicitou recursos inválidos ou indisponíveis nos parâmetros de chamada especificados em CallParameters . |
Comentários
Se ProtocolCmMakeCall receber um NdisPartyHandle explícito, essa VC foi criada pelo cliente para uma chamada de vários pontos. O gerenciador de chamadas deve alocar e inicializar todos os recursos necessários para manter as informações de estado e controlar uma chamada de vários pontos. Esses recursos incluem, mas não se limitam a buffers de memória, estruturas de dados, eventos e outros recursos semelhantes. Se o gerenciador de chamadas não puder alocar ou inicializar os recursos necessários para suas áreas de estado, ele deverá retornar o controle para o NDIS com NDIS_STATUS_RESOURCES.
ProtocolCmMakeCall comunica-se com dispositivos de controle de rede ou outros atores específicos de mídia, conforme necessário, para fazer uma conexão entre o nó local e um nó remoto com base nos parâmetros de chamada especificados em CallParameters . Essas ações podem incluir, mas não se limitam a, comunicação com a alternância de hardware, comunicações com uma estação de controle de rede ou outras ações conforme apropriado para o meio de rede.
Se um gerenciador de chamadas for necessário para a comunicação com o hardware de rede (como um comutador de rede), ele deverá usar uma conexão virtual com o dispositivo de controle de rede que ele estabeleceu em sua função ProtocolBindAdapterEx . Os gerenciadores de chamadas se comunicam com o hardware de rede por meio do driver de miniporta chamando NdisCoSendNetBufferLists. Os drivers de miniport com suporte integrado ao gerenciamento de chamadas não chamarão NdisCoSendNetBufferLists, mas transmitirão os dados por conta própria.
Depois que um gerenciador de chamadas tiver feito toda a comunicação necessária com seu hardware de rede conforme exigido por seu meio, os gerenciadores de chamadas deverão chamar NdisCmActivateVc.
Se essa chamada for uma chamada de vários pontos, depois que o gerenciador de chamadas tiver se comunicado com o hardware de rede, verificado parâmetros de chamada e alocado e inicializado seus dados de estado por parte, o endereço de seu bloco de estado deverá ser definido no identificador CallMgrPartyContext antes de retornar o controle para o NDIS. O identificador é definido desreferenciando o identificador e armazenando um ponteiro para o bloco de estado como o valor do identificador. Por exemplo:
*CallMgrPartyContext = SomeBuffer ;
Se ProtocolCmMakeCall tiver concluído as operações necessárias para sua rede e a VC tiver sido ativada com êxito por meio de NdisCmActivateVc, ProtocolCmMakeCall deverá retornar o controle o mais rápido possível com um status de STATUS_SUCCESS.
Depois que ProtocolCmMakeCall retornar o controle para o NDIS, o gerenciador de chamadas deverá esperar não executar mais nenhuma ação nessa chamada para configurá-lo. ProtocolCmMakeCall é responsável por estabelecer a conexão para que o cliente possa fazer transferências de dados pela rede nesta VC. No entanto, o gerenciador de chamadas pode ser chamado posteriormente para modificar a qualidade de serviço da chamada, para adicionar ou remover partes se esta for uma VC de vários pontos e, eventualmente, para encerrar essa chamada.
Exemplos
Para definir uma função ProtocolCmMakeCall , 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 ProtocolCmMakeCall chamada "MyCmMakeCall", use o tipo PROTOCOL_CM_MAKE_CALL conforme mostrado neste exemplo de código:
PROTOCOL_CM_MAKE_CALL MyCmMakeCall;
Em seguida, implemente sua função da seguinte maneira:
_Use_decl_annotations_
NDIS_STATUS
MyCmMakeCall(
NDIS_HANDLE CallMgrVcContext,
PCO_CALL_PARAMETERS CallParameters,
NDIS_HANDLE NdisPartyHandle,
PNDIS_HANDLE CallMgrPartyContext
)
{...}
O tipo de função PROTOCOL_CM_MAKE_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_CM_MAKE_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 ProtocolCmMakeCall (NDIS 5.1)) no Windows Vista. Com suporte para drivers NDIS 5.1 (consulte ProtocolCmMakeCall (NDIS 5.1)) no Windows XP. |
| Plataforma de Destino | Windows |
| Cabeçalho | ndis.h (inclua Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |