Función NdisMSetAttributesEx (ndis.h)

  • Artículo

Nota NDIS 5. x ha quedado en desuso y se sustituye por NDIS 6. x. Para el nuevo desarrollo de controladores NDIS, consulte Controladores de red a partir de Windows Vista. Para obtener información sobre cómo migrar NDIS 5. x controladores a NDIS 6. x, consulte Migración de controladores NDIS 5.x a NDIS 6.0.

NdisMSetAttributesEx informa a la biblioteca NDIS sobre características significativas de la NIC del autor de la llamada o de la NIC virtual durante la inicialización.

Sintaxis

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 la entrada de identificador en MiniportInitialize.

[in] MiniportAdapterContext

Especifica un identificador para un área de contexto residente asignada por MiniportInitialize.

[in, optional] CheckForHangTimeInSeconds

Especifica el intervalo, en segundos, en el que NDIS debe llamar a la función MiniportCheckForHang . Si un controlador no ha respondido a una solicitud de OID o ha enviado una solicitud dentro de dos llamadas sucesivas a MiniportCheckForHang, NDIS puede llamar a la función MiniportReset del controlador.

El intervalo real que usa NDIS al llamar a MiniportCheckForHang siempre es un múltiplo de 2 segundos. Por ejemplo, si especifica 5 segundos, el intervalo real será de aproximadamente 4 segundos.

Especificar cero para este parámetro indica que NDIS debe llamar a MiniportCheckForHang en el intervalo predeterminado de 2 segundos de NDIS.

Si el autor de la llamada establece NDIS_ATTRIBUTE_DESERIALIZE en AttributeFlags, NDIS no pone en cola los envíos pendientes para el controlador de minipuerto. En su lugar, este controlador deserializado debe administrar su propia cola de solicitudes de envío posteriores internamente siempre que tenga recursos insuficientes para transmitir inmediatamente un envío entrante.

[in] AttributeFlags

Especifica una máscara de bits que se puede establecer con una o varias (ORed) de las marcas siguientes:

  • NDIS_ATTRIBUTE_BUS_MASTER
    Establezca si la NIC del autor de la llamada es un dispositivo DMA maestro de bus.

  • NDIS_ATTRIBUTE_DESERIALIZE
    Establezca si el autor de la llamada es un controlador de minipuerto deserializado.

  • NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT
    Establezca si NDIS no debe intentar agotar el tiempo de espera de los paquetes de envío que contiene en cola al autor de la llamada. Los controladores intermedios deben establecer esta marca, pero los controladores NIC no deben.

  • NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT
    Establezca si NDIS no debe intentar agotar el tiempo de espera de la consulta y establecer las solicitudes que contiene en cola en el autor de la llamada. Los controladores intermedios deben establecer esta marca, pero los controladores NIC no deben.

  • NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER
    Establezca si el autor de la llamada es un controlador intermedio.

  • NDIS_ATTRIBUTE_IGNORE_TOKEN_RING_ERRORS
    Establezca si NDIS no debe llamar a la función MiniportReset del controlador NIC del anillo de tokens si se indican errores de anillo de token.

  • NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND
    Establezca si NDIS no debe llamar a la función MiniportHalt de un controlador antes de que el sistema pase a un estado de baja potencia (en suspensión). Los controladores que dependen del estado mantenido por hardware no deben establecer esta marca.

    Nota Al establecer esta marca, se deshabilita la casilla Permitir que el equipo desactive este dispositivo para guardar energía en la pestaña Administración de energía del cuadro de diálogo Propiedades de la tarjeta de interfaz de red (NIC). La administración de energía está deshabilitada incluso si la NIC es capaz de administrar energía.

  • NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK
    Establezca si el controlador puede controlar la eliminación de su NIC sin notificación de usuario. Este controlador exporta una función MiniportPnPEventNotify . La compatibilidad del sistema con NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK está disponible en Windows XP y en sistemas operativos posteriores.

  • NDIS_ATTRIBUTE_NOT_CO_NDIS
    Se establece mediante un controlador que puede admitir dispositivos sin conexión y orientados a la conexión para indicar que el dispositivo es un dispositivo sin conexión. La compatibilidad del sistema con NDIS_ATTRIBUTE_NOT_CO_NDIS está disponible en Windows XP y en sistemas operativos posteriores.

  • NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS
    Establecido por un controlador que usa NdisBufferVirtualAddressSafe, NdisGetFirstBufferFromPacketSafe y NdisQueryBufferSafe exclusivamente para acceder a las direcciones virtuales del sistema para enviar búferes de paquetes. NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS también lo establece un controlador que usa exclusivamente direcciones físicas para acceder a dichos búferes. Establecer NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS puede mejorar el rendimiento, ya que el sistema operativo no tendrá que asignar búferes de paquetes de envío a direcciones virtuales del sistema. La compatibilidad del sistema con NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS está disponible en Windows XP y versiones posteriores.

  • NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO
    Establecido por un controlador de miniporte de CoNDIS que no proporciona servicios TAPI. Establecer NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO impide que NDIS enlace el controlador miniporte al controlador proxy NDIS TAPI (NDPROXY). De forma predeterminada, NDIS enlaza NDPROXY a todos los controladores de miniporte de CoNDIS.

[in, optional] AdapterType

Especifica el tipo de interfaz de bus de E/S de la NIC del autor de la llamada, que normalmente es el tipo de bus de E/S en el que está conectada la NIC, como una de las siguientes:

  • NdisInterfaceInternal
    Especifica una interfaz interna específica del host.

  • NdisInterfaceIsa
    Especifica la interfaz ISA.

  • NdisInterfaceEisa
    Especifica la interfaz de ISA extendida (EISA).

  • NdisInterfaceMca
    Esto hace referencia al bus MCA, que ya no se admite.

  • NdisInterfaceTurboChannel
    Especifica la interfaz Turbo Channel.

  • NdisInterfacePci
    Especifica la interfaz de interconexión de componentes periféricos (PCI).

  • NdisInterfacePcMcia
    Especifica la interfaz de la Asociación Internacional de tarjeta de memoria de equipo personal (tarjeta PC).

Este parámetro es irrelevante para los controladores intermedios, que deben pasar cero para este argumento a NdisMSetAttributesEx.

Valor devuelto

None

Observaciones

Una función MiniportInitialize debe llamar a NdisMSetAttributesEx(o NdisMSetAttributes) antes de llamar a cualquier otra función NdisMRegisterXxx o NdisXxx que dependa de la información proporcionada a NdisMSetAttributesEx. Por ejemplo, se producirá un error en la llamada de un controlador NIC a NdisMAllocateMapRegisters si MiniportInitialize aún no ha llamado a NdisMSetAttributesEx con attributeFlags establecido con NDIS_ATTRIBUTE_BUS_MASTER.

Los controladores intermedios deben llamar a NdisMSetAttributesEx, en lugar de a NdisMSetAttributes, y deben establecer NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER en AttributeFlags. Al establecer esta marca, NDIS trata un controlador intermedio como un controlador miniporte dúplex completo, lo que evita que se produzcan interbloqueos poco frecuentes pero intermitentes en el controlador intermedio. Por lo tanto, cada controlador intermedio debe ser capaz de controlar envíos simultáneos e indicaciones.

Los controladores deserializados también deben llamar a NdisMSetAttributesEx y deben establecer NDIS_ATTRIBUTE_DESERIALIZE en AttributeFlags. NDIS no mantiene una cola de paquetes de envío para un controlador deserializado, ni serializa las llamadas NDIS a las funciones MiniportXxx de un controlador de este tipo. Un controlador deserializado se hace responsable de lo siguiente:

  • Aceptar todas las solicitudes de envío entrantes
  • Poner en cola los paquetes de envío entrantes internamente si es necesario, como, por ejemplo, si un controlador NIC deserializado tiene actualmente recursos insuficientes disponibles para transmitir un paquete de envío entrante inmediatamente.
  • Sincronizar el acceso a sus colas internas según sea necesario entre las rutinas del controlador
  • Completar todos los envíos solicitados de forma asincrónica llamando posteriormente a NdisMSendComplete con cada descriptor de paquete proporcionado por el protocolo pasado a su función Miniport(Co)Send(Packets)

NDIS supone que todos los miniportes orientados a la conexión son controladores deserializados, independientemente de AttributeFlags que pasen a NdisMSetAttributesEx. Es decir, cualquier controlador que llame a NdisMRegisterMiniport con 0x05 como MajorNdisVersion debe ser un controlador de miniporte deserializado.

Los controladores NIC serializados pueden llamar a cualquiera de estas funciones desde MiniportInitialize, pero NdisMSetAttributes no permite a su autor de llamada ajustar el intervalo en el que se llama a las funciones MiniportCheckForHang o MiniportReset del controlador NIC.

El valor de CheckForHangTimeInSeconds determina el intervalo de tiempo de espera de la biblioteca NDIS en los envíos, si los hay, y las solicitudes que contiene en cola al autor de la llamada. De forma predeterminada, NDIS agota el tiempo de espera de los envíos en cola (solo para controladores serializados) y las solicitudes al doble del intervalo check-for-hang, después de lo cual llama a la función MiniportReset , a menos que el controlador establezca AttributeFlags con NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT y NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT cuando llama a NdisMSetAttributesEx. Los controladores intermedios deben establecer estas marcas al llamar a NdisMSetAttributesEx porque dicho controlador no puede determinar ni controlar cuándo el controlador NIC subyacente procesará los envíos y solicitudes.

Los controladores NIC no deben establecer las marcas de NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT y NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT, aunque NDIS respetará dicha especificación mediante un controlador NIC serializado. Sin embargo, los controladores NIC pueden ajustar el intervalo de tiempo de espera en el que se llama a sus funciones MiniportReset especificando un CheckForHangTimeInSeconds explícito. Por ejemplo, un controlador NIC que emula Ethernet a través de un módem podría no completar todos los paquetes dentro del intervalo de tiempo de espera predeterminado de la biblioteca NDIS. Cada vez que un paquete parecía agotar el tiempo de espera en dicha NIC, NDIS asumiría que la NIC ya no funcionaba correctamente y llamaría a la función MiniportReset del controlador. Para el controlador de este tipo de NIC, llamar a NdisMSetAttributesEx con un CheckForHangTimeInSeconds establecido en algo mayor que dos impide que se restablezcan innecesariamente y extienda el intervalo en el que se llama a su función MiniportCheckForHang , si existe, para probar el estado operativo de la NIC.

Un controlador intermedio debe establecer la marca NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND. Al establecer esta marca, se impide que NDIS detenga el controlador antes de que el sistema pase a un estado de bajo consumo (en suspensión).

Un controlador de miniporte heredado que administra una NIC no compatible con PnP puede establecer la marca de NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND para evitar que NDIS detenga el controlador antes de que el sistema pase a un estado de bajo consumo. Si el controlador de minipuerto establece esta marca, NDIS consulta el controlador de minipuerto con OID_PNP_CAPABILITIES aunque el controlador de bus para la NIC del controlador de minipuerto haya indicado que la NIC no es compatible con pm. El controlador de minipuerto debe realizar correctamente la solicitud de OID_PNP_CAPABILITIES con NDIS_STATUS_SUCCESS. En la estructura NDIS_PM_WAKE_UP_CAPABILITIES devuelta por este OID, el controlador de minipuerto también debe especificar un estado de alimentación del dispositivo de NdisDeviceStateUnspecified para cada funcionalidad de reactivación. Cuando el sistema pasa a un estado de baja potencia, NDIS no llamará a la función MiniportHalt del controlador de miniporte . Antes de que el sistema pase a un estado de menor potencia, el controlador de minipuerto debe guardar cualquier contexto de hardware que mantenga. Al recibir una solicitud de OID_PNP_SET_POWER al estado D3, el controlador de minipuerto debe establecer su NIC en el estado adecuado para el estado de baja potencia. Al recibir una solicitud de OID_PNP_SET_POWER al estado D0, el controlador de minipuerto debe establecer su NIC en el estado adecuado para el estado de trabajo.

Un controlador miniporte que admita la eliminación sorpresa de su dispositivo (eliminación sin notificación a través de la interfaz de usuario) debe establecer NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK. Al hacerlo, NDIS llama a la función MiniportPnPEventNotify del controlador con PnPEvent establecido en NdisDevicePnPEventSurpriseRemoved cuando se quita el dispositivo del miniporte sin notificación. Además, al establecer NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK suprime la presentación de un cuadro de diálogo de advertencia que pide al usuario que detenga el dispositivo antes de quitarlo.

Un controlador de minipuerto que admita dispositivos sin conexión y orientados a conexiones debe establecer NDIS_ATTRIBUTE_NOT_CO_NDIS si su dispositivo es un dispositivo sin conexión. De lo contrario, NDIS asume erróneamente que su dispositivo está orientado a la conexión, ya que el controlador registra funciones de miniporte orientadas a la conexión con NdisMRegisterMiniport.

En general, un controlador NIC debe llamar a NdisMSetAttributesEx antes de llamar a cualquier función NdisXxx que solicite recursos de hardware en el registro para su NIC, ya que NDIS debe tener el valor AttributeFlags antes de que se realice dicha llamada y porque el controlador normalmente necesita la memoria en MiniportAdapterContext para almacenar información para estas llamadas. Esta restricción implica que la función MiniportInitialize de un controlador NIC no puede llamar a la siguiente NdisXxx antes de llamar a NdisMSetAttributesEx:

Sin embargo, antes de llamar a NdisMSetAttributesEx, cualquier función MiniportInitialize del controlador puede llamar a Ndis.. Funciones de configuración para recuperar la información de configuración instalada en el Registro. MiniportInitialize también puede llamar a las funciones NdisReadXxx específicas del tipo bus, como NdisReadPciSlotInformation, siempre que la entrada del Registro instalada para el tipo de interfaz del controlador coincida con las llamadas NdisReadXxxMiniportInitialize específicas del tipo de bus.

El controlador MiniportAdapterContext proporcionado a NdisMSetAttributesEx se convierte en un parámetro de entrada para todas las funciones MiniportXxx registradas, junto con MiniportInitialize, en la llamada a NdisMRegisterMiniport o NdisIMRegisterLayeredMiniport. Normalmente, este identificador es un puntero a la memoria residente, asignada por MiniportInitialize, en la que el controlador mantiene el estado de tiempo de ejecución específico de la NIC.

  • Plataforma de destino: Universal
  • Versión: no se admite para controladores NDIS 6.0 en Windows Vista. Use NdisMSetMiniportAttributesen su lugar. Compatible con controladores NDIS 5.1 en Windows Vista y Windows XP.

Requisitos

Requisito Valor
Header ndis.h (incluya Ndis.h)
Library Ndis.lib
IRQL PASSIVE_LEVEL

Consulte también