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

Artigo
03/01/2024

A função ProtocolClAddPartyComplete é necessária para clientes NDIS orientados à conexão que configuram conexões de vários pontos. Esses clientes devem ter funções ProtocolClAddPartyComplete para concluir as operações assíncronas iniciadas com NdisClAddParty. Caso contrário, a função ProtocolClAddPartyComplete do driver de protocolo pode simplesmente retornar o controle.

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

Sintaxe

PROTOCOL_CL_ADD_PARTY_COMPLETE ProtocolClAddPartyComplete;

void ProtocolClAddPartyComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolPartyContext,
  [in] NDIS_HANDLE NdisPartyHandle,
  [in] PCO_CALL_PARAMETERS CallParameters
)
{...}

Parâmetros

[in] Status

Especifica a status final da operação de suplemento iniciada pelo cliente, que pode ser uma das seguintes:

NDIS_STATUS_SUCCESS

A parte especificada foi adicionada à VC de vários pontos ativos do cliente.

NDIS_STATUS_RESOURCES

O NDIS não pôde alocar recursos suficientes para acompanhar a nova parte.

NDIS_STATUS_FAILURE

O cliente passou um NdisVcHandle inválido para NdisClAddParty.

NDIS_STATUS_XXX

A função ProtocolCmAddParty do gerenciador de chamadas retornou um valor determinado por CM para indicar por que ele não pôde adicionar a parte à VC.

[in] ProtocolPartyContext

Especifica o identificador fornecido pelo cliente originalmente passado para NdisClAddParty.

[in] NdisPartyHandle

Se Status for NDIS_STATUS_SUCCESS, esse identificador fornecido pelo NDIS representará a associação entre o gerenciador de chamadas e o cliente em relação a essa parte. Caso contrário, a tentativa de adicionar uma parte falhou e o cliente deve considerar esse parâmetro um identificador inválido.

[in] CallParameters

Ponteiro para uma estrutura do tipo CO_CALL_PARAMETERS, originalmente configurada pelo cliente para sua chamada para NdisClAddParty , mas possivelmente modificada posteriormente pelo gerenciador de chamadas.

Retornar valor

Nenhum

Comentários

Uma chamada para ProtocolClAddPartyComplete indica a conclusão da operação assíncrona iniciada quando o cliente chamou NdisClAddParty. Se o Status de entrada for definido como algo diferente de NDIS_STATUS_SUCCESS, ProtocolClAddPartyComplete poderá liberar ou reutilizar os buffers alocados pelo cliente em ProtocolPartyContext e em CallParameters .

Se a tentativa de adicionar uma parte tiver êxito, ProtocolClAddPartyComplete deverá salvar a entrada NdisPartyHandle para chamadas subsequentes às funções da biblioteca NDIS relativas a essa parte na área ProtocolPartyContext do cliente. Por exemplo, o cliente deve passar esse identificador em uma chamada subsequente para NdisClDropParty eventualmente, a menos que a parte remota que ele representa feche sua conexão primeiro.

A estrutura em CallParameters originalmente foi alocada e inicializada pelo cliente, que passou esse ponteiro para
NdisClAddParty. No entanto, o gerenciador de chamadas pode ter modificado os valores fornecidos pelo cliente para refletir os resultados da negociação do CM com a rede ou com um par de sinalização durante o processamento da solicitação de parte do cliente. Para determinar se o gerenciador de chamadas fez modificações, ProtocolClAddPartyComplete pode marcar o membro Flags dessa estrutura para saber se CALL_PARAMETERS_CHANGED está definido. Nesse caso, ProtocolClAddPartyComplete deve atualizar o estado por parte que o cliente mantém para essa chamada em ProtocolPartyContext , a menos que considere inaceitáveis as modificações do CM. O protocolo de sinalização específico determina o que o cliente pode fazer nesse caso. Normalmente, um cliente chama NdisClDropParty se achar os parâmetros de chamada modificados por CM inaceitáveis.

Dependendo do protocolo de sinalização do gerenciador de chamadas, os parâmetros de tráfego em CallParameters podem ser idênticos para todas as partes em qualquer conexão multiponto específica. Ou seja, como o cliente desse gerenciador de chamadas adiciona partes em uma conexão de vários pontos que o cliente configurou originalmente com NdisClMakeCall, ele pode fornecer apenas o endereço de destino de cada parte e deixar os parâmetros de tráfego como configurados originalmente para a VC de vários pontos sempre que chamar NdisClAddParty.

Exemplos

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

PROTOCOL_CL_ADD_PARTY_COMPLETE MyClAddPartyComplete;

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

_Use_decl_annotations_
VOID
 MyClAddPartyComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolPartyContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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