MINIPORT_ADD_DEVICE función de devolución de llamada (ndis.h)

Artículo
02/29/2024

La función MiniportAddDevice permite que un controlador de miniporte establezca un área de contexto para un dispositivo agregado.

Nota Debe declarar la función mediante el tipo MINIPORT_ADD_DEVICE . Para obtener más información, consulte la sección Ejemplos siguientes.

Sintaxis

MINIPORT_ADD_DEVICE MiniportAddDevice;

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

Parámetros

[in] NdisMiniportHandle

Identificador NDIS que identifica el adaptador de minipuerto que está agregando el administrador de Plug and Play (PnP). NDIS también pasa este identificador al Función MiniportInitializeEx .

[in] MiniportDriverContext

Identificador de un área de contexto asignada por el controlador donde el controlador mantiene la información de estado y configuración. El controlador de minipuerto pasó este área de contexto al Función NdisMRegisterMiniportDriver .

Valor devuelto

MiniportAddDevice devuelve uno de los siguientes valores:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	El controlador de minipuerto asignó correctamente los recursos que requiere para agregar el dispositivo.
NDIS_STATUS_RESOURCES	El controlador de minipuerto no pudo asignar los recursos necesarios.
NDIS_STATUS_FAILURE	Error de MiniportAddDevice por motivos distintos de recursos insuficientes.

Si se produce un error en MiniportAddDevice , NDIS no llamará a la función MiniportInitializeEx para inicializar el adaptador de miniport.

Comentarios

La función MiniportAddDevice es una función opcional. Los controladores de minipuerto que admiten MSI-X deben especificar un punto de entrada para esta función en . NDIS_MINIPORT_PNP_CHARACTERISTICS estructura.

MiniportAddDevice puede asignar un área de contexto para controlar IRP_MN_FILTER_RESOURCE_REQUIREMENTS Paquetes de solicitud de E/S (IRP) que el Identificadores de función MiniportFilterResourceRequirements . Los controladores de minipuerto especifican el área de contexto inicializando un NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES estructura y, a continuación, llamando a Función NdisMSetMiniportAttributes . NDIS más adelante proporciona este identificador de contexto al MiniportRemoveDevice, Funciones MiniportFilterResourceRequirements, MiniportStartDevice y MiniportInitializeEx . Para MiniportInitializeEx, el identificador de contexto se pasa en el miembro MiniportAddDeviceContext del NDIS_MINIPORT_INIT_PARAMETERS estructura a la que apunta el parámetro MiniportInitParameters .

Si el controlador de minipuerto produce un error en la llamada a MiniportAddDevice después de asignar el área de contexto, el controlador debe liberar el área de contexto antes de volver de MiniportAddDevice.

Los controladores de minipuerto deben usar un área de contexto diferente para el miembro MiniportAddDeviceContext de la estructura NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES y el miembro MiniportAdapterContext de la estructura NDIS_MINIPORT_INIT_PARAMETERS . Las áreas de contexto independientes garantizarán que la información del área de contexto no se reinicializa, lo que puede producirse en la función MiniportInitializeEx si el adaptador de miniporte está detenido y reinicializado.

Cuando el administrador de PnP solicita que NDIS quite el dispositivo, NDIS llama a la función MiniportRemoveDevice para deshacer las operaciones que realizó MiniportAddDevice .

NDIS llama a MiniportAddDevice en IRQL = PASSIVE_LEVEL.

Ejemplos

Para definir una función MiniportAddDevice , primero debe proporcionar una declaración de función que identifique el tipo de función que está definiendo. Windows proporciona un conjunto de tipos de función para controladores. Declarar una función mediante los tipos de función ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación a encontrar errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una función MiniportAddDevice denominada "MyAddDevice", use el tipo MINIPORT_ADD_DEVICE como se muestra en este ejemplo de código:

MINIPORT_ADD_DEVICE MyAddDevice;

A continuación, implemente la función de la siguiente manera:

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

El tipo de función MINIPORT_ADD_DEVICE se define en el archivo de encabezado Ndis.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función MINIPORT_ADD_DEVICE en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante el uso de tipos de roles de función para controladores NDIS.

Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Se admite en NDIS 6.0 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	PASSIVE_LEVEL