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

Artigo
08/07/2023

A função ProtocolCmRegisterSap é uma função necessária que é chamada pelo NDIS para solicitar que um gerenciador de chamadas registre um SAP (ponto de acesso de serviço) em nome de um cliente orientado a conexões.

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

Sintaxe

PROTOCOL_CM_REG_SAP ProtocolCmRegSap;

NDIS_STATUS ProtocolCmRegSap(
  [in]  NDIS_HANDLE CallMgrAfContext,
  [in]  PCO_SAP Sap,
  [in]  NDIS_HANDLE NdisSapHandle,
  [out] PNDIS_HANDLE CallMgrSapContext
)
{...}

Parâmetros

[in] CallMgrAfContext

Especifica o identificador para uma área de contexto alocada pelo gerenciador de chamadas na qual o gerenciador de chamadas mantém seu estado de AF por aberto. O gerenciador de chamadas forneceu esse identificador ao NDIS de sua função ProtocolCmOpenAf .

[in] Sap

Ponteiro para uma estrutura de CO_SAP específica de mídia que contém o SAP específico que um cliente orientado à conexão está registrando.

[in] NdisSapHandle

Especifica um identificador, fornecido pelo NDIS, que identifica exclusivamente esse SAP. Esse identificador é opaco para o gerenciador de chamadas e reservado para uso da biblioteca NDIS.

[out] CallMgrSapContext

No retorno, especifica o identificador para uma área de contexto fornecida pelo gerenciador de chamadas na qual o gerenciador de chamadas mantém o estado sobre esse SAP.

Retornar valor

ProtocolCmRegisterSap retorna a status de suas operações como uma das seguintes:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	Indica que o gerenciador de chamadas alocou e/ou inicializou com êxito todos os recursos necessários para registrar e manter o SAP. Além disso, também indica que o SAP foi registrado com êxito conforme exigido pela mídia de rede à qual o gerenciador de chamadas dá suporte.
NDIS_STATUS_PENDING	Indica que o gerenciador de chamadas concluirá o processamento dessa solicitação de forma assíncrona. Os gerentes de chamadas devem chamar NdisCmRegisterSapComplete quando todo o processamento tiver sido concluído para sinalizar ao NDIS que o registro foi concluído.
NDIS_STATUS_RESOURCES	Indica que o gerenciador de chamadas não pôde alocar e/ou inicializar seus recursos necessários para registrar o SAP em nome do cliente orientado à conexão.
NDIS_STATUS_INVALID_DATA	Indica que a especificação fornecida no Sap é inválida ou não tem suporte.
NDIS_STATUS_XXX	Indica que o gerenciador de chamadas encontrou um erro ao tentar registrar o SAP para o cliente orientado à conexão. O código de retorno é apropriado para o erro e pode ser um código de retorno propagado de outra função de biblioteca NDIS.

Comentários

ProtocolCmMakeCall comunica-se com dispositivos de controle de rede ou outros agentes específicos de mídia, conforme necessário, para registrar o SAP, conforme especificado em Sap, na rede para um cliente orientado a conexão. Essas ações podem incluir, mas não se limitam à comunicação com a alternância de hardware, comunicação com uma estação de controle de rede ou outras ações apropriadas para a mídia de rede.

Se um gerenciador de chamadas for necessário para se comunicar com agentes de controle de rede (em outras palavras, um comutador de rede), ele deverá usar uma conexão virtual com o agente de controle de rede que estabeleceu em sua função ProtocolBindAdapterEx . Os gerenciadores de chamadas autônomos se comunicam por meio do driver de miniporto subjacente chamando NdisCoSendNetBufferLists. Drivers de miniport com suporte integrado de gerenciamento de chamadas nunca chamam NdisCoSendNetBufferLists. Em vez disso, eles transmitem os dados diretamente pela rede.

Além disso, ProtocolCmRegisterSap deve executar todas as alocações necessárias de recursos dinâmicos e estruturas que o gerenciador de chamadas precisa para manter informações de estado sobre o SAP em nome do cliente orientado para conexão. Esses recursos incluem, mas não se limitam a buffers de memória, estruturas de dados, eventos e outros recursos semelhantes. Um gerenciador de chamadas também deve inicializar todos os recursos alocados antes de retornar o controle para o NDIS. Os gerenciadores de chamadas devem armazenar o identificador fornecido pelo NDIS que identifica o SAP, fornecido em NdisSapHandle, em sua área de contexto para uso futuro.

Se ProtocolCmRegisterSap retornar NDIS_STATUS_SUCCESS, ele deverá, depois de alocar a área de estado por SAP, definir o endereço dessa área de estado em CallMgrSapContext antes de retornar o controle para NDIS. Para fazer isso, desreferenciar CallMgrSapContext e armazenar um ponteiro para a área de dados como o valor do identificador. Por exemplo:

*CallMgrSapContext = SomeBuffer ;

Se o SAP já estiver registrado por outro cliente orientado a conexão, o gerenciador de chamadas deverá falhar na solicitação e retornar NDIS_STATUS_INVALID_DATA.

Depois que um gerenciador de chamadas tiver registrado um SAP em nome de um cliente orientado a conexão, ele notificará o cliente de uma oferta de chamada de entrada direcionada a esse SAP chamando NdisCmDispatchIncomingCall.

Exemplos

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

PROTOCOL_CM_REG_SAP MyCmRegisterSap;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCmRegisterSap(
    NDIS_HANDLE  CallMgrAfContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle,
    PNDIS_HANDLE  CallMgrSapContext
    )
  {...}

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