共用方式為

PcAddAdapterDevice 函式 (portcls.h)

  • 發行項

PcAddAdapterDevice 函式會將適配卡裝置新增至 WDM 裝置堆疊。

語法

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

參數

[in] DriverObject

驅動程式物件的指標。 這個指標會當做參數傳遞至配接器的 AddDevice 處理程式。 驅動程式對像是類型 為 DRIVER_OBJECT 的系統結構。

[in] PhysicalDeviceObject

裝置 實體裝置物件的指標 (PDO) 。 PortCls 會將此指標當做呼叫參數傳遞至配接器的 AddDevice 處理程式。 PDO 是類型 為 DEVICE_OBJECT的系統結構。

[in] StartDevice

操作系統呼叫以啟動裝置之函式的指標。 如需詳細資訊，請參閱下列一節。

[in] MaxObjects

指定呼叫 PcRegisterSubdevice 所要註冊的子裝置數目上限。 此計數會將上限設定為適配卡驅動程式可以具現化的迷你埠對象總數。

[in] DeviceExtensionSize

指定裝置擴充功能大小。 針對預設大小使用零。 如需使用者提供的擴充功能大小，請參閱下列一節。

傳回值

如果呼叫成功，PcAddAdapterDevice 會傳回STATUS_SUCCESS。 否則，它會傳回適當的錯誤碼。

備註

此函式會執行音訊配接器驅動程式的 AddDevice 處理程式執行的大部分工作。 PcAddAdapterDevice 會建立裝置物件、初始化裝置內容，並將裝置物件附加至裝置堆疊。

配接器驅動程式在收到對 AddDevice 處理程式的呼叫時呼叫 PcAddAdapterDevice。 配接器驅動程式通常會藉由呼叫 PcInitializeAdapterDriver 來安裝 AddDevice 處理程式，不過驅動程式也可以透過其他方式安裝處理程式。 PcAddAdapterDevice 會針對傳遞給 AddDevice 處理程式的 PDO 建立 (FDO) 的功能裝置物件。

DeviceExtensionSize 通常是零。 某些適配卡驅動程式可能需要在裝置擴充功能中保留額外的空間，在此情況下，它們應該指定大於 PORT_CLASS_DEVICE_EXTENSION_SIZE 的 DeviceExtensionSize ，這是預設大小。 大於零且小於PORT_CLASS_DEVICE_EXTENSION_SIZE的任何值都是不合法的。 適配卡驅動程式在位移PORT_CLASS_DEVICE_EXTENSION_SIZE之後，可以使用裝置延伸模組的任何部分。 在具有 64 位尋址的系統內含 32 位位址和位移範圍 32 到 63 的系統中，它們也可以自由使用位移範圍 16 到 31 的位元組。 如果延伸模組視為ULONG_PTR數位，配接器驅動程式可以使用四到七的陣列元素。

StartDevice 參數指向 PCPFNSTARTDEVICE 類型的函式，其頭檔 portcls.h 會定義為：

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

如需 PcAddAdapterDevice 和配接器驅動程式的裝置啟動和 AddDevice 例程的詳細資訊，請參閱 啟動順序。

下列範例程式代碼示範配接器驅動程式如何使用 DeviceExtensionSize 參數，將 64 個字節的裝置特定擴充數據附加至 PortCls 為裝置內容配置的儲存區塊結尾：

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

上述 的 PcAddAdapterDevice 呼叫類似於 啟動序列中的範例，不同之處在於傳遞給 PcAddAdapterDevice 的最後一個參數是非零的。

配接器驅動程式接著可以存取裝置特定的延伸模組數據，如下列代碼段所示：

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

Variable FunctionDeviceObject 是音訊配接器的 FDO 指標， pMyExtensionData 是延伸模組數據的暫存指標。 避免將 FDO 與屬於 PCI 總線驅動程式的 PDO 混淆。 適配卡驅動程式不得修改 PDO 中的數據，因為這樣做會損毀 PCI 總線驅動程式所擁有的記憶體，而且可能會導致系統損毀。

規格需求

需求 值
最低支援的用戶端 從 Windows 2000 開始提供。
目標平台 Universal
標頭 portcls.h (包括 Portcls.h)
程式庫 Portcls.lib
IRQL PASSIVE_LEVEL

另請參閱

AddDevice

DEVICE_OBJECT

DRIVER_OBJECT

PcRegisterSubdevice