PROTOCOL_CM_OPEN_AF função de retorno de chamada (ndis.h)
A função ProtocolCmOpenAf é necessária. Essa função aloca recursos por aberto para um gerenciador de chamadas interagir com um cliente NDIS orientado a conexão que está abrindo a família de endereços.
Sintaxe
PROTOCOL_CM_OPEN_AF ProtocolCmOpenAf;
NDIS_STATUS ProtocolCmOpenAf(
[in] NDIS_HANDLE CallMgrBindingContext,
[in] PCO_ADDRESS_FAMILY AddressFamily,
[in] NDIS_HANDLE NdisAfHandle,
[out] PNDIS_HANDLE CallMgrAfContext
)
{...}
Parâmetros
[in] CallMgrBindingContext
Para um gerenciador de chamadas não integrado, CallMgrBindingContext especifica o identificador para uma área de contexto alocada pelo gerenciador de chamadas na qual os gerenciadores de chamadas mantêm suas informações de estado por associação. O gerenciador de chamadas forneceu esse identificador quando chamou NdisOpenAdapterEx.
Para um MCM (gerenciador de chamadas integrado), CallMgrBindingContext especifica o identificador para uma área de contexto alocada por miniporto na qual o miniporto mantém suas informações de estado por adaptador. O miniporto forneceu esse identificador em sua chamada NdisMSetAttributesEx (para drivers 5.x) ou sua chamada NdisMSetMiniportAttributes (para drivers 6.x).
[in] AddressFamily
Especifica a família de endereços que um cliente está abrindo. Essa família de endereços foi registrada pelo gerenciador de chamadas quando ela chamou NdisCmRegisterAddressFamilyEx.
[in] NdisAfHandle
Especifica um identificador, fornecido pelo NDIS, que identifica exclusivamente essa instância da família de endereços. Esse identificador é opaco para o gerenciador de chamadas e reservado para uso do sistema.
[out] CallMgrAfContext
Especifica o identificador para uma área de contexto fornecida pelo gerenciador de chamadas na qual o gerenciador de chamadas mantém o estado sobre essa abertura de uma família de endereços que ele fornece.
Retornar valor
ProtocolCmOpenAf retorna a status de suas operações como uma das seguintes:
| Código de retorno | Descrição |
|---|---|
|
Indica que o gerenciador de chamadas alocou e inicializou com êxito todos os recursos necessários para aceitar solicitações do cliente para essa família de endereços. |
|
Indica que a operação solicitada está sendo tratada de forma assíncrona. O gerenciador de chamadas deve chamar NdisCmOpenAddressFamilyComplete quando tiver concluído todas as operações open-AF para indicar ao NDIS (e ao cliente) que as operações foram concluídas. |
|
Indica que o gerenciador de chamadas não pôde concluir as operações necessárias devido à falta de recursos do sistema disponíveis, como memória. |
|
Indica que o gerenciador de chamadas não pôde se definir em um estado em que ele pode aceitar solicitações do cliente para operar nessa família de endereços. Isso pode ser um erro status propagado de outra função de biblioteca NDIS ou qualquer erro status determinado apropriado pelo gravador de driver. |
Comentários
ProtocolCmOpenAf executa todas as alocações necessárias de recursos dinâmicos e estruturas que o gravador do gerenciador de chamadas considera necessárias para executar operações em nome do cliente que está abrindo uma instância dessa família de endereços. 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 dados por abertura relevantes antes de retornar o controle para o NDIS.
Quando um gerenciador de chamadas aloca sua área de estado por aberto, o endereço da área de estado deve ser definido no identificador CallMgrAfContext antes de retornar o controle para o NDIS. Para fazer isso, desreferenciar CallMgrAfContext e armazenar um ponteiro para a área de dados como o valor do identificador. Por exemplo:
*CallMgrAfContext = SomeBuffer;
Se ProtocolCmOpenAf não puder alocar os recursos abertos necessários para realizar solicitações subsequentes em nome do cliente que abre essa família de endereços, ele deverá liberar todos os recursos alocados para o controle aberto e de retorno para o NDIS com NDIS_STATUS_RESOURCES.
Se ProtocolCmOpenAf tiver concluído suas operações necessárias e o CM estiver pronto para aceitar solicitações do cliente, ProtocolCmOpenAf deverá retornar o controle o mais rápido possível com um status de NDIS_STATUS_SUCCESS.
Exemplos
Para definir uma função ProtocolCmOpenAf , 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 ProtocolCmOpenAf chamada "MyCmOpenAf", use o tipo PROTOCOL_CM_OPEN_AF conforme mostrado neste exemplo de código:
PROTOCOL_CM_OPEN_AF MyCmOpenAf;
Em seguida, implemente sua função da seguinte maneira:
_Use_decl_annotations_
NDIS_STATUS
MyCmOpenAf(
NDIS_HANDLE CallMgrBindingContext,
PCO_ADDRESS_FAMILY AddressFamily,
NDIS_HANDLE NdisAfHandle,
PNDIS_HANDLE CallMgrAfContext
)
{...}
O tipo de função PROTOCOL_CM_OPEN_AF é 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_OPEN_AF 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 ProtocolCmOpenAf (NDIS 5.1)) no Windows Vista. Com suporte para drivers NDIS 5.1 (consulte ProtocolCmOpenAf (NDIS 5.1)) no Windows XP. |
| Plataforma de Destino | Windows |
| Cabeçalho | ndis.h (inclua Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |