Função NdisMSetAttributesEx (ndis.h)

  • Artigo

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.

NdisMSetAttributesEx informa à biblioteca NDIS sobre recursos significativos da NIC ou nic virtual do chamador durante a inicialização.

Sintaxe

void NdisMSetAttributesEx(
  [in]           NDIS_HANDLE         MiniportAdapterHandle,
  [in]           NDIS_HANDLE         MiniportAdapterContext,
  [in, optional] UINT                CheckForHangTimeInSeconds,
  [in]           ULONG               AttributeFlags,
  [in, optional] NDIS_INTERFACE_TYPE AdapterType
);

Parâmetros

[in] MiniportAdapterHandle

Especifica a entrada do identificador para MiniportInitialize.

[in] MiniportAdapterContext

Especifica um identificador para uma área de contexto residente alocada por MiniportInitialize.

[in, optional] CheckForHangTimeInSeconds

Especifica o intervalo, em segundos, no qual o NDIS deve chamar a função MiniportCheckForHang . Se um driver não tiver respondido a uma solicitação OID ou enviado uma solicitação dentro de duas chamadas sucessivas para MiniportCheckForHang, o NDIS poderá chamar a função MiniportReset do driver.

O intervalo real que o NDIS usa ao chamar MiniportCheckForHang é sempre um múltiplo de 2 segundos. Por exemplo, se você especificar 5 segundos, o intervalo real será de aproximadamente 4 segundos.

Especificar zero para esse parâmetro indica que o NDIS deve chamar MiniportCheckForHang no intervalo padrão de 2 segundos do NDIS.

Se o chamador definir NDIS_ATTRIBUTE_DESERIALIZE em AttributeFlags, o NDIS não enfileira os envios pendentes para o driver de miniporto. Em vez disso, esse driver desserializado deve gerenciar seu próprio enfileiramento de solicitações de envio subsequentes internamente sempre que não tiver recursos suficientes para transmitir um envio de entrada imediatamente.

[in] AttributeFlags

Especifica uma máscara de bits que pode ser definida com um ou mais (ORed) dos seguintes sinalizadores:

  • NDIS_ATTRIBUTE_BUS_MASTER
    Defina se a NIC do chamador é um dispositivo DMA master barramento.

  • NDIS_ATTRIBUTE_DESERIALIZE
    Defina se o chamador for um driver de miniporta desserializado.

  • NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT
    Defina se o NDIS não deve tentar esgotar os pacotes de envio pendentes que ele mantém na fila para o chamador. Os drivers intermediários devem definir esse sinalizador, mas os drivers NIC não devem.

  • NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT
    Defina se o NDIS não deve tentar esgotar a consulta pendente e definir solicitações que ela mantém enfileiradas para o chamador. Os drivers intermediários devem definir esse sinalizador, mas os drivers NIC não devem.

  • NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER
    Defina se o chamador é um driver intermediário.

  • NDIS_ATTRIBUTE_IGNORE_TOKEN_RING_ERRORS
    Defina se o NDIS não deve chamar a função MiniportReset de um driver de Nic de Anel de Token se forem indicados erros de Anel de Token.

  • NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND
    Defina se o NDIS não deve chamar a função MiniportHalt de um driver antes que o sistema faça a transição para um estado de baixa potência (em suspensão). Os drivers que dependem do estado mantido por hardware não devem definir esse sinalizador.

    Nota Definir esse sinalizador desabilita a caixa Permitir que o computador desative esse dispositivo para economizar energia marcar na guia Gerenciamento de Energia da caixa de diálogo Propriedades da NIC (cartão de interface de rede). O gerenciamento de energia será desabilitado mesmo que a NIC seja capaz de gerenciamento de energia.

  • NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK
    Defina se o driver pode lidar com a remoção de sua NIC sem notificação do usuário. Esse driver exporta uma função MiniportPnPEventNotify . O suporte do sistema para NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK está disponível no Windows XP e em sistemas operacionais posteriores.

  • NDIS_ATTRIBUTE_NOT_CO_NDIS
    Definido por um driver que pode dar suporte a dispositivos orientados a conexão e sem conexão para indicar que o dispositivo é um dispositivo sem conexão. O suporte do sistema para NDIS_ATTRIBUTE_NOT_CO_NDIS está disponível no Windows XP e em sistemas operacionais posteriores.

  • NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS
    Definido por um driver que usa NdisBufferVirtualAddressSafe, NdisGetFirstBufferFromPacketSafe e NdisQueryBufferSafe exclusivamente para acessar endereços virtuais do sistema para enviar buffers de pacotes. NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS também é definido por um driver que usa exclusivamente endereços físicos para acessar esses buffers. Definir NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS pode melhorar o desempenho, pois o sistema operacional não precisará mapear o envio de buffers de pacotes para endereços virtuais do sistema. O suporte do sistema para NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS está disponível no Windows XP e em versões posteriores.

  • NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO
    Definido por um driver de miniporto CoNDIS que não fornece serviços TAPI. Definir NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO impede que o NDIS associe o driver de miniporto ao driver proxy TAPI do NDIS (NDPROXY). Por padrão, o NDIS associa NDPROXY a todos os drivers de miniporto coNDIS.

[in, optional] AdapterType

Especifica o tipo de interface de barramento de E/S da NIC do chamador, que geralmente é o tipo de barramento de E/S no qual a NIC está conectada, como um dos seguintes:

  • NdisInterfaceInternal
    Especifica uma interface interna específica do host.

  • NdisInterfaceIsa
    Especifica a interface ISA.

  • NdisInterfaceEisa
    Especifica a interface EISA (ISA estendida).

  • NdisInterfaceMca
    Isso se refere ao barramento MCA, que não tem mais suporte.

  • NdisInterfaceTurboChannel
    Especifica a interface do Turbo Channel.

  • NdisInterfacePci
    Especifica a interface PCI (Interconexão de Componentes Periféricos).

  • NdisInterfacePcMcia
    Especifica a interface da Associação Internacional de Cartão de Memória do Computador Pessoal (Pc Card).

Esse parâmetro é irrelevante para drivers intermediários, que devem passar zero para esse argumento para NdisMSetAttributesEx.

Retornar valor

Nenhum

Comentários

Uma função MiniportInitialize deve chamar NdisMSetAttributesEx(ou NdisMSetAttributes) antes de chamar qualquer outra função NdisMRegisterXxx ou NdisXxx que dependa das informações fornecidas a NdisMSetAttributesEx. Por exemplo, a chamada de um driver NIC para NdisMAllocateMapRegisters falhará se MiniportInitialize ainda não tiver chamado NdisMSetAttributesEx com AttributeFlags definido com NDIS_ATTRIBUTE_BUS_MASTER.

Os drivers intermediários devem chamar NdisMSetAttributesEx, em vez de NdisMSetAttributes, e devem definir NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER no AttributeFlags. Definir esse sinalizador faz com que o NDIS trate um driver intermediário como um driver de miniporto full-duplex, o que impede que deadlocks raros, mas intermitentes, ocorram no driver intermediário. Consequentemente, cada driver intermediário deve ser capaz de lidar com envios e indicações simultâneas.

Os drivers desserializados também devem chamar NdisMSetAttributesEx e devem definir NDIS_ATTRIBUTE_DESERIALIZE no AttributeFlags. O NDIS não mantém uma fila de envio de pacotes para um driver desserializado, nem o NDIS serializa chamadas para as funções MiniportXxx de um driver desse tipo. Um driver desserializado se torna responsável pelo seguinte:

  • Aceitando todas as solicitações de envio de entrada
  • Enfileirar pacotes de envio de entrada internamente, se necessário, como, por exemplo, se um driver NIC desserializado atualmente não tiver recursos suficientes disponíveis para transmitir um pacote de envio de entrada imediatamente
  • Sincronizar o acesso às suas filas internas conforme necessário entre as rotinas do driver
  • Concluir todos os envios solicitados de forma assíncrona chamando posteriormente NdisMSendComplete com cada descritor de pacote fornecido pelo protocolo passado para sua função Miniport(Co)Send(Packets)

O NDIS pressupõe que todos os miniportos orientados a conexão sejam drivers desserializados, independentemente do AttributeFlags que eles passam para NdisMSetAttributesEx. Ou seja, qualquer driver que chame NdisMRegisterMiniport com 0x05 como MajorNdisVersion deve ser um driver de miniporto desserializado.

Os drivers NIC serializados podem chamar qualquer uma dessas funções de MiniportInitialize, mas NdisMSetAttributes não permite que seu chamador ajuste o intervalo no qual as funções MiniportCheckForHang e/ou MiniportReset de um driver NIC são chamadas.

O valor de CheckForHangTimeInSeconds determina o intervalo de tempo limite da biblioteca NDIS em envios, se houver, e solicita que ele mantenha enfileirado para o chamador. Por padrão, o NDIS atinge o tempo limite dos envios enfileirados (somente para drivers serializados) e solicitações em duas vezes o intervalo de marcar para travamento, após o qual ele chama a função MiniportReset, a menos que o driver defina AttributeFlags com NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT e NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT quando chamar NdisMSetAttributesEx. Os drivers intermediários devem definir esses sinalizadores ao chamar NdisMSetAttributesEx porque esse driver não pode determinar ou controlar quando o driver NIC subjacente processará envios e solicitações.

Os drivers NIC não devem definir os sinalizadores de NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT e NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT, embora o NDIS cumpra essa especificação por um driver NIC serializado. No entanto, os drivers NIC podem ajustar o intervalo de tempo limite no qual suas funções MiniportReset são chamadas especificando um CheckForHangTimeInSeconds explícito. Por exemplo, um driver NIC que emula ethernet em um modem pode não concluir todos os pacotes dentro do intervalo de tempo limite padrão da biblioteca NDIS. Sempre que um pacote aparecia com o tempo limite em tal NIC, o NDIS pressupõe que a NIC não estava mais operando corretamente e chamaria a função MiniportReset do driver. Para o driver de tal NIC, chamar NdisMSetAttributesEx com um CheckForHangTimeInSeconds definido como algo maior que dois impede redefinições desnecessárias e estende o intervalo no qual sua função MiniportCheckForHang , se houver, é chamada para testar o estado operacional da NIC.

Um driver intermediário deve definir o sinalizador NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND. Definir esse sinalizador impede que o NDIS interrompa o driver antes que o sistema faça a transição para um estado de baixa potência (em suspensão).

Um driver de miniporto herdado que gerencia uma NIC sem reconhecimento de PnP pode definir o sinalizador NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND para impedir que o NDIS interrompa o driver antes que o sistema faça a transição para um estado de baixa potência. Se o driver de miniporta definir esse sinalizador, o NDIS consultará o driver de miniporto com OID_PNP_CAPABILITIES mesmo que o motorista do ônibus para a NIC do motorista de miniporto possa ter indicado que a NIC não tem reconhecimento de PM. O driver de miniporta deve ter êxito na solicitação de OID_PNP_CAPABILITIES com NDIS_STATUS_SUCCESS. Na estrutura NDIS_PM_WAKE_UP_CAPABILITIES retornada por esse OID, o driver de miniporto também deve especificar um estado de energia do dispositivo de NdisDeviceStateUnspecified para cada funcionalidade de ativação. Quando o sistema faz a transição para um estado de baixa potência, o NDIS não chamará a função MiniportHalt de um driver de miniport. Antes que o sistema faça a transição para um estado de menor potência, o driver de miniporta deve salvar qualquer contexto de hardware que ele mantém. Ao receber uma solicitação OID_PNP_SET_POWER para o estado D3, o driver de miniporto deve definir sua NIC como o estado apropriado para o estado de baixa potência. Ao receber uma solicitação de OID_PNP_SET_POWER para o estado D0, o driver de miniporto deve definir sua NIC como o estado apropriado para o estado de trabalho.

Um driver de miniporta que dá suporte à remoção surpresa de seu dispositivo (remoção sem notificação por meio da interface do usuário) deve definir NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK. Isso faz com que o NDIS chame a função MiniportPnPEventNotify do driver com PnPEvent definido como NdisDevicePnPEventSurpriseRemoved quando o dispositivo do miniporto é removido sem notificação. Além disso, a configuração NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK suprime a exibição de uma caixa de diálogo de aviso que solicita que o usuário interrompa o dispositivo antes de removê-lo.

Um driver de miniporta que pode dar suporte a dispositivos orientados a conexão e sem conexão deve definir NDIS_ATTRIBUTE_NOT_CO_NDIS se seu dispositivo for um dispositivo sem conexão. Caso contrário, o NDIS assumirá erroneamente que seu dispositivo é orientado à conexão, pois o driver registra funções de driver de miniporto orientadas a conexão com NdisMRegisterMiniport.

Em geral, um driver NIC deve chamar NdisMSetAttributesEx antes de chamar qualquer função NdisXxx que declara recursos de hardware no registro para sua NIC, pois o NDIS deve ter o valor AttributeFlags antes que essa chamada seja feita e porque o driver geralmente precisa da memória em MiniportAdapterContext para armazenar informações para essas chamadas. Essa restrição implica que a função MiniportInitialize de um driver NIC não pode chamar o seguinte NdisXxx antes de chamar NdisMSetAttributesEx:

No entanto, antes de chamar NdisMSetAttributesEx, qualquer função MiniportInitialize de qualquer driver pode chamar o Ndis.. Funções de configuração para recuperar informações de configuração instaladas no Registro. MiniportInitialize também pode chamar as funções NdisReadXxx específicas do tipo de barramento, como NdisReadPciSlotInformation, desde que a entrada do Registro instalada para o tipo de interface do driver corresponda às chamadas NdisReadXxxxMiniportInitialize específicas do tipo de barramento.

O identificador MiniportAdapterContext fornecido a NdisMSetAttributesEx torna-se um parâmetro de entrada para todas as funções MiniportXxx que foram registradas, juntamente com MiniportInitialize, na chamada para NdisMRegisterMiniport ou NdisIMRegisterLayeredMiniport. Normalmente, esse identificador é um ponteiro para a memória residente, alocada pelo MiniportInitialize, no qual o driver mantém o estado de tempo de execução específico da NIC.

  • Plataforma de destino: Universal
  • Versão: não há suporte para drivers NDIS 6.0 no Windows Vista. Em vez disso, use NdisMSetMiniportAttributes. 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

Confira também