Função NdisRegisterProtocol (ndis.h)

Nota NDIS 5. x foi preterido e substituído pelo NDIS 6. x. Para obter o 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 dando 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 maiúsculas e minú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 associados a qualquer driver NIC que dê suporte a indicações de recebimento de vários pacotes devem fornecer uma função ProtocolReceivePacket para melhorar seu 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 tenham sido 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 à conexão deve fornecer. Um cliente orientado à conexão fornecerá uma função ProtocolSendComplete se ela 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 à conexão fornecerá uma função ProtocolStatus se ela também se associar a miniportes sem conexão.

• CoReceivePacketHandler
  Especifica o ponto de entrada da função ProtocolCoReceivePacket do chamador , que um cliente ou gerenciador de chamadas orientado à conexão deve fornecer. Um cliente orientado à conexão fornece uma função ProtocolReceivePacket e/ou funções ProtocolReceive e ProtocolTransferDataComplete se ele também se associa a miniportes 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 uma 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

Confira também

• ANSI_STRING
• DriverEntry de drivers de protocolo NDIS
• NdisClOpenAddressFamily
• NdisCmRegisterAddressFamily
• NdisDeregisterProtocol
• NdisIMRegisterLayeredMiniport
• NdisInitializeString
• NdisInitUnicodeString
• NdisMCmRegisterAddressFamily
• NdisOpenAdapter
• NdisZeroMemory
• ProtocolBindAdapter
• ProtocolCloseAdapterComplete
• ProtocolCoAfRegisterNotify
• ProtocolCoReceivePacket
• ProtocolCoSendComplete
• ProtocolCoStatus
• ProtocolOpenAdapterComplete
• ProtocolPnPEvent
• ProtocolReceive
• ProtocolReceiveComplete
• ProtocolReceivePacket
• ProtocolRequestComplete
• ProtocolResetComplete
• ProtocolSendComplete
• ProtocolStatus
• ProtocolStatusComplete
• ProtocolTransferDataComplete
• ProtocolUnbindAdapter
• UNICODE_STRING