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

Статья
08/07/2023

Функция NdisIMInitializeDeviceInstanceEx инициирует операцию инициализации виртуального мини-порта и при необходимости настраивает сведения о состоянии виртуального мини-порта для последующих связанных драйверов протокола.

Синтаксис

NDIS_STATUS NdisIMInitializeDeviceInstanceEx(
  [in]           NDIS_HANDLE  DriverHandle,
  [in]           PNDIS_STRING DriverInstance,
  [in, optional] NDIS_HANDLE  DeviceContext
);

Параметры

[in] DriverHandle

Дескриптор драйвера мини-порта, которыйФункция NdisMRegisterMiniportDriver возвращает значение в NdisMiniportDriverHandle .

[in] DriverInstance

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

[in, optional] DeviceContext

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

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

NdisIMInitializeDeviceInstanceEx может возвращать одно из следующих элементов:

Код возврата	Описание
NDIS_STATUS_SUCCESS	NDIS инициировал операцию инициализации виртуального мини-порта промежуточного драйвера.
NDIS_STATUS_NOT_ACCEPTED	Сбой NdisIMInitializeDeviceInstanceEx , так как устройство, указанное в DriverHandle , уже инициализировано.

Промежуточный драйвер NDIS должен вызывать NdisIMInitializeDeviceInstanceEx из функции ProtocolBindAdapterEx . Сбой вызова NdisIMInitializeDeviceInstanceEx из промежуточного драйвера NDIS фактически предотвращает успешную загрузку этого драйвера.

Перед вызовом NdisIMInitializeDeviceInstanceEx функция ProtocolBindAdapterEx промежуточного драйвера должна быть привязана к любым базовым драйверам минипорта, необходимым для работы промежуточного драйвера. Функция ProtocolBindAdapterEx также может выделить область в DeviceContext , возможно, задав для нее промежуточные сведения о возможностях базового адаптера минипорта, собранные ProtocolBindAdapterEx. Функция MiniportInitializeEx промежуточного драйвера может впоследствии использовать эти сведения для настройки этой области контекста со сведениями о виртуальном минипорте драйвера.

Вызов промежуточного драйвера к NdisIMInitializeDeviceInstanceEx приводит к тому, что NDIS вызывает функцию MiniportInitializeEx промежуточного драйвера, если NDIS получает IRP_MN_START_DEVICE IRP для запуска устройства. Если NDIS не получает такой IRP, NDIS не будет вызывать функцию MiniportInitializeEx промежуточного драйвера.

Вызов MiniportInitializeEx может произойти позже и, следовательно, не обязательно находится в контексте вызова NdisIMInitializeDeviceInstanceEx. Если NDIS никогда не вызывает MiniportInitializeEx для виртуального мини-порта, на который ссылается вызов NdisIMInitializeDeviceInstanceEx , и промежуточный драйвер больше не требует виртуального мини-порта, промежуточный драйвер должен вызвать Функция NdisIMCancelInitializeDeviceInstance для отмены инициализации виртуального мини-порта. Например, предположим, что промежуточный драйвер создает виртуальный минипорт в ответ на успешную привязку к базовому адаптеру мини-порта. Если эта привязка удаляется до вызова NDIS MiniportInitializeEx, промежуточный драйвер должен вызвать NdisIMCancelInitializeDeviceInstance , чтобы отменить инициализацию виртуального мини-порта.

MiniportInitializeEx выделяет все ресурсы, необходимые драйверу для выполнения сетевых операций ввода-вывода, таких как вызов Функция NdisMSetMiniportAttributes и для инициализации виртуального минипорта драйвера в рабочее состояние. Затем драйверы протокола более высокого уровня могут привязаться к виртуальному минипорту после успешного завершения инициализации промежуточного драйвера.

После того как MiniportInitializeEx вернет управление, область контекста устройства промежуточного драйвера ( если она есть) может содержать любые данные, определяемые промежуточным драйвером, которые впоследствии позволяют всем драйверам протокола более высокого уровня, привязанным к тому же виртуальному минипорту, получать доступ к информации в этой области контекста. Такой драйвер протокола более высокого уровня может запрашивать контекст устройства, предоставленный промежуточным драйвером, с помощьюФункция NdisIMGetBindingContext.

Прежде чем NDIS вызывает функцию MiniportInitializeEx промежуточного драйвера, драйвер может вызвать NdisIMCancelInitializeDeviceInstance для отмены операции инициализации.

После того как NDIS вызывает функцию MiniportInitializeEx промежуточного драйвера, драйвер должен вызвать NdisIMDeInitializeDeviceInstance для отмены операции инициализации.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается для драйверов NDIS 6.0 и NDIS 5.1 (см. раздел NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) в Windows Vista. Поддерживается для драйверов NDIS 5.1 (см. раздел NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) в Windows XP.
Целевая платформа	Персональный компьютер
Верхняя часть	ndis.h (включая Ndis.h)
Библиотека	Ndis.lib
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	Irql_IM_Function(ndis)