Funzione PcAddAdapterDevice (portcls.h)

La funzione PcAddAdapterDevice aggiunge un dispositivo adapter allo stack di dispositivi WDM.

Sintassi

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

Parametri

[in] DriverObject

Puntatore all'oggetto driver. Questo puntatore viene passato come parametro al gestore AddDevice dell'adattatore. L'oggetto driver è una struttura di sistema di tipo DRIVER_OBJECT.

[in] PhysicalDeviceObject

Puntatore all'oggetto dispositivo fisico (PDO) del dispositivo. PortCls passa questo puntatore come parametro di chiamata al gestore AddDevice dell'adattatore. Il PDO è una struttura di sistema di tipo DEVICE_OBJECT.

[in] StartDevice

Puntatore alla funzione chiamata dal sistema operativo per avviare il dispositivo. Per altre informazioni, vedere la sezione Osservazioni seguente.

[in] MaxObjects

Specifica il numero massimo di sottodispositivi da registrare tramite chiamate a PcRegisterSubdevice. Questo conteggio imposta il limite massimo sul numero totale di oggetti miniport che il driver dell'adattatore può creare un'istanza.

[in] DeviceExtensionSize

Specifica le dimensioni dell'estensione del dispositivo. Usare zero per le dimensioni predefinite. Vedere la sezione Osservazioni seguente per le dimensioni delle estensioni fornite dall'utente.

Valore restituito

PcAddAdapterDevice restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo. In caso contrario, restituisce un codice di errore appropriato.

Commenti

Questa funzione esegue la maggior parte del lavoro che deve essere eseguito dal gestore AddDevice del driver dell'adattatore audio. PcAddAdapterDevice crea l'oggetto dispositivo, inizializza il contesto del dispositivo e collega l'oggetto dispositivo allo stack di dispositivi.

Un driver dell'adattatore chiama PcAddAdapterDevice quando riceve una chiamata al relativo gestore AddDevice . Il driver dell'adattatore installa in genere il gestore AddDevice chiamando PcInitializeAdapterDriver, anche se il driver può anche installare il gestore con altri mezzi. PcAddAdapterDevice crea l'oggetto dispositivo funzionale (FDO) per il PDO passato al gestore AddDevice .

DeviceExtensionSize è in genere zero. Alcuni driver di adattatore potrebbero dover riservare spazio aggiuntivo nell'estensione del dispositivo, nel qual caso devono specificare un DeviceExtensionSize maggiore di PORT_CLASS_DEVICE_EXTENSION_SIZE, ovvero le dimensioni predefinite. Qualsiasi valore maggiore di zero e minore di PORT_CLASS_DEVICE_EXTENSION_SIZE non è valido. I driver dell'adattatore sono liberi di usare qualsiasi parte dell'estensione del dispositivo dopo l'offset PORT_CLASS_DEVICE_EXTENSION_SIZE. Sono inoltre liberi di usare byte nell'intervallo di offset compreso tra 16 e 31 inclusi in un sistema con indirizzamento a 32 bit e byte nell'intervallo di offset da 32 a 63 in un sistema con indirizzamento a 64 bit. Se l'estensione viene considerata come una matrice di ULONG_PTR, gli elementi della matrice da quattro a sette sono disponibili per l'uso dal driver dell'adattatore.

Il parametro StartDevice punta a una funzione di tipo PCPFNSTARTDEVICE, che il file di intestazione portcls.h definisce come:

  NTSTATUS
    (*PCPFNSTARTDEVICE)(
      IN PDEVICE_OBJECT  DeviceObject,
      IN PIRP  Irp,
      IN PRESOURCELIST  ResourceList
      );

Per altre informazioni su PcAddAdapterDevice e le routine AddDevice del driver dell'adattatore e AddDevice , vedi Sequenza di avvio.

Il codice di esempio seguente mostra come un driver dell'adattatore può usare il parametro DeviceExtensionSize per aggiungere 64 byte di dati di estensione specifici del dispositivo alla fine del blocco di archiviazione allocato da PortCls per il contesto di dispositivo:

  #define MY_EXTENSION_SIZE  64
  NTSTATUS  ntstatus = PcAddAdapterDevice(DriverObject, PhysicalDeviceObject,
                                          MyStartDevice, MAX_MINIPORTS,
                                          MY_EXTENSION_SIZE + PORT_CLASS_DEVICE_EXTENSION_SIZE);

La chiamata pcAddAdapterDevice precedente è simile all'esempio in Sequenza di avvio, ad eccezione del fatto che l'ultimo parametro passato a PcAddAdapterDevice è diverso da zero.

Il driver dell'adattatore può quindi accedere ai dati di estensione specifici del dispositivo, come illustrato nel frammento di codice seguente:

  PVOID  pMyExtensionData = (PVOID)((PCHAR)FunctionalDeviceObject->DeviceExtension +
                                              PORT_CLASS_DEVICE_EXTENSION_SIZE);

Variable FunctionalDeviceObject è un puntatore al fdO dell'adattatore audio e pMyExtensionData è un puntatore temporaneo ai dati dell'estensione. Evitare di confondere il fdO con il PDO, che appartiene al driver del bus PCI. Il driver dell'adattatore non deve modificare i dati nel PDO perché ciò danneggia la memoria di proprietà del driver del bus PCI e può causare l'arresto anomalo del sistema.

Requisiti

Vedi anche

AddDevice

DEVICE_OBJECT

DRIVER_OBJECT

PcRegisterSubdevice