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

Artigo
08/07/2023

Um cliente NDIS orientado a conexão que aceita chamadas de entrada deve ter uma função ProtocolClRegisterSapComplete para concluir as operações assíncronas iniciadas com NdisClRegisterSap. Caso contrário, a função ProtocolClRegisterSapComplete registrada de um driver de protocolo pode simplesmente retornar o controle.

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

Sintaxe

PROTOCOL_CL_REGISTER_SAP_COMPLETE ProtocolClRegisterSapComplete;

void ProtocolClRegisterSapComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolSapContext,
  [in] PCO_SAP Sap,
  [in] NDIS_HANDLE NdisSapHandle
)
{...}

Parâmetros

[in] Status

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

NDIS_STATUS_SUCCESS

O SAP foi registrado com o NDIS e o gerenciador de chamadas, que chamará posteriormente NdisCmDispatchIncomingCall sempre que recebe uma oferta de chamada de entrada direcionada para o SAP determinado, fazendo com que o NDIS chame o cliente Função ProtocolClIncomingCall .

NDIS_STATUS_RESOURCES

O NDIS ou o gerenciador de chamadas não pôde alocar e/ou inicializar os recursos necessários para registrar e manter o SAP.

NDIS_STATUS_INVALID_DATA

O cliente forneceu uma especificação inválida no Sap para o NDIS, que ele encaminhou para a função ProtocolCmRegisterSap do gerenciador de chamadas para validação.

NDIS_STATUS_XXX

O gerenciador de chamadas encontrou um erro ao tentar registrar o SAP e o NDIS determinados propagaram essa falha determinada por CM status para o cliente.

[in] ProtocolSapContext

Especifica o identificador para a área de contexto por SAP do cliente, que o cliente originalmente forneceu ao NDIS quando chamou NdisClRegisterSap. Se o registro for bem-sucedido, o NDIS manterá esse identificador de contexto e o usará posteriormente em chamadas para a função ProtocolClIncomingCall do cliente relativa a esse SAP.

[in] Sap

Ponteiro para o buffer alocado pelo cliente que contém a especificação para o SAP a ser aberto. O cliente originalmente passou esse ponteiro para NdisClRegisterSap.

[in] NdisSapHandle

Se Status for NDIS_STATUS_SUCCESS, especificará um identificador válido fornecido pelo NDIS para esse SAP registrado, efetivamente uma associação estabelecida com o NDIS entre o cliente e um gerenciador de chamadas específico para o SAP especificado pelo cliente. Caso contrário, esse parâmetro será NULL. O cliente deve salvar um identificador válido, preferencialmente em sua área ProtocolSapContext , para uma eventual chamada para NdisClDeregisterSap.

Retornar valor

Nenhum

Comentários

O NDIS chama ProtocolClRegisterSapComplete para indicar que a chamada anterior do cliente para NdisClRegisterSap foi processada pelo NDIS e, se o NDIS não falhou na chamada, pelo gerenciador de chamadas com o qual o cliente compartilha o NdisAfHandle que ele passou para NdisClRegisterSap.

Para receber chamadas de entrada por meio de uma NIC orientada a conexão, o de um cliente ProtocolCoAfRegisterNotify ou A função ProtocolClOpenAfCompleteEx geralmente registra um ou mais SAPs com o gerenciador de chamadas.

Para registrar cada SAP, o cliente chama NdisClRegisterSap, passando o NdisAfHandle que identifica o gerenciador de chamadas do qual o cliente deseja receber notificações de chamadas de entrada e o NDIS retorna ao cliente um NdisSapHandle para o SAP registrado se a chamada do cliente para NdisClRegisterSap for bem-sucedida. ProtocolClRegisterSapComplete deve salvar cada NdisSapHandle válido, geralmente na área de ProtocolSapContext por SAP do cliente para que ele possa liberar o SAP mais tarde com NdisClDeregisterSap.

O formato de um SAP é específico para o gerenciador de chamadas. Se o gerenciador de chamadas não reconhecer o SAP que o cliente está tentando registrar ou se o SAP especificado já estiver em uso, o gerenciador de chamadas poderá falhar no registro sap. ProtocolClRegisterSapComplete deve marcar o Status de entrada para NDIS_STATUS_SUCCESS antes de prosseguir. Se a tentativa de registrar o SAP falhou,
ProtocolClRegisterSapComplete pode liberar a área de contexto por SAP e o buffer no Sap que o cliente alocou ou prepará-los para reutilização em outra chamada para NdisClRegisterSap.

Um cliente pode receber chamadas de entrada em um SAP mesmo enquanto o registro sap ainda estiver pendente, ou seja, antes que sua função ProtocolClRegisterSapComplete seja chamada.

Exemplos

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

PROTOCOL_CL_REGISTER_SAP_COMPLETE MyClRegisterSapComplete;

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

_Use_decl_annotations_
VOID
 MyClRegisterSapComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolSapContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle
    )
  {...}

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