Функция 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, содержащий строку Юникода, завершающую значение NULL, которая называет объект устройства. Строка должна быть полным именем- например, \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 или Power Management, так как созданный объект устройства не предназначен для физического устройства и поэтому не получает irPs Plug and Power Management или Plug and Power Management.

[in] pDeviceObject

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

[out] NdisDeviceHandle

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

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

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

Замечания

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

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

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

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

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

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

  1. Когда приложение регистрирует уведомление о событиях устройства на базовом устройстве путем вызова функции RegisterDeviceNotification, укажите фильтр уведомлений типа DBT_DEVTYP_HANDLE. (Дополнительные сведения о функции RegisterDeviceNotification см. в документации по пакету SDK для Microsoft Windows.) Если приложение впоследствии получает событие 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 (include Ndis.h)
библиотеки Ndis.lib
IRQL PASSIVE_LEVEL

См. также

  • Last updated on