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

Статья
03/10/2023

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

NdisOpenAdapter настраивает привязку между протоколом вызова и конкретным базовым драйвером сетевой карты или промежуточным драйвером NDIS.

Синтаксис

void NdisOpenAdapter(
  [out]          PNDIS_STATUS Status,
  [out]          PNDIS_STATUS OpenErrorStatus,
  [out]          PNDIS_HANDLE NdisBindingHandle,
  [out]          PUINT        SelectedMediumIndex,
  [in]           PNDIS_MEDIUM MediumArray,
  [in]           UINT         MediumArraySize,
  [in]           NDIS_HANDLE  NdisProtocolHandle,
  [in]           NDIS_HANDLE  ProtocolBindingContext,
  [in]           PNDIS_STRING AdapterName,
  [in]           UINT         OpenOptions,
  [in, optional] PSTRING      AddressingInformation
);

Параметры

[out] Status

Указатель на переменную, предоставленную вызывающей стороной, которая может иметь одно из следующих значений при возврате из этой функции:

STATUS_SUCCESS
Запрошенная привязка теперь настроена, чтобы вызывающий объект может использовать значения, возвращенные в NdisBindingHandle и SelectedMediumIndex в последующих вызовах NdisXxx.
NDIS_STATUS_PENDING
Запрошенная операция обрабатывается асинхронно, и функция ProtocolOpenAdapterComplete вызываемого абонента будет вызываться после завершения открытия.
NDIS_STATUS_RESOURCES
Запрошенная операция завершилась сбоем, так как NDIS не удалось выделить достаточный объем памяти или инициализировать состояние, используемое для отслеживания открытой привязки.
NDIS_STATUS_ADAPTER_NOT_FOUND
Запрошенная операция завершилась сбоем, так как имя в AdapterName не удалось найти в пространстве имен системного объекта.
NDIS_STATUS_UNSUPPORTED_MEDIA
В массиве MediumArray не указана среда, поддерживаемая NDIS или базовым драйвером.
NDIS_STATUS_CLOSING
Закрывается вызывающий объект или физическое или виртуальное устройство, указанное в adapterName .
NDIS_STATUS_OPEN_FAILED
Открытая попытка не завершилась сбоем ни по одной из указанных выше причин. Например, возможно, NDIS не удалось инициализировать пакет фильтра для выбранного носителя.

[out] OpenErrorStatus

Указатель на переменную, предоставленную вызывающим методом, которая может содержать ошибку NDIS_STATUS_XXX, предоставляющую дополнительные сведения, если NdisOpenAdapter возвращает ошибку в состоянии. Например, драйвер сетевой карты "Кольцо токена" может возвращать ошибку кольца в этой переменной.

[out] NdisBindingHandle

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

[out] SelectedMediumIndex

Указатель на переменную, предоставленную вызывающим объектом, в которой NDIS возвращает индекс элемента массива, указывающий тип носителя, используемого базовым драйвером NDIS.

[in] MediumArray

Указатель на массив значений типа NDIS_MEDIUM, указывающий типы носителей, которые может поддерживать вызывающий объект. Возможные элементы включают любое правильное подмножество из следующих:

NdisMedium802_3
Указывает сеть Ethernet (802.3).
NdisMedium802_5
Указывает сеть кольцевого токена (802.5).
NdisMediumFddi
Указывает сеть интерфейса FDDI.
NdisMediumWan
Указывает широкую сеть. Этот тип охватывает различные формы сетевых карт типа "точка — точка" и WAN, а также форматы адресов и заголовков, которые должны согласовываться между драйвером протокола и базовым драйвером после установки привязки.
NdisMediumLocalTalk
Указывает сеть LocalTalk.
NdisMediumDix
Указывает сеть Ethernet, для которой драйверы используют формат заголовка DIX Ethernet.
NdisMediumArcnetRaw
Указывает сеть ARCNET.
NdisMediumArcnet878_2
Указывает сеть ARCNET (878.2).
NdisMediumAtm
Указывает сеть банкомата. Клиентские протоколы, ориентированные на подключение, могут привязываться к базовому драйверу мини-порта, который возвращает это значение. В противном случае устаревшие протоколы привязываются к предоставленному системой промежуточному драйверу LanE, который сообщает о своем среднем типе как NdisMedium802_3 или NdisMedium802_5 в зависимости от настройки драйвера LanE администратором сети.
NdisMediumWirelessWan
Указывает беспроводную сеть. Драйверы мини-портов NDIS 5.X, поддерживающие пакеты беспроводной локальной сети (WLAN) или беспроводной глобальной сети (WWAN), объявляют свою среду как NdisMedium802_3 и эмулируют Ethernet для драйверов NDIS более высокого уровня.

Примечание Этот тип мультимедиа недоступен для использования, начиная с Windows Vista.
NdisMediumIrda
Указывает инфракрасную сеть (IrDA).
NdisMediumCoWan
Указывает широкую сеть в среде, ориентированной на подключение.
NdisMedium1394
Указывает сеть IEEE 1394 (пожарный провод).

[in] MediumArraySize

Указывает количество элементов в MediumArray.

[in] NdisProtocolHandle

Указывает дескриптор, возвращаемый NdisRegisterProtocol.

[in] ProtocolBindingContext

Указывает дескриптор для заданной вызывающей абонентской области контекста, в которой протокол сохраняет состояние этой привязки после ее создания.

[in] AdapterName

Указатель на тип NDIS_STRING, содержащий подсчитываемую строку, указанную в системной кодировке по умолчанию, именуя сетевой адаптер или виртуальный адаптер базового драйвера NDIS. Этот драйвер экспортирует набор функций верхнего края (MiniportXxx). Для драйверов Windows 2000 и более поздних версий эта подсчитываемая строка содержит символы Юникода. То есть для Windows 2000 и более поздних версий NDIS определяет тип NDIS_STRING как тип UNICODE_STRING .

[in] OpenOptions

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

[in, optional] AddressingInformation

Указатель на необязательную подсчитываемую строку переменной длины, содержащую сведения, относящиеся к базовому сетевому адаптеру, который драйвер сетевого адаптера может использовать для программирования netcard. Этот указатель может иметь значение NULL.

Если он указан, сведения об адресации должны оставаться действительными до завершения операции открытия. Базовый драйвер сетевого адаптера, поддерживающий асинхронный модем, может использовать эти сведения для набора номера.

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

None

Remarks

Драйвер протокола вызывает NdisOpenAdapter из своей функции ProtocolBindAdapter . NDIS больше не поддерживает вызов NdisOpenAdapter из функции DriverEntry , которая была доступна для устаревших протоколов (версии 3.0). NDIS больше не поддерживает протоколы версии 3.0. NDIS не выполняет любую попытку вызова NdisOpenAdapter вне контекста ProtocolBindAdapter.

Строка в AdapterName остается действительной только до тех пор, пока NdisOpenAdapter не вернет управление, даже если она возвращает NDIS_STATUS_PENDING в состояние.

Переменные в NdisBindingHandle и SelectedMediumIndex следует игнорировать, пока функция ProtocolOpenAdapterComplete не будет вызвана , если NdisOpenAdapter возвращает NDIS_STATUS_PENDING. Поскольку эти переменные могут оставаться недопустимыми до вызова ProtocolOpenAdapterComplete , они не могут находиться в стеке. Обычно эти переменные находятся в области ProtocolBindingContext , так как этот дескриптор является входным параметром для ProtocolOpenAdapterComplete.

Драйвер протокола должен хранить дескриптор, возвращенный в NdisProtocolHandle. Это обязательный параметр для других функций NdisXxx , которые драйвер вызывает впоследствии. Предоставленный protocolBindingContext является входным параметром функций ProtocolXxx вызывающего объекта, поэтому протоколы обычно передают указатель NdisProtocolHandle в переменную в области контекста, выделенной вызывающим объектом, в своих вызовах к NdisOpenAdapter.

Вызывающий объект использует значение, возвращаемое в SelectedMediumIndex , в последующих вызовах NdisRequest и (или) NdisCoRequest. Идентификаторы OID, которые он задает в пакете запроса, зависят от возвращенного объекта NdisMediumXxx. Например, если NdisMediumAtm возвращается в SelectedMediumIndex, драйвер протокола вызывает NdisCoRequest при указании кодов OID_ATM_ XXX или OID_CO_XXX и NdisRequest при указании кодов OID_GEN_XXX .

Если NdisMediumWan возвращается в SelectedMediumIndex, драйвер протокола вызывает NdisRequest , указывая OID_WAN_MEDIUM_SUBTYPE в запросе, чтобы определить, какой из типов носителей глобальной сети использует базовый драйвер.

Если ранее выданный глобальный запрос OID_NETWORK_TYPE для беспроводного носителя указывает, что драйвер и базовый сетевой адаптер поддерживают несколько носителей типа NdisMediumWirelessWan, протокол должен выбрать один из поддерживаемых носителей сразу после настройки привязки NDIS и перед тем, как протокол выберет формат заголовка.

Дополнительные сведения об общих и средних идентификаторах OID, используемых драйверами протоколов для согласования с драйвером NDIS, см. в разделе Идентификаторы объектов NDIS.

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

Требования

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