Функция NdisIMInitializeDeviceInstanceEx (ndis.h)
Функция 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 инициировала операцию инициализации для виртуального минипорта промежуточного драйвера. |
|
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, промежуточный драйвер должен вызывать NdisIMCanitializeDeviceInstance, чтобы отменить инициализацию виртуального минипорта.
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 (include Ndis.h) |
| библиотеки | Ndis.lib |
| IRQL | PASSIVE_LEVEL |
| правил соответствия DDI | Irql_IM_Function(ndis) |