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

Статья
02/07/2025

Примечание 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 возвращает дескриптор, представляющий успешную привязку между вызывающим и заданным физическим или виртуальным сетевым адаптером, указанным в Имя адаптера.

[out] SelectedMediumIndex

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

[in] MediumArray

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

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

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

[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.

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

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

Никакой

Замечания

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

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

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

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

Вызывающий объект использует значение, возвращаемое SelectedMediumIndex при последующих вызовах NdisRequest и/или NdisCoRequest. OIDs, которые он задает в пакете запроса, зависят от возвращаемого NdisMediumXx. Например, если NdisMediumAtm возвращается по SelectedMediumIndex, драйвер протокола вызывает NdisCoRequest при указании OID_ATM_ XXX или OID_CO_кодах XXX и NdisRequest при указании кодов OID_GEN_XXX.

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

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

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

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

Требования

Требование	Ценность
заголовка	ndis.h (include Ndis.h)
библиотеки	Ndis.lib
IRQL	PASSIVE_LEVEL

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

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

Синтаксис

Параметры

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

Замечания

Требования

См. также

Обратная связь

Дополнительные ресурсы