функция обратного вызова MINIPORT_ADD_DEVICE (ndis.h)

Статья
08/07/2023

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

Примечание Функцию необходимо объявить с помощью типа MINIPORT_ADD_DEVICE . Дополнительные сведения см. в следующем разделе Примеры.

Синтаксис

MINIPORT_ADD_DEVICE MiniportAddDevice;

NDIS_STATUS MiniportAddDevice(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext
)
{...}

Параметры

[in] NdisMiniportHandle

Дескриптор NDIS, определяющий адаптер мини-порта, добавляемый диспетчером Plug and Play (PnP). NDIS также передает этот дескриптор вФункция MiniportInitializeEx.

[in] MiniportDriverContext

Дескриптор выделенной драйвером контекстной области, в которой драйвер хранит сведения о состоянии и конфигурации. Драйвер мини-порта передал эту область контекста вФункция NdisMRegisterMiniportDriver.

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

MiniportAddDevice возвращает одно из следующих значений:

Код возврата	Описание
NDIS_STATUS_SUCCESS	Драйвер мини-порта успешно выделил ресурсы, необходимые для добавления устройства.
NDIS_STATUS_RESOURCES	Драйверу мини-порта не удалось выделить необходимые ресурсы.
NDIS_STATUS_FAILURE	Сбой MiniportAddDevice по другим причинам, кроме нехватки ресурсов.

В случае сбоя MiniportAddDevice NDIS не будет вызывать функцию MiniportInitializeEx для инициализации адаптера мини-порта.

MiniportAddDevice может выделить область контекста для обработки IRP_MN_FILTER_RESOURCE_REQUIREMENTS Пакеты запросов ввода-вывода (IRP), которые Дескриптор функции MiniportFilterResourceRequirements . Драйверы мини-порта задают область контекста путем инициализации NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES структуры, а затем вызовитеФункция NdisMSetMiniportAttributes. Позже NDIS предоставляет этот дескриптор контекста для MiniportRemoveDevice.Функции MiniportFilterResourceRequirements, MiniportStartDevice и MiniportInitializeEx. Для MiniportInitializeEx дескриптор контекста передается в элементе MiniportAddDeviceContext элемента NDIS_MINIPORT_INIT_PARAMETERS структура, на которую указывает параметр MiniportInitParameters .

Если драйвер мини-порта не выполняет вызов MiniportAddDevice после выделения области контекста, драйвер должен освободить область контекста перед возвращением из MiniportAddDevice.

Драйверы miniport должны использовать другую область контекста для элемента MiniportAddDeviceContext структуры NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES и элемента MiniportAdapterContextструктуры NDIS_MINIPORT_INIT_PARAMETERS . Отдельные области контекста гарантируют, что информация в области контекста не будет повторно инициализирована, что может произойти в функции MiniportInitializeEx , если адаптер мини-порта остановлен и повторно инициализирован.

Когда диспетчер PnP запрашивает удаление устройства NDIS, NDIS вызывает функцию MiniportRemoveDevice для отмены операций, выполненных MiniportAddDevice .

NDIS вызывает MiniportAddDevice по адресу IRQL = PASSIVE_LEVEL.

Примеры

Чтобы определить функцию MiniportAddDevice , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции. Windows предоставляет набор типов функций для драйверов. Объявление функции с помощью типов функций помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить функцию MiniportAddDevice с именем MyAddDevice, используйте тип MINIPORT_ADD_DEVICE , как показано в следующем примере кода:

MINIPORT_ADD_DEVICE MyAddDevice;

Затем реализуйте функцию следующим образом:

_Use_decl_annotations_
NDIS_STATUS
 MyAddDevice(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext
    )
  {...}

Тип функции MINIPORT_ADD_DEVICE определен в файле заголовка Ndis.h. Чтобы более точно определить ошибки при запуске средств анализа кода, не забудьте добавить заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует использование заметок, которые применяются к типу функции MINIPORT_ADD_DEVICE в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в статье Объявление функций с помощью типов ролей функций для драйверов NDIS.

Сведения о Use_decl_annotations см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в NDIS 6.0 и более поздних версиях.
Целевая платформа	Windows
Header	ndis.h (включая Ndis.h)
IRQL	PASSIVE_LEVEL