Función PcAddAdapterDevice (portcls.h)
La función PcAddAdapterDevice agrega un dispositivo adaptador a la pila de dispositivos WDM.
PORTCLASSAPI NTSTATUS PcAddAdapterDevice(
[in] PDRIVER_OBJECT DriverObject,
[in] PDEVICE_OBJECT PhysicalDeviceObject,
[in] PCPFNSTARTDEVICE StartDevice,
[in] ULONG MaxObjects,
[in] ULONG DeviceExtensionSize
);
[in] DriverObject
Puntero al objeto de controlador. Este puntero se pasa como parámetro al controlador AddDevice del adaptador. El objeto driver es una estructura del sistema de tipo DRIVER_OBJECT.
[in] PhysicalDeviceObject
Puntero al objeto de dispositivo físico (PDO) del dispositivo. PortCls pasa este puntero como parámetro de llamada al controlador AddDevice del adaptador. El PDO es una estructura del sistema de tipo DEVICE_OBJECT.
[in] StartDevice
Puntero a la función a la que llama el sistema operativo para iniciar el dispositivo. Para obtener más información, vea la siguiente sección Comentarios .
[in] MaxObjects
Especifica el número máximo de subdispositivos que se van a registrar mediante llamadas a PcRegisterSubdevice. Este recuento establece el límite superior en el número total de objetos de miniport que el controlador del adaptador puede crear instancias.
[in] DeviceExtensionSize
Especifica el tamaño de la extensión del dispositivo. Use cero para el tamaño predeterminado. Consulte la siguiente sección Comentarios para conocer los tamaños de extensión proporcionados por el usuario.
PcAddAdapterDevice devuelve STATUS_SUCCESS si la llamada se realizó correctamente. De lo contrario, devuelve un código de error adecuado.
Esta función realiza la mayor parte del trabajo que debe realizar el controlador AddDevice del controlador del adaptador de audio. PcAddAdapterDevice crea el objeto de dispositivo, inicializa el contexto del dispositivo y conecta el objeto de dispositivo a la pila de dispositivos.
Un controlador de adaptador llama a PcAddAdapterDevice cuando recibe una llamada a su controlador AddDevice . Normalmente, el controlador del adaptador instala el controlador AddDevice llamando a PcInitializeAdapterDriver, aunque el controlador también puede instalar el controlador por otros medios. PcAddAdapterDevice crea el objeto de dispositivo funcional (FDO) para el PDO que se pasó al controlador AddDevice .
DeviceExtensionSize suele ser cero. Es posible que algunos controladores de adaptador necesiten reservar espacio adicional en la extensión del dispositivo, en cuyo caso deben especificar un DeviceExtensionSize mayor que PORT_CLASS_DEVICE_EXTENSION_SIZE, que es el tamaño predeterminado. Cualquier valor mayor que cero y menor que PORT_CLASS_DEVICE_EXTENSION_SIZE es ilegal. Los controladores de adaptador son libres de usar cualquier parte de la extensión del dispositivo después del desplazamiento PORT_CLASS_DEVICE_EXTENSION_SIZE. También son libres de usar bytes en el intervalo de desplazamiento de 16 a 31 inclusive en un sistema con direccionamiento de 32 bits y bytes en el intervalo de desplazamiento de 32 a 63 en un sistema con direccionamiento de 64 bits. Si la extensión se considera una matriz de ULONG_PTR, los elementos de matriz cuatro a siete están disponibles para su uso por parte del controlador del adaptador.
El parámetro StartDevice apunta a una función de tipo PCPFNSTARTDEVICE, que el archivo de encabezado portcls.h define como:
NTSTATUS
(*PCPFNSTARTDEVICE)(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp,
IN PRESOURCELIST ResourceList
);
Para obtener más información sobre PcAddAdapterDevice y las rutinas device-startup del controlador del adaptador y AddDevice , vea Startup Sequence.
En el código de ejemplo siguiente se muestra cómo un controlador de adaptador puede usar el parámetro DeviceExtensionSize para anexar 64 bytes de datos de extensión específicos del dispositivo al final del bloque de almacenamiento que PortCls asigna para el contexto del dispositivo:
#define MY_EXTENSION_SIZE 64
NTSTATUS ntstatus = PcAddAdapterDevice(DriverObject, PhysicalDeviceObject,
MyStartDevice, MAX_MINIPORTS,
MY_EXTENSION_SIZE + PORT_CLASS_DEVICE_EXTENSION_SIZE);
La llamada a PcAddAdapterDevice anterior es similar al ejemplo de La secuencia de inicio, excepto que el último parámetro que se pasa a PcAddAdapterDevice es distinto de cero.
A continuación, el controlador del adaptador puede acceder a los datos de extensión específicos del dispositivo, como se muestra en el siguiente fragmento de código:
PVOID pMyExtensionData = (PVOID)((PCHAR)FunctionalDeviceObject->DeviceExtension +
PORT_CLASS_DEVICE_EXTENSION_SIZE);
La variable FunctionalDeviceObject es un puntero al FDO del adaptador de audio y pMyExtensionData es un puntero temporal a los datos de extensión. Evite confundir el FDO con el PDO, que pertenece al controlador de bus PCI. El controlador del adaptador no debe modificar los datos del PDO porque, al hacerlo, se daña la memoria que posee el controlador de bus PCI y puede provocar que el sistema se bloquee.
Requisito | Value |
---|---|
Cliente mínimo compatible | Disponible a partir de Windows 2000. |
Plataforma de destino | Universal |
Encabezado | portcls.h (incluya Portcls.h) |
Library | Portcls.lib |
IRQL | PASSIVE_LEVEL |