Поделиться через

Функция 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 с интервалом NDIS по умолчанию в 2 секунды.

Если вызывающий объект задает 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 драйвера сетевого адаптера token Ring, если указаны ошибки кольца токена.

  • 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) перед вызовом любой другой функции NdisMRegisterXxx или NdisXxx , которая зависит от сведений, предоставляемых NdisMSetAttributesEx. Например, вызов драйвера сетевой карты к NdisMAllocateMapRegisters завершится ошибкой, если MiniportInitialize еще не вызвал NdisMSetAttributesEx с атрибутом AttributeFlags , заданным с NDIS_ATTRIBUTE_BUS_MASTER.

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

Десериализованные драйверы также должны вызывать NdisMSetAttributesEx и задавать NDIS_ATTRIBUTE_DESERIALIZE в AttributeFlags. NDIS не поддерживает очередь отправки пакетов для десериализованного драйвера, а 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 значениемNdisDevicePnPEventSurpriseRemoved при удалении устройства минипорта без уведомления. Кроме того, установка NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK подавляет отображение диалогового окна с предупреждением, которое предлагает пользователю остановить устройство перед его удалением.

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

Как правило, драйвер сетевого адаптера должен вызывать NdisMSetAttributesEx перед вызовом любой функции NdisXxx, которая запрашивает аппаратные ресурсы в реестре для своего сетевого адаптера, так как NDIS должно иметь значение AttributeFlags перед таким вызовом и поскольку драйверу обычно требуется память в MiniportAdapterContext для хранения информации для этих вызовов. Это ограничение подразумевает, что функция MiniportInitialize драйвера сетевого адаптера не может вызвать следующий NdisXxx перед вызовом 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

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