共用方式為

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

裝置 實體裝置物件的指標。 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 通常是零。 某些適配卡驅動程式可能需要在裝置擴充功能中保留額外的空間，在此情況下，它們應該指定 DeviceExtensionSize 大於 PORT_CLASS_DEVICE_EXTENSION_SIZE，這是預設大小。 任何大於零且小於PORT_CLASS_DEVICE_EXTENSION_SIZE的值都是非法的。 配接器驅動程式在位移PORT_CLASS_DEVICE_EXTENSION_SIZE之後，免費使用裝置擴充功能的任何部分。 在具有 64 位尋址的系統中，其位移範圍 16 到 31 內含的位元組，以及位移範圍 32 到 63 中的位元組，也可以自由使用位元組。 如果延伸模組被視為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 呼叫類似於 Startup Sequence中的範例，但 傳遞給 pcAddAdapterDevice 的最後一個參數為非零。

適配卡驅動程序接著可以存取裝置特定的擴充數據，如下列代碼段所示：

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

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

要求

要求 價值
最低支援的用戶端 從 Windows 2000 開始提供。
目標平臺 普遍
標頭 portcls.h （包括 Portcls.h）
連結庫 Portcls.lib
IRQL PASSIVE_LEVEL

另請參閱

AddDevice

DEVICE_OBJECT

DRIVER_OBJECT

PcRegisterSubdevice