Функция NdisMSetAttributesEx (ndis.h)

  • Статья

Примечание NDIS 5. X является нерекомендуемым и заменен NDIS 6. x. Сведения о разработке новых драйверов NDIS см. в статье Сетевые драйверы, начиная с Windows Vista. Сведения о переносе NDIS 5. x драйверы для NDIS 6. x, см. раздел Перенос драйверов NDIS 5.x в NDIS 6.0.

NdisMSetAttributesEx информирует библиотеку NDIS о важных функциях сетевого адаптера или виртуального сетевого адаптера вызывающего объекта во время инициализации.

Синтаксис

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

Параметры

[in] MiniportAdapterHandle

Указывает входные данные дескриптора для MiniportInitialize.

[in] MiniportAdapterContext

Указывает дескриптор для области постоянного контекста, выделенной MiniportInitialize.

[in, optional] CheckForHangTimeInSeconds

Указывает интервал в секундах, через который NDIS должен вызывать функцию MiniportCheckForHang . Если драйвер не ответил на запрос OID или отправил запрос в течение двух последовательных вызовов MiniportCheckForHang, NDIS может вызвать функцию MiniportReset драйвера.

Фактический интервал, который NDIS использует при вызове MiniportCheckForHang , всегда равен 2 секундам. Например, если вы указываете 5 секунд, фактический интервал будет примерно 4 секунды.

Указание нуля для этого параметра означает, что NDIS должен вызывать MiniportCheckForHang с 2-секундным интервалом NDIS по умолчанию.

Если вызывающий объект задает NDIS_ATTRIBUTE_DESERIALIZE в AttributeFlags, NDIS не помещает в очередь ожидающие отправки для драйвера мини-порта. Вместо этого такой десериализованный драйвер должен управлять собственной очередью последующих запросов на отправку, когда у него недостаточно ресурсов для немедленной передачи входящего сообщения.

[in] AttributeFlags

Указывает битовую маску, которую можно задать с помощью одного или нескольких (ORed) следующих флагов:

  • NDIS_ATTRIBUTE_BUS_MASTER
    Укажите, является ли сетевой адаптер вызывающего абонента устройством DMA master шины.

  • NDIS_ATTRIBUTE_DESERIALIZE
    Установите значение , если вызывающий объект является десериализованным драйвером мини-порта.

  • NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT
    Установите значение , если NDIS не должен пытаться и времени ожидания отправки пакетов, которые он хранит в очереди для вызывающего абонента. Промежуточные драйверы должны устанавливать этот флаг, а драйверы сетевого адаптера — нет.

  • NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT
    Задайте значение , если NDIS не должен пытаться выполнить ожидающий запрос и задать запросы, которые он удерживает в очереди, к вызывающему объекту. Промежуточные драйверы должны устанавливать этот флаг, а драйверы сетевого адаптера — нет.

  • NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER
    Установите значение , если вызывающий объект является промежуточным драйвером.

  • NDIS_ATTRIBUTE_IGNORE_TOKEN_RING_ERRORS
    Установите значение , если NDIS не должен вызывать функцию MiniportReset драйвера NIC для маркерного кольца, если указаны ошибки кольца токенов.

  • NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND
    Установите значение , если NDIS не должен вызывать функцию MiniportHalt драйвера, прежде чем система перейдет в маломощное (спящее) состояние. Драйверы, использующие состояние, поддерживаемое оборудованием, не должны устанавливать этот флаг.

    Примечание Установка этого флага отключает поле Разрешить компьютеру отключить это устройство для экономии питания проверка на вкладке Управление питанием диалогового окна Свойства для сетевого интерфейса карта (NIC). Управление питанием отключено, даже если сетевой адаптер поддерживает управление питанием.

  • NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK
    Установите значение , если драйвер может обрабатывать удаление сетевого адаптера без уведомления пользователя. Такой драйвер экспортирует функцию MiniportPnPEventNotify . Системная поддержка NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK доступна в операционных системах Windows XP и более поздних версий.

  • NDIS_ATTRIBUTE_NOT_CO_NDIS
    Устанавливается драйвером, который может поддерживать как устройства, ориентированные на подключение, так и устройства без подключения, чтобы указать, что устройство является устройством без подключения. Системная поддержка NDIS_ATTRIBUTE_NOT_CO_NDIS доступна в операционных системах Windows XP и более поздних версий.

  • NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS
    Устанавливается драйвером, использующим NdisBufferVirtualAddressSafe, NdisGetFirstBufferFromPacketSafe и NdisQueryBufferSafe исключительно для доступа к системным виртуальным адресам для буферов пакетов отправки. NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS также устанавливается драйвером, который использует исключительно физические адреса для доступа к таким буферам. Настройка NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS может повысить производительность, так как операционной системе не придется сопоставлять буферы отправки пакетов с системными виртуальными адресами. Системная поддержка NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS доступна в Windows XP и более поздних версиях.

  • NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO
    Устанавливается драйвером мини-порта CoNDIS, который не предоставляет службы TAPI. Настройка NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO не позволяет NDIS привязать драйвер мини-порта к драйверу прокси-сервера NDIS TAPI (NDPROXY). По умолчанию NDIS привязывает NDPROXY ко всем драйверам мини-портов CoNDIS.

[in, optional] AdapterType

Указывает тип интерфейса шины ввода-вывода сетевого адаптера вызывающего объекта, который обычно является типом шины ввода-вывода, к которой подключен сетевой адаптер, в качестве одного из следующих:

  • NdisInterfaceInternal
    Указывает внутренний интерфейс для конкретного узла.

  • NdisInterfaceIsa
    Указывает интерфейс ISA.

  • NdisInterfaceEisa
    Указывает расширенный интерфейс ISA (EISA).

  • NdisInterfaceMca
    Это относится к шине MCA, которая больше не поддерживается.

  • NdisInterfaceTurboChannel
    Указывает интерфейс Turbo Channel.

  • NdisInterfacePci
    Указывает интерфейс PCI.

  • NdisInterfacePcMcia
    Указывает интерфейс Международной ассоциации карт памяти персонального компьютера (PC Card).

Этот параметр не имеет значения для промежуточных драйверов, которые должны передавать ноль для этого аргумента в NdisMSetAttributesEx.

Возвращаемое значение

None

Remarks

Функция MiniportInitialize должна вызывать NdisMSetAttributesEx(или NdisMSetAttributes) перед вызовом любой другой функции NdisMRegisterXxxx или NdisXxx, которая зависит от информации, предоставленной NdisMSetAttributesEx. Например, вызов драйвера сетевой карты к NdisMAllocateMapRegisters завершится ошибкой, если MiniportInitialize еще не вызвал NdisMSetAttributesEx с атрибутом AttributeFlags , заданным с NDIS_ATTRIBUTE_BUS_MASTER.

Промежуточные драйверы должны вызывать NdisMSetAttributesEx, а не NdisMSetAttributes и задавать NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER в AttributeFlags. Установка этого флага приводит к тому, что NDIS будет рассматривать промежуточный драйвер как полнодуплексный драйвер минипорта, что предотвращает редкие, но периодические взаимоблокировки в промежуточном драйвере. Следовательно, каждый промежуточный драйвер должен быть способен обрабатывать параллельные отправки и указания.

Десериализованные драйверы также должны вызывать NdisMSetAttributesEx и задавать NDIS_ATTRIBUTE_DESERIALIZE в AttributeFlags. NDIS не поддерживает очередь отправки пакетов для десериализованного драйвера и не сериализует вызовы функций MiniportXxx такого драйвера. Десериализованный драйвер отвечает за следующее:

  • Принятие всех входящих запросов на отправку
  • Постановка в очередь входящих пакетов отправки, если это необходимо, например, если у десериализованного драйвера сетевого адаптера в настоящее время недостаточно ресурсов для немедленной передачи входящего пакета отправки
  • Синхронизация доступа к внутренним очередям по мере необходимости между подпрограммами драйвера
  • Выполнение всех запрошенных отправки выполняется асинхронно путем последующего вызова NdisMSendComplete с каждым дескриптором пакета, предоставленным протоколом, передаваемым в функцию Miniport(Co)Send(Packets)

NDIS предполагает, что все минипорты, ориентированные на подключение, являются десериализованными драйверами, независимо от attributeFlags , которые они передают в NdisMSetAttributesEx. То есть любой драйвер, вызывающий NdisMRegisterMiniport с 0x05 в качестве MajorNdisVersion , должен быть десериализованным драйвером мини-порта.

Сериализованные драйверы сетевого адаптера могут вызывать какую-либо из этих функций из MiniportInitialize, но NdisMSetAttributes не позволяет вызывающему объекту настраивать интервал, через который вызываются функции MiniportCheckForHang драйвера сетевой карты и (или) MiniportReset .

Значение CheckForHangTimeInSeconds определяет интервал времени ожидания библиотеки NDIS при отправке, если таковые имеются, и запросы, которые она хранит в очереди вызывающему объекту. По умолчанию NDIS время ожидания отправки в очередь (только для сериализованных драйверов) и запросы в два раза превышает интервал проверка для зависания, после чего вызывает функцию MiniportReset, если драйвер не задает AttributeFlags с NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT и NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT при вызове NdisMSetAttributesEx. Промежуточные драйверы должны устанавливать эти флаги при вызове NdisMSetAttributesEx , так как такой драйвер не может определить или контролировать, когда базовый драйвер сетевой карты будет обрабатывать отправки и запросы.

Драйверы сетевых карт не должны устанавливать флаги NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT и NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT, хотя NDIS будет учитывать такую спецификацию сериализованным драйвером сетевого адаптера. Однако драйверы сетевых карт могут настроить интервал времени ожидания, через который вызываются их функции MiniportReset , задав явное значение CheckForHangTimeInSeconds. Например, драйвер сетевой карты, эмулирующий Ethernet через модем, может не завершить каждый пакет в течение интервала времени ожидания по умолчанию для библиотеки NDIS. Всякий раз, когда в таком сетевом адаптере появляется время ожидания пакета, NDIS предполагает, что сетевой адаптер больше не работает правильно, и вызывает функцию MiniportReset драйвера. Для драйвера такого сетевого адаптера вызов NdisMSetAttributesEx с параметром CheckForHangTimeInSeconds , для которого задано значение, превышающее два, предотвращает ненужные сбросы и увеличивает интервал вызова функции MiniportCheckForHang для проверки рабочего состояния сетевого адаптера.

Промежуточный драйвер должен установить флаг NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND. Установка этого флага предотвращает остановку драйвера NDIS до перехода системы в состояние с низким энергопотреблением (спящий режим).

Устаревший драйвер мини-порта, который управляет сетевой картой, не поддерживающей PnP, может установить флаг NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND, чтобы предотвратить остановку NDIS драйвера до перехода системы в состояние с низким энергопотреблением. Если драйвер мини-порта устанавливает этот флаг, NDIS запрашивает у водителя мини-порта OID_PNP_CAPABILITIES даже если водитель автобуса для сетевой карты водителя минипорта, возможно, указал, что сетевой адаптер не учитывает PM. Драйвер мини-порта должен выполнить запрос OID_PNP_CAPABILITIES с NDIS_STATUS_SUCCESS. В структуре NDIS_PM_WAKE_UP_CAPABILITIES, возвращаемой этим OID, драйвер мини-порта также должен указать состояние питания устройства NdisDeviceStateUnspecified для каждой возможности пробуждения. Когда система переходит в маломощное состояние, NDIS не будет вызывать функцию MiniportHalt такого драйвера минипорта. Прежде чем система перейдет в состояние меньшей мощности, драйвер мини-порта должен сохранить любой аппаратный контекст, который он поддерживает. При получении запроса OID_PNP_SET_POWER к состоянию D3 драйвер мини-порта должен задать для своего сетевого адаптера соответствующее состояние для состояния с низким энергопотреблением. При получении запроса OID_PNP_SET_POWER к состоянию D0 драйвер мини-порта должен задать для своего сетевого адаптера соответствующее состояние для рабочего состояния.

Драйвер мини-порта, поддерживающий неожиданное удаление устройства (удаление без уведомления через пользовательский интерфейс), должен задать NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK. Это приводит к тому, что NDIS вызывает функцию MiniportPnPEventNotify драйвера с PnPEvent, для параметра PnPEvent задано значение NdisDevicePnPEventSurpriseRemoved при удалении устройства минипорта без уведомления. Кроме того, установка NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK подавляет отображение диалогового окна с предупреждением, которое предлагает пользователю остановить устройство перед его удалением.

Драйвер мини-порта, который может поддерживать как устройства без подключения, так и устройства, ориентированные на подключение, должны задать NDIS_ATTRIBUTE_NOT_CO_NDIS, если его устройство является устройством без подключения. В противном случае NDIS ошибочно предполагает, что устройство ориентировано на подключение, так как драйвер регистрирует функции драйвера мини-порта, ориентированные на подключение, с помощью NdisMRegisterMiniport.

Как правило, драйвер сетевого адаптера должен вызывать NdisMSetAttributesEx перед вызовом любой функции NdisXxxx, которая утверждает аппаратные ресурсы в реестре для своего сетевого адаптера, так как NDIS должно иметь значение AttributeFlags перед таким вызовом и потому, что драйверу обычно требуется память в MiniportAdapterContext для хранения информации для этих вызовов. Это ограничение подразумевает, что функция MiniportInitialize драйвера сетевого адаптера не может вызвать следующий NdisXxxx перед вызовом NdisMSetAttributesEx:

Однако перед вызовом NdisMSetAttributesEx функция MiniportInitialize драйвера может вызвать Ndis.. Функции конфигурации для получения сведений о конфигурации, установленных в реестре. MiniportInitialize также может вызывать функции NdisReadXxx для конкретного типа шины, такие как NdisReadPciSlotInformation, при условии, что установленная запись реестра для типа интерфейса драйвера соответствует вызовам NdisReadXxxxMiniportInitialize для конкретного типа шины.

Дескриптор MiniportAdapterContext , предоставленный NdisMSetAttributesEx , становится входным параметром для всех функций MiniportXxx, которые были зарегистрированы вместе с MiniportInitialize в вызове NdisMRegisterMiniport или NdisIMRegisterLayeredMiniport. Как правило, этот дескриптор является указателем на резидентную память, выделенную MiniportInitialize, в которой драйвер поддерживает состояние времени выполнения для конкретной сетевой карты.

  • Целевая платформа: универсальная
  • Версия: не поддерживается для драйверов NDIS 6.0 в Windows Vista. Вместо этого используйте NdisMSetMiniportAttributes. Поддерживается для драйверов NDIS 5.1 в Windows Vista и Windows XP.

Требования

Требование Значение
Заголовок ndis.h (включая Ndis.h)
Библиотека Ndis.lib
IRQL PASSIVE_LEVEL

См. также раздел