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

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

戻り値

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

注釈

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

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

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

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

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

PcAddAdapterDevice とアダプター ドライバーの device-startup ルーチンと 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 は拡張データへの一時的なポインターです。 PCI バス ドライバーに属する PDO と FDO を混同しないようにします。 アダプター ドライバーは、PCI バス ドライバーによって所有されているメモリが破損し、システムがクラッシュする可能性があるため、PDO 内のデータを変更することはできません。

要件

要件 値
サポートされている最小のクライアント Windows 2000 以降で使用できます。
対象プラットフォーム ユニバーサル
Header portcls.h (Portcls.h を含む)
Library Portcls.lib
IRQL PASSIVE_LEVEL

こちらもご覧ください

AddDevice

DEVICE_OBJECT

DRIVER_OBJECT

PcRegisterSubdevice