Partilhar via

Função NdisRegisterProtocol (ndis.h)

  • Artigo

Observação 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 o NDIS 6. x, consulte portabilidade de drivers NDIS 5.x para NDIS 6.0.

NdisRegisterProtocol registra os pontos de entrada e o nome do do driver NDIS 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 do 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 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.

  • Reservada
    Esse membro é reservado para uso do sistema.

  • OpenAdapterCompleteHandler
    Especifica o ponto de entrada da funçãoProtocolOpenAdapterComplete do chamador.

  • CloseAdapterCompleteHandler
    Especifica o ponto de entrada da funçãoProtocolCloseAdapterComplete do chamador.

  • SendCompleteHandler
    Especifica o ponto de entrada da função ProtocolSendComplete do chamador, se houver.

  • TransferDataCompleteHandler
    Especifica o ponto de entrada da funçãoProtocolTransferDataComplete do chamador, se houver.

  • ResetCompleteHandler
    Especifica o ponto de entrada da funçãoProtocolResetComplete do chamador.

  • RequestCompleteHandler
    Especifica o ponto de entrada da funçãoProtocolRequestComplete do chamador.

  • ReceiveHandler
    Especifica o ponto de entrada da função ProtocolReceive do chamador, se houver.

  • ReceiveCompleteHandler
    Especifica o ponto de entrada da funçãoProtocolReceiveComplete 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.

  • Name
    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 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 de NDIS_STRING como um tipo de UNICODE_STRING. Essa cadeia de caracteres deve corresponder à especificada no registro (em Services) 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çãoProtocolReceivePacket 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çãoProtocolBindAdapter do chamador. Os chamadores que definem o valor no membro MajorNdisVersion para 0x05 ou 0x04 devem fornecer uma função ProtocolBindAdapter e dar suporte ao 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çãoProtocolUnbindAdapter 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 à conexão deve fornecer. Um cliente orientado à conexão fornecerá uma função ProtocolStatus se ele 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 à conexão deve fornecer. Um cliente orientado à conexão fornece uma função ProtocolReceivePacket e/ou ProtocolReceive e ProtocolTransferDataComplete funções se ele também se associa 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á automaticamente definido 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 no e MinorNdisVersion membros da estrutura de características devem ser consistentes com a diretiva de build ou devem ser 0x03 e 0x00, respectivamente.

Valor de retorno

Nenhum

Observações

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 sobre 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 de protocolBindAdapter.

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

Um driver registrado com êxito deve salvar a alça retornada em NdisProtocolHandle. É um parâmetro necessário para outras funções de 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 retornará o controle porque essa função de 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 camada acima de qualquer driver NDIS que registrou um conjunto de funções de miniportXxx do NDIS.

  • Plataforma de destino: Universal
  • Versão: Não há suporte para drivers NDIS 6.0 no Windows Vista. Use NdisRegisterProtocolDriver. Com suporte para drivers NDIS 5.1 no Windows Vista e no Windows XP.

Requisitos

Requisito Valor
cabeçalho ndis.h (inclua Ndis.h)
biblioteca Ndis.lib
IRQL PASSIVE_LEVEL

Consulte também