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

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

  • Статья

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

Функция NdisMRegisterDevice создает именованный объект устройства и символьную связь между объектом устройства и именем, видимым пользователем для этого устройства.

Синтаксис

NDIS_STATUS NdisMRegisterDevice(
  [in]  NDIS_HANDLE      NdisWrapperHandle,
  [in]  PNDIS_STRING     DeviceName,
  [in]  PNDIS_STRING     SymbolicName,
  [in]  PDRIVER_DISPATCH *MajorFunctions,
  [in]  PDEVICE_OBJECT   *pDeviceObject,
  [out] NDIS_HANDLE      *NdisDeviceHandle
);

Параметры

[in] NdisWrapperHandle

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

[in] DeviceName

Указатель на тип NDIS_STRING, содержащий строку Юникода с пустым завершением, которая называет объект устройства. Строка должна быть полным путем, например \Device\DeviceName. Для Windows 2000 и более поздних версий NDIS определяет тип NDIS_STRING как тип UNICODE_STRING .

[in] SymbolicName

Указатель на тип NDIS_STRING, содержащий строку Юникода, которая является видимым в Win32 именем регистрируемого устройства. Как правило, символьное имя имеет следующий формат: \DosDevices\SymbolicName.

[in] MajorFunctions

Указатель на массив из одной или нескольких точек входа для подпрограмм диспетчеризации драйвера устройства. Драйвер должен задать столько отдельных точек входа диспетчеризации, сколько кодов IRP_MJ_XXX , обрабатываемых драйвером для объекта устройства. Каждая подпрограмма диспетчеризации объявляется следующим образом:

NTSTATUS
(*PDRIVER_DISPATCH) (
    IN PDEVICE_OBJECT Device Object,
    IN PIRP Irp
)   ;

Драйвер не должен предоставлять точки входа для обработчиков Plug and Play или управления питанием, так как созданный объект устройства не предназначен для физического устройства и поэтому не получает Plug and Play или irP управления питанием.

[in] pDeviceObject

Указатель на созданный объект устройства, если вызов выполнен успешно.

[out] NdisDeviceHandle

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

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

NdisMRegisterDevice возвращает STATUS_SUCCESS в случае успеха, NDIS_STATUS_NOT_SUPPORTED, если вызывающий объект не является драйвером мини-порта NDIS, или код сбоя в случае сбоя.

Комментарии

Для промежуточного драйвера или драйвера мини-порта может потребоваться отдельный автономный объект устройства. Например, драйверу промежуточного мини-порта может потребоваться автономный объект устройства для отслеживания состояния базовой сетевой карты, когда драйвер мини-порта сетевой карты не работает. Чтобы получить состояние сетевой карты в таком случае, приложение или подсистема среды пользовательского режима отправляет IRP объекту устройства. IRP обрабатывается промежуточным драйвером. Без автономного объекта устройства состояние сетевого адаптера доступно только в том случае, если драйвер мини-порта сетевой карты запущен и работает.

Промежуточный драйвер или драйвер мини-порта создает объект устройства, вызывая NdisMRegisterDevice из функции DriverEntry после того , как DriverEntry вызвал NdisMInitializeWrapper. NdisMRegisterDevice создает именованный объект устройства, а также символьную связь между именем объекта устройства и именем, видимым пользователем для этого устройства. Если вызов NdisMRegisterDevice завершается успешно, диспетчер ввода-вывода выделяет хранилище в непагрегированном пуле для самого объекта устройства и для всех других структур данных, связанных с объектом устройства, включая расширение устройства драйвера. Расширение устройства для объекта, созданного с помощью NdisMRegisterDevice , зарезервировано для использования NDIS и не может использоваться драйвером.

Объект устройства, созданный с помощью функций NdisMRegisterDevice , так же, как объект устройства и символьная ссылка, созданные с помощью IoCreateDevice и IoCreateSymbolicLink соответственно. Драйвер мини-порта отвечает за обработку всех irP, получаемых для объекта устройства. (NDIS обрабатывает все Plug and Play и irP управления питанием, отправленные объекту устройства.) Драйвер обрабатывает irp, отправленные объекту устройства, с помощью подпрограмм диспетчеризации, которые он зарегистрировал при указании указателя MajorFunctions на NdisMRegisterDevice. Дополнительные сведения об объектах устройств, irP и подпрограммах диспетчеризации см. в разделах Объекты устройств и стеки устройств, Обработка irP и Написание подпрограмм диспетчеризации.

Драйверы NDIS miniport и промежуточные драйверы никогда не должны вызывать IoCreateDevice или IoCreateSymbolicLink. Вместо этого, если драйвер NDIS должен создать объект устройства, он должен вызвать NdisMRegisterDevice. Драйверы miniport и промежуточные драйверы никогда не должны пытаться сложить объект устройства поверх физического объекта устройства путем вызова IoAttachDevice.

Объект устройства, созданный с помощью NdisMRegisterDevice, не является физическим объектом устройства и поэтому не получает Plug and Play или irP управления питанием. Поэтому вызывающие элементы NdisMRegisterDevice должны пропускать точки входа для обработчиков Plug and Play или управления питанием в массиве, на который указывает MajorFunctions.

Обратите внимание, что если открыт дескриптор объекта устройства, созданного с помощью NdisMRegisterDevice , драйвер, создавший объект устройства, не может быть выгружен. Поэтому приложение в пользовательском режиме должно выполнять одно из следующих действий:

  1. Когда приложение регистрирует уведомление о событиях устройства на базовом устройстве путем вызова функции RegisterDeviceNotification , укажите фильтр уведомлений типа DBT_DEVTYP_HANDLE. (Дополнительные сведения о функции RegisterDeviceNotification см. в документации по Microsoft Windows SDK.) Если приложение впоследствии получает событие DBT_DEVICEQUERYREMOVE для устройства, приложение должно закрыть открытый дескриптор.

  2. Когда приложение регистрируется для уведомления о событиях устройства на базовом устройстве путем вызова функции RegisterDeviceNotification , укажите фильтр уведомлений типа DBT_DEVTYP_DEVICEINTERFACE и GUID_NDIS_LAN_CLASS в качестве GUID класса интерфейса. Если впоследствии приложение получает событие DBT_DEVICEREMOVECOMPLETE для интерфейса устройства, которому соответствует дескриптор, приложение должно закрыть открытый дескриптор.

Если вызов драйвера к NdisMRegisterDevice завершается сбоем, драйвер может продолжать загружаться или нет в зависимости от того, насколько важен автономный объект устройства для работы драйвера.

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

Требования

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

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