Função NdisRegisterProtocol (ndis.h)

Artigo
08/07/2023

Nota NDIS 5. x foi preterido e substituído pelo NDIS 6. x. Para obter um novo desenvolvimento de driver NDIS, consulte Drivers de rede começando com o Windows Vista. Para obter informações sobre como portar o NDIS 5. x drivers para NDIS 6. x, consulte Portabilidade de drivers NDIS 5.x para NDIS 6.0.

NdisRegisterProtocol registra os pontos de entrada ProtocolXxx de um driver NDIS e o nome com a biblioteca NDIS quando o driver é inicializado.

Sintaxe

void NdisRegisterProtocol(
  [out] PNDIS_STATUS                   Status,
  [out] PNDIS_HANDLE                   NdisProtocolHandle,
  [in]  PNDIS_PROTOCOL_CHARACTERISTICS ProtocolCharacteristics,
  [in]  UINT                           CharacteristicsLength
);

Parâmetros

[out] Status

Ponteiro para uma variável fornecida pelo chamador que pode ser um dos seguintes valores no retorno dessa função:

NDIS_STATUS_SUCCESS
A biblioteca NDIS registrou o chamador como um driver de protocolo.
NDIS_STATUS_BAD_CHARACTERISTICS
O CharacteristicsLength é muito pequeno para o MajorNdisVersion especificado no buffer em ProtocolCharacteristics.
NDIS_STATUS_BAD_VERSION
O MajorNdisVersion especificado no buffer em ProtocolCharacteristics é inválido.
NDIS_STATUS_RESOURCES
Uma escassez de recursos, possivelmente memória, impediu que a biblioteca NDIS registrasse o chamador.

[out] NdisProtocolHandle

Ponteiro para uma variável fornecida pelo chamador na qual essa função retorna um identificador que representa o driver registrado.

[in] ProtocolCharacteristics

Ponteiro para uma estrutura NDIS_PROTOCOL_CHARACTERISTICS configurada pelo chamador. A estrutura em ProtocolCharacteristics é definida da seguinte maneira:

        typedef struct _NDIS_PROTOCOL_CHARACTERISTICS {
            UCHAR MajorNdisVersion;
            UCHAR MinorNdisVersion;
            UINT Reserved;
            OPEN_ADAPTER_COMPLETE_HANDLER OpenAdapterCompleteHandler;
            CLOSE_ADAPTER_COMPLETE_HANDLER CloseAdapterCompleteHandler;
            SEND_COMPLETE_HANDLER SendCompleteHandler;
            TRANSFER_DATA_COMPLETE_HANDLER TransferDataCompleteHandler;
            RESET_COMPLETE_HANDLER ResetCompleteHandler;
            REQUEST_COMPLETE_HANDLER RequestCompleteHandler;
            RECEIVE_HANDLER ReceiveHandler;
            RECEIVE_COMPLETE_HANDLER ReceiveCompleteHandler;
            STATUS_HANDLER StatusHandler;
            STATUS_COMPLETE_HANDLER StatusCompleteHandler;
            NDIS_STRING Name;
        //
        // MajorNdisVersion must be set to 0x04 or 0x05
        // with any of the following members.
        //
            RECEIVE_PACKET_HANDLER ReceivePacketHandler;
            BIND_HANDLER BindAdapterHandler;
            UNBIND_HANDLER UnbindAdapterHandler;
            PNP_EVENT_HANDLER PnPEventHandler;
            UNLOAD_PROTOCOL_HANDLER UnloadHandler;
        //
        // MajorNdisVersion must be set to 0x05 
        // with any of the following members.
        //
            CO_SEND_COMPLETE_HANDLER CoSendCompleteHandler;
            CO_STATUS_HANDLER CoStatusHandler;
            CO_RECEIVE_PACKET_HANDLER CoReceivePacketHandler;
            CO_AF_REGISTER_NOTIFY_HANDLER CoAfRegisterNotifyHandler;
        } NDIS_PROTOCOL_CHARACTERISTICS, *PNDIS_PROTOCOL_CHARACTERISTICS;

O driver deve inicializar essa estrutura com zeros antes de configurar os seguintes membros:

MajorNdisVersion
Especifica a versão principal da biblioteca NDIS que o driver está usando. O valor atual é 0x05, embora a biblioteca NDIS continue a dar suporte a drivers existentes desenvolvidos para o NDIS V4.0. O NDIS não dá mais suporte a protocolos V3.0.
MinorNdisVersion
Especifica a versão secundária do NDIS. O valor atual é 0x00.
Reserved
Esse membro é reservado para uso do sistema.
OpenAdapterCompleteHandler
Especifica o ponto de entrada da função ProtocolOpenAdapterComplete do chamador.
CloseAdapterCompleteHandler
Especifica o ponto de entrada da função ProtocolCloseAdapterComplete do chamador.
SendCompleteHandler
Especifica o ponto de entrada da função ProtocolSendComplete do chamador, se houver.
TransferDataCompleteHandler
Especifica o ponto de entrada da função ProtocolTransferDataComplete do chamador, se houver.
ResetCompleteHandler
Especifica o ponto de entrada da função ProtocolResetComplete do chamador.
RequestCompleteHandler
Especifica o ponto de entrada da função ProtocolRequestComplete do chamador.
ReceiveHandler
Especifica o ponto de entrada da função ProtocolReceive do chamador , se houver.
ReceiveCompleteHandler
Especifica o ponto de entrada da função ProtocolReceiveComplete do chamador .
StatusHandler
Especifica o ponto de entrada da função ProtocolStatus do chamador, se houver.
StatusCompleteHandler
Especifica o ponto de entrada da função ProtocolStatusComplete do chamador.
Nome
Um tipo de NDIS_STRING que contém uma cadeia de caracteres contada inicializada pelo chamador, no conjunto de caracteres padrão do sistema, nomeando o driver. Para drivers do Windows 2000 e posteriores, essa cadeia de caracteres contém caracteres Unicode. Ou seja, para o Windows 2000 e posterior, o NDIS define o tipo NDIS_STRING como um tipo de UNICODE_STRING . Essa cadeia de caracteres deve corresponder à especificada no Registro (em Serviços) quando o protocolo foi instalado.

NdisRegisterProtocol converte a cadeia de caracteres fornecida em letras maiúsculas, portanto, um gravador de driver de protocolo não pode assumir que alterar o caso de um nome de protocolo já registrado cria um nome exclusivo para o driver.
ReceivePacketHandler
Especifica o ponto de entrada da função ProtocolReceivePacket do chamador , se houver, ou NULL. Os protocolos que se associam a qualquer driver NIC que dê suporte a indicações de recebimento de vários pacotes devem fornecer uma função ProtocolReceivePacket para aprimorar o desempenho. No entanto, um protocolo que se associa exclusivamente a miniportos orientados à conexão também pode definir esse membro como NULL.
BindAdapterHandler
Especifica o ponto de entrada da função ProtocolBindAdapter do chamador. Os chamadores que definem o valor no membro MajorNdisVersion como 0x05 ou 0x04 devem fornecer uma função ProtocolBindAdapter e dar suporte a Plug and Play. Os drivers intermediários do NDIS também devem fornecer uma função ProtocolBindAdapter , que permite que esses drivers intermediários chamem NdisIMRegisterLayeredMiniport e adiem a inicialização completa do driver até que os drivers NIC subjacentes sejam inicializados.
UnbindAdapterHandler
Especifica o ponto de entrada da função ProtocolUnbindAdapter do chamador. Os drivers NDIS que fornecem uma função ProtocolBindAdapter também devem fornecer uma função ProtocolUnbindAdapter .
PnPEventHandler
Especifica o ponto de entrada da função ProtocolPnPEvent do chamador, se houver.
UnloadHandler
Especifica o ponto de entrada da função ProtocolUnbind do chamador, se houver, ou NULL.
CoSendCompleteHandler
Especifica o ponto de entrada da função ProtocolCoSendComplete do chamador, que um cliente ou gerenciador de chamadas orientado a conexões deve fornecer. Um cliente orientado à conexão fornecerá uma função ProtocolSendComplete se também se associar a miniportos sem conexão.
CoStatusHandlerCoStatusHandler
Especifica o ponto de entrada da função ProtocolCoStatus do chamador, que um cliente ou gerenciador de chamadas orientado a conexões deve fornecer. Um cliente orientado a conexão fornecerá uma função ProtocolStatus se também se associar a miniportos sem conexão.
CoReceivePacketHandler
Especifica o ponto de entrada da função ProtocolCoReceivePacket do chamador , que um cliente ou gerenciador de chamadas orientado a conexões deve fornecer. Um cliente orientado a conexão fornece uma função ProtocolReceivePacket e/ou funções ProtocolReceive e ProtocolTransferDataComplete se também se associar a miniportos sem conexão.
CoAfRegisterNotifyHandler
Especifica o ponto de entrada da função ProtocolAfRegisterNotify do chamador, que um cliente orientado à conexão deve fornecer.

[in] CharacteristicsLength

Especifica o tamanho em bytes da estrutura em ProtocolCharacteristics. Se a diretiva de build -DNDIS50=1 ou -DNDIS40=1 for especificada no arquivo de fontes antes de #includeNdis.h , o sizeof(NDIS_PROTOCOL_CHARACTERISTICS) será definido automaticamente como o valor apropriado. Se nenhuma diretiva for especificada, o NDIS pressupõe que a estrutura de características V3.0 está sendo usada.

Os valores definidos nos membros MajorNdisVersion e MinorNdisVersion da estrutura de características devem ser consistentes com a diretiva de build ou devem ser 0x03 e 0x00, respectivamente.

Retornar valor

Nenhum

Comentários

Um driver de protocolo deve especificar um MajorNdisVersion de 0x05 (a versão atual) ou 0x04. O NDIS não dá mais suporte a protocolos V.30 e, portanto, não carrega um protocolo que especifica um MajorNdisVersion de 0x03.

Todos os protocolos devem ser compatíveis com Plug and Play (PnP). Portanto, um protocolo deve especificar pontos de entrada para BindAdapterHandler e UnbindAdapterHandler. O NDIS não carrega um protocolo que especifica NULL para esses manipuladores.

Para obter o melhor desempenho possível, qualquer protocolo que se coloque em camadas acima de um driver NIC sem conexão que dê suporte a recebimentos de vários pacotes deve fornecer uma função ProtocolReceivePacket . Esse driver de protocolo também deve fornecer uma função ProtocolReceive . Qualquer driver NIC sem conexão que dê suporte a envios de vários pacotes também provavelmente indicará recebimentos de vários pacotes.

Todos os protocolos orientados à conexão, sejam clientes ou gerentes de chamadas, devem registrar uma função ProtocolCoReceivePacket . Os protocolos de cliente que também se associam a drivers NIC sem conexão fornecem funções ProtocolReceivePacket e ProtocolReceive também. Os protocolos orientados à conexão devem registrar pontos de entrada adicionais orientados à conexão com o NDIS chamando NdisClOpenAddressFamily para clientes ou NdisCmRegisterAddressFamily para gerenciadores de chamadas de suas funções ProtocolBindAdapter .

Após uma chamada bem-sucedida para NdisRegisterProtocol, um driver não pode alterar o conjunto de funções ProtocolXxx fornecidas por ele.

Um driver registrado com êxito deve salvar o identificador retornado em NdisProtocolHandle. É um parâmetro necessário para outras funções NdisXxx que o driver chama posteriormente.

Após uma chamada bem-sucedida para NdisRegisterProtocol, a função DriverEntry de um protocolo orientado a conexão ou com reconhecimento PnP retorna o controle porque essa função ProtocolBindAdapter de um driver será chamada posteriormente uma ou mais vezes para configurar associações para NIC(s) subjacentes. Caso contrário, o driver de protocolo pode chamar NdisOpenAdapter para configurar uma associação para o driver NIC subjacente ou para se colocar em camadas acima de qualquer driver NDIS que registrou um conjunto de funções NDIS MiniportXxx .

Plataforma de destino: Universal
Versão: não há suporte para drivers NDIS 6.0 no Windows Vista. Em vez disso, use NdisRegisterProtocolDriver. Com suporte para drivers NDIS 5.1 no Windows Vista e windows XP.

Requisitos

Requisito	Valor
Cabeçalho	ndis.h (inclua Ndis.h)
Biblioteca	Ndis.lib
IRQL	PASSIVE_LEVEL

Share via

Função NdisRegisterProtocol (ndis.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Requisitos

Confira também

Comentários

Comentários

Recursos adicionais