função de retorno de chamada PROTOCOL_BIND_ADAPTER_EX (ndis.h)
O NDIS chama a função ProtocolBindAdapterEx de um driver de protocolo para solicitar que o driver se associe a um adaptador de miniport.
Sintaxe
PROTOCOL_BIND_ADAPTER_EX ProtocolBindAdapterEx;
NDIS_STATUS ProtocolBindAdapterEx(
[in] NDIS_HANDLE ProtocolDriverContext,
[in] NDIS_HANDLE BindContext,
[in] PNDIS_BIND_PARAMETERS BindParameters
)
{...}
Parâmetros
[in] ProtocolDriverContext
Um identificador para uma área de contexto alocada pelo driver em que o driver mantém informações de estado e configuração. O driver de protocolo passou essa área de contexto para o Função NdisRegisterProtocolDriver .
[in] BindContext
O identificador que identifica a área de contexto do NDIS para essa operação de associação.
[in] BindParameters
Um ponteiro para uma estrutura NDIS_BIND_PARAMETERS que o NDIS criou.
Retornar valor
ProtocolBindAdapterEx retorna um dos seguintes valores de status:
| Código de retorno | Descrição |
|---|---|
|
ProtocolBindAdapterEx concluiu com êxito a associação ao adaptador de miniporto subjacente. |
|
ProtocolBindAdapterEx não concluiu a operação de associação e a operação será concluída de forma assíncrona. O driver de protocolo deve chamar o A função NdisCompleteBindAdapterEx quando a operação é concluída. |
|
ProtocolBindAdapterEx não pôde alocar os recursos necessários ao driver para realizar operações de E/S de rede. |
|
Falha na tentativa do driver de protocolo de configurar uma associação. Normalmente, esse status de erro é propagado de uma função NdisXxx ou de uma rotina de suporte no modo kernel. |
Comentários
ProtocolBindAdapterEx é uma função necessária. O NDIS chama ProtocolBindAdapterEx para executar operações de associação sempre que um adaptador de miniporto subjacente, ao qual o driver de protocolo pode ser associado, fica disponível.
ProtocolBindAdapterEx aloca memória suficiente para manter as informações de contexto de associação e chama a função NdisOpenAdapterEx para se associar ao adaptador de miniporto subjacente. ProtocolBindAdapterEx passa um ponteiro para as informações de contexto de associação no parâmetro ProtocolBindingContext de NdisOpenAdapterEx. ProtocolBindAdapterEx passa o valor no membro AdapterName de seu parâmetro BindParameters como o membro AdapterName do parâmetro OpenParameters de NdisOpenAdapterEx.
Antes que o driver chame NdisOpenAdapterEx, o driver pode passar o ponteiro em BindParameters para a função NdisOpenConfigurationEx para ler os parâmetros de configuração associados a um adaptador de miniport.
Depois de abrir o adaptador de miniporto com êxito, o driver pode passar o identificador do parâmetro NdisHandle de NdisOpenAdapterEx para NdisOpenConfigurationEx para obter um identificador para o local do Registro em que os parâmetros de configuração de uma associação de protocolo são armazenados.
ProtocolBindAdapterEx passa NdisOpenAdapterEx um ponteiro para uma matriz de valores de tipo médio que lista os tipos de mídia que o driver de protocolo pode dar suporte. Essa lista é um subconjunto dos tipos de NDIS_MEDIUM . O NDIS indica o tipo médio selecionado no parâmetro SelectedMediumIndex da estrutura em OpenParameters.
Se NdisOpenAdapterEx retornar um erro status, ProtocolBindAdapterEx retornará esse erro status, liberará todos os recursos por associação alocados pelo driver de protocolo e retornará o controle imediatamente.
Se NdisOpenAdapterEx retornar NDIS_STATUS_SUCCESS, ProtocolBindAdapterEx poderá alocar os recursos restantes que o driver de protocolo precisa para realizar e/S de rede na associação. O driver também pode configurar qualquer informação de contexto específica de associação que o driver usa para rastrear operações de E/S de rede.
Se NdisOpenAdapterEx retornar NDIS_STATUS_PENDING, o NDIS chamará o driver de protocolo Função ProtocolOpenAdapterCompleteEx após a conclusão da operação aberta. ProtocolOpenAdapterCompleteEx pode concluir as operações de associação. ProtocolBindAdapterEx pode armazenar o identificador BindContext na área de contexto de associação. O NDIS passa ProtocolBindingContext como um parâmetro de entrada para a função ProtocolOpenAdapterCompleteEx do driver.
Se NdisOpenAdapterEx retornar NDIS_STATUS_PENDING, o NDIS definirá o membro SelectedMediumIndex da estrutura no parâmetro OpenParameters e o valor do parâmetro NdisBindingHandle após o retorno de NdisOpenAdapterEx . O NDIS define esses valores antes de chamar ProtocolOpenAdapterCompleteEx. Portanto, o driver de protocolo deve armazenar a estrutura de parâmetros abertos e o identificador de associação de protocolo na área de contexto em ProtocolBindingContext(ou qualquer local válido até que o NDIS chame ProtocolOpenAdapterCompleteEx).
Um driver de protocolo não pode fazer solicitações OID em uma associação até que a operação aberta seja concluída. Como a associação está no estado pausado após a conclusão da operação aberta, o driver de protocolo não pode fazer solicitações de envio até que o NDIS reinicie a associação.
Depois que a operação aberta for concluída, ProtocolBindAdapterEx poderá retornar NDIS_STATUS_SUCCESS para concluir a operação de associação. ProtocolBindAdapterEx pode retornar NDIS_STATUS_PENDING para adiar a conclusão das operações de associação para um momento posterior. Se ProtocolBindAdapterEx retornar NDIS_STATUS_PENDING, o driver deverá chamar o Função NdisCompleteBindAdapterEx após a conclusão da operação de associação.
Os drivers de protocolo devem usar a estrutura NDIS_BIND_PARAMETERS para determinar os recursos do adaptador de miniporto subjacente. Depois que a operação aberta for concluída, dependendo da mídia subjacente, o driver de protocolo poderá chamar a função NdisOidRequest para consultar o driver de miniporto subjacente (ou NDIS) sobre recursos adicionais do adaptador de miniport. Para obter mais informações sobre solicitações OID, consulte Solicitações de OID do Driver de Protocolo.
O NDIS pode chamar um driver de protocolo Função ProtocolReceiveNetBufferLists depois que o driver configura um filtro de pacote para a associação com o OID_GEN_CURRENT_PACKET_FILTER OID. Se o adaptador de miniporto subjacente não usar um filtro de pacote para pacotes de entrada, as indicações de recebimento serão habilitadas após a conclusão da operação aberta. Os drivers de protocolo podem receber status indicações na função ProtocolStatusEx após a conclusão da operação aberta.
Cada driver de protocolo deve alocar pools de estrutura de NET_BUFFER e NET_BUFFER_LIST suficientes. O driver aloca descritores de dados de rede desses pools para operações de envio subsequentes.
Se ProtocolBindAdapterEx não puder alocar os recursos necessários para realizar operações de E/S de rede subsequentes, ele deverá liberar todos os recursos já alocados e retornar um valor de erro apropriado.
O NDIS chama um driver de protocolo Função ProtocolUnbindAdapterEx para solicitar que o driver seja desassociado de um adaptador de miniporte subjacente.
Se o driver de protocolo abrir com êxito o adaptador de miniporto, mas a operação de associação falhar (por exemplo, como resultado de uma solicitação OID com falha), o driver deverá fechar o adaptador de miniporte de dentro do contexto de ProtocolBindAdapterEx ou ProtocolUnbindAdapterEx. Por exemplo, o driver chama NdisCloseAdapterEx de ProtocolBindAdapterEx e aguarda a conclusão da operação de fechamento antes que o driver retorne de ProtocolBindAdapterEx. Como alternativa, se o driver retornou NDIS_STATUS_PENDING de ProtocolBindAdapterEx, o driver poderá chamar a função NdisUnbindAdapter e chamar NdisCloseAdapterEx na função ProtocolUnbindAdapterEx .
O NDIS chama ProtocolBindAdapterEx em IRQL = PASSIVE_LEVEL.
Exemplos
Para definir uma função ProtocolBindAdapterEx , 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 ProtocolBindAdapterEx chamada "MyBindAdapterEx", use o tipo PROTOCOL_BIND_ADAPTER_EX conforme mostrado neste exemplo de código:
PROTOCOL_BIND_ADAPTER_EX MyBindAdapterEx;
Em seguida, implemente sua função da seguinte maneira:
_Use_decl_annotations_
NDIS_STATUS
MyBindAdapterEx(
NDIS_HANDLE ProtocolDriverContext,
NDIS_HANDLE BindContext,
PNDIS_BIND_PARAMETERS BindParameters
)
{...}
O tipo de função PROTOCOL_BIND_ADAPTER_EX é 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_BIND_ADAPTER_EX 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 no NDIS 6.0 e posterior. |
| Plataforma de Destino | Windows |
| Cabeçalho | ndis.h (inclua Ndis.h) |
| IRQL | PASSIVE_LEVEL |