PROTOCOL_CO_CREATE_VC função de retorno de chamada (ndis.h)
A função ProtocolCoCreateVc é uma função necessária que aloca recursos necessários para um gerenciador de chamadas ou cliente ativar e manter uma VC (conexão virtual).
Sintaxe
PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;
NDIS_STATUS ProtocolCoCreateVc(
[in] NDIS_HANDLE ProtocolAfContext,
[in] NDIS_HANDLE NdisVcHandle,
[out] PNDIS_HANDLE ProtocolVcContext
)
{...}
Parâmetros
[in] ProtocolAfContext
Especifica o identificador para uma área de contexto alocada por protocolo na qual o gerenciador de chamadas ou cliente mantém seu estado por aberto. O gerenciador de chamadas forneceu esse identificador de sua função ProtocolCmOpenAf . O cliente forneceu esse identificador quando chamou NdisClOpenAddressFamilyEx de sua função ProtocolCoAfRegisterNotify .
[in] NdisVcHandle
Especifica um identificador, fornecido pelo NDIS, que identifica exclusivamente essa conexão virtual. Esse identificador é opaco para o driver de protocolo e reservado para uso da biblioteca NDIS. No entanto, o gerenciador de chamadas e o cliente devem salvar esse identificador para passar chamadas subsequentes para funções NdisCo/Cl/Cm/MCmXxx que dizem respeito a essa VC.
[out] ProtocolVcContext
Especifica o identificador para uma área de contexto fornecida pelo protocolo na qual o gerenciador de chamadas ou o cliente mantém o estado sobre essa conexão virtual.
Retornar valor
ProtocolCoCreateVc retorna o status de suas operações como um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
|
Indica que o gerenciador de chamadas ou o cliente alocou e/ou inicializou com êxito todos os recursos necessários para estabelecer e manter uma conexão virtual. |
|
Indica que o gerenciador de chamadas ou o cliente não pôde alocar e/ou inicializar seus recursos para estabelecer e manter uma conexão virtual. |
|
Indica que o gerenciador de chamadas ou o cliente não pôde se definir em um estado em que pudesse estabelecer uma conexão virtual. Isso pode ser um valor retornado de erro propagado de outra rotina de biblioteca NDIS.
Nota Os gerenciadores de chamadas ou clientes não podem retornar NDIS_STATUS_PENDING de suas funções ProtocolCoCreateVc . O retorno pendente tornará essa conexão virtual inutilizável e a biblioteca NDIS chamará o cliente ou o gerenciador de chamadas para excluí-la.
|
Comentários
A função ProtocolCoCreateVc de um gerenciador de chamadas ou cliente é chamada sempre que o cliente ou gerenciador de chamadas correspondente, respectivamente, chama NdisCoCreateVc. Os clientes iniciam a criação de VCs no processo de configuração de suas chamadas de saída antes de chamarem NdisClMakeCall. Um gerenciador de chamadas inicia a criação de uma VC no processo de notificar seu cliente de que o CM recebeu uma oferta de chamada de entrada de um nó remoto que é direcionado para um SAP já registrado com o CM por esse cliente antes que o CM chame NdisCmDispatchIncomingCall.
ProtocolCoCreateVc executa todas as alocações necessárias de recursos dinâmicos e estruturas que o gerenciador de chamadas ou cliente exige para executar operações subsequentes em uma VC que será ativada. Esses recursos incluem, mas não se limitam a buffers de memória, estruturas de dados, eventos e outros recursos semelhantes. Gerenciadores de chamadas e clientes também devem inicializar quaisquer estruturas relevantes por VC que precisarão quando uma chamada for estabelecida.
Os drivers de protocolo orientados à conexão devem armazenar o identificador para a VC, especificada em NdisVcHandle, em sua área de estado por VC a ser usada em operações futuras nessa conexão virtual. O NdisVcHandle é o parâmetro necessário para o NdisCoXxx, NdisCmXxx e/ou NdisClXxx que um protocolo orientado a conexão chama posteriormente.
Quando um gerenciador de chamadas ou cliente aloca memória para seus próprios dados por VC e inicializa seu estado, o endereço dessa estrutura de dados deve ser definido no identificador antes de retornar o controle para NDIS. Para fazer isso, desreferenciar o identificador e armazenar um ponteiro para a área de dados alocada pelo protocolo como o valor do identificador. Por exemplo:
*ProtocolVcContext = SomeBuffer;
Se ProtocolCoCreateVc não puder alocar o recurso necessário para realizar operações de E/S de rede subsequentes, ele deverá liberar todos os recursos alocados para essa VC e retornar o controle com um status de NDIS_STATUS_RESOURCES.
Se ProtocolCoCreateVc tiver concluído suas operações necessárias e tiver tornado o gerenciador de chamadas ou o cliente pronto para realizar a inicialização de chamadas para essa conexão virtual, ProtocolCoCreateVc deverá retornar o controle o mais rápido possível com um status de NDIS_STATUS_SUCCESS.
As chamadas para ProtocolCoCreateVc são inerentemente síncronas por natureza. Ou seja, ProtocolCoCreateVcnão pode retornar NDIS_STATUS_PENDING.
Depois que a função ProtocolCoCreateVc de um gerenciador de chamadas retornar o controle, a função ProtocolCmMakeCall do gerenciador de chamadas será chamada para estabelecer uma conexão com um nó remoto. Os gerenciadores de chamadas não devem executar nenhuma ação no ProtocolCmMakeCall que realmente estabeleça uma chamada porque é possível que a VC seja destruída antes que uma chamada seja estabelecida devido a uma condição de erro em outro componente do NDIS orientado à conexão.
Depois que a função ProtocolCoCreateVc de um cliente retornar o controle, a função ProtocolClIncomingCall do cliente será notificada quando uma solicitação iniciada remotamente para se conectar em um SAP registrado anteriormente pelo cliente entrar pela rede.
Exemplos
Para definir uma função ProtocolCoCreateVc , 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 ProtocolCoCreateVc chamada "MyCoCreateVc", use o tipo PROTOCOL_CO_CREATE_VC conforme mostrado neste exemplo de código:
PROTOCOL_CO_CREATE_VC MyCoCreateVc;
Em seguida, implemente sua função da seguinte maneira:
_Use_decl_annotations_
NDIS_STATUS
MyCoCreateVc(
NDIS_HANDLE ProtocolAfContext,
NDIS_HANDLE NdisVcHandle,
PNDIS_HANDLE ProtocolVcContext
)
{...}
O tipo de função PROTOCOL_CO_CREATE_VC é 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_CO_CREATE_VC 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 ProtocolCoCreateVc (NDIS 5.1)) no Windows Vista. Com suporte para drivers NDIS 5.1 (consulte ProtocolCoCreateVc (NDIS 5.1)) no Windows XP. |
| Plataforma de Destino | Windows |
| Cabeçalho | ndis.h (inclua Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |