PcAddAdapterDevice 関数 (portcls.h)

[アーティクル]
02/07/2025

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

デバイス拡張機能のサイズを指定します。既定のサイズには 0 を使用します。ユーザー指定の拡張機能のサイズについては、次の解説セクションを参照してください。

戻り値

PcAddAdapterDevice は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。それ以外の場合は、適切なエラーコードが返されます。

備考

この関数は、オーディオアダプタードライバーの AddDevice ハンドラーが実行する必要があるほとんどの作業を実行します。 pcAddAdapterDevice デバイスオブジェクトを作成し、デバイスコンテキストを初期化し、デバイスオブジェクトをデバイススタックにアタッチします。

アダプタードライバーは、AddDevice ハンドラーへの呼び出しを受け取ったときに、PcAddAdapterDevice 呼び出します。アダプタードライバーは通常、pcInitializeAdapterDriver 呼び出すことによって、AddDevice ハンドラーをインストールしますが、ドライバーは他の方法でもハンドラーをインストールできます。 PcAddAdapterDevice は、AddDevice ハンドラーに渡された PDO の機能デバイスオブジェクト (FDO) を作成します。

DeviceExtensionSize は通常 0 です。一部のアダプタードライバーでは、デバイス拡張機能に追加の領域を予約する必要がある場合があります。その場合は、DeviceExtensionSize PORT_CLASS_DEVICE_EXTENSION_SIZEより大きい (既定のサイズ) を指定する必要があります。 0 より大きく、PORT_CLASS_DEVICE_EXTENSION_SIZE未満の値は無効です。アダプタードライバーは、オフセット PORT_CLASS_DEVICE_EXTENSION_SIZE後にデバイス拡張機能の任意の部分を自由に使用できます。また、オフセット範囲が 16 ~ 31 のバイト (32 ビットのアドレス指定があるシステムではバイトを含む) と、オフセット範囲が 32 ~ 63 のバイトは、64 ビットアドレス指定のシステムでも自由に使用できます。拡張機能がULONG_PTRの配列と見なされる場合、配列要素 4 ~ 7 はアダプタードライバーで使用できます。

StartDevice パラメーターは PCPFNSTARTDEVICE 型の関数を指します。この関数は、ヘッダーファイル portcls.h は次のように定義します。

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

PcAddAdapterDevice とアダプタードライバーのデバイススタートアップおよび AddDevice ルーチン 詳細については、「スタートアップシーケンス」を参照してください。

次のコード例は、アダプタードライバーが DeviceExtensionSize パラメーターを使用して、PortCls がデバイスコンテキストに割り当てるストレージブロックの末尾に 64 バイトのデバイス固有の拡張データを追加する方法を示しています。

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

上記の PcAddAdapterDevice 呼び出しは、スタートアップシーケンスの例に似ていますが、PcAddAdapterDevice に渡される最後のパラメーター 0 以外の値です。

アダプタードライバーは、次のコードフラグメントに示すように、デバイス固有の拡張データにアクセスできます。

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

Variable FunctionalDeviceObject はオーディオアダプターの FDO へのポインターであり、pMyExtensionData は拡張データへの一時的なポインターです。 FDO と PCI バスドライバーに属する PDO を混同しないようにします。アダプタードライバーは、PCI バスドライバーによって所有されているメモリが破損し、システムがクラッシュする可能性があるため、PDO 内のデータを変更しないでください。

必要条件

要件	価値
サポートされる最小クライアント	Windows 2000 以降で使用できます。
ターゲットプラットフォームの	万国
ヘッダー	portcls.h (Portcls.h を含む)
ライブラリ	Portcls.lib
IRQL	PASSIVE_LEVEL

次の方法で共有

PcAddAdapterDevice 関数 (portcls.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース