Función PcAddAdapterDevice (portcls.h)

La función PcAddAdapterDevice agrega un dispositivo adaptador a la pila de dispositivos WDM.

Sintaxis

PORTCLASSAPI NTSTATUS PcAddAdapterDevice(
  [in] PDRIVER_OBJECT   DriverObject,
  [in] PDEVICE_OBJECT   PhysicalDeviceObject,
  [in] PCPFNSTARTDEVICE StartDevice,
  [in] ULONG            MaxObjects,
  [in] ULONG            DeviceExtensionSize
);

Parámetros

[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.

Valor devuelto

PcAddAdapterDevice devuelve STATUS_SUCCESS si la llamada se realizó correctamente. De lo contrario, devuelve un código de error adecuado.

Comentarios

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.

Requisitos

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

Consulte también

AddDevice

DEVICE_OBJECT

DRIVER_OBJECT

PcRegisterSubdevice