DrmForwardContentToDeviceObject 関数 (drmk.h)

[アーティクル]
08/07/2023

関数は DrmForwardContentToDeviceObject 、呼び出し元が保護されたコンテンツを転送するデバイスを表すデバイスオブジェクトを受け取ります。この関数は、デバイスを認証し、システムが保護されたコンテンツに割り当てたコンテンツ ID と DRM 権限を送信します。

構文

NTSTATUS DrmForwardContentToDeviceObject(
  [in]           ULONG        ContentId,
  [in, optional] PVOID        Reserved,
  [in]           PCDRMFORWARD DrmForward
);

パラメーター

[in] ContentId

DRM コンテンツ ID を指定します。このパラメーターは、保護された KS オーディオストリームを識別します。

[in, optional] Reserved

将来利用するために予約されています。 NULL に設定します。

[in] DrmForward

ターゲットデバイスを識別するデバイスオブジェクトとファイルオブジェクト、およびそのデバイス上の KS オーディオピンをそれぞれ指定する DRMFORWARD 構造体へのポインター。構造体には、 KSPROPERTY_DRMAUDIOSTREAM_CONTENTIDset-property 要求がデバイスに渡すコンテキスト値も含まれます。

戻り値

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

注釈

保護されたコンテンツがデータパスを通過できるようにする前に、システムはデータパスがセキュリティで保護されていることを確認します。これを行うために、システムは、データパスの上流端からダウンストリームに移動するデータパス内の各モジュールを認証します。各モジュールが認証されると、そのモジュールはデータパス内の次のモジュールに関するシステム情報を提供して、認証することもできます。正常に認証するには、モジュールのバイナリファイルに DRM 準拠として署名する必要があります。

データパス内の 2 つの隣接するモジュールは、いくつかの方法のいずれかで相互に通信できます。アップストリームモジュールが IoCallDriver を介してダウンストリームモジュールを呼び出す場合、ダウンストリームモジュールは WDM ドライバーの一部です。この場合、アップストリームモジュールは関数を DrmForwardContentToDeviceObject 呼び出して、ダウンストリームモジュールを表すデバイスオブジェクトをシステムに提供します。 (2 つのモジュールがダウンストリームモジュールの COM インターフェイスまたはコンテンツハンドラーを介して通信する場合、アップストリームモジュールは代わりに DrmForwardContentToInterface または DrmAddContentHandlers を呼び出します)。

呼び出し元は、DrmForward パラメーターが指す DRMFORWARD 構造体の DeviceObject、FileObject、および Context メンバーを入力します。 DrmForwardContentToDeviceObject では、次の値が使用されます。

DeviceObject は、ドライバー (ダウンストリームモジュール) を表すデバイスオブジェクトを指定します。 DrmForwardContentToDeviceObject では、デバイスオブジェクトを使用してドライバーを認証します。成功した場合、この関数は、set-property 要求をデバイスの KS ピンに送信することで、デバイスの KSPROPERTY_DRMAUDIOSTREAM_CONTENTID プロパティを設定します。
FileObject は、プロパティ要求を送信する DrmForwardContentToDeviceObject KS ピンを指定します。
Context は、呼び出し元がプロパティ要求を介してドライバーに渡すコンテキスト値を指定します。 DrmForwardContentToDeviceObject は、コンテキスト値を要求のプロパティ記述子にコピーします。通常、コンテキスト値は、呼び出し元とドライバーの両方が理解するカスタム形式のデータを含むバッファーへのポインターです。慣例により、ダウンストリームモジュールが KS フィルターの場合、 Context メンバーは、関数がプロパティ要求を送信する KS ピンを指定する DrmForwardContentToDeviceObject ファイルオブジェクトを指します。言い換えると、 Context メンバーは FileObject メンバーと同じファイルオブジェクトを指します。 USB オーディオドライバーでは、 Context パラメーターをUSBD_PIPE_HANDLE値に設定する必要があります。

プロパティ要求には、パラメーター ContentId からの DRM コンテンツ ID と、そのコンテンツ ID に属する DRM コンテンツ権限も含まれます。 DrmForwardContentToDeviceObject は、これらの値を要求のプロパティ値にコピーします。 DrmForwardContentToDeviceObject は、を返した後にデバイスオブジェクトをこれ以上使用しません。

DrmForwardContentToDeviceObjectは、PcForwardContentToDeviceObject および IDrmPort2::ForwardContentToDeviceObject と同じ関数を実行します。詳細については、「 DRM 関数とインターフェイス」を参照してください。

KSPROPERTY_DRMAUDIOSTREAM_CONTENTID プロパティは、DRM コンテンツ ID と DRM コンテンツ権限を KS オーディオピンに割り当てます。

使用状況の概要テーブル

取得	オン	移行先	プロパティ記述子の型	プロパティ値の型
いいえ	Yes	Pin	KSP_DRMAUDIOSTREAM_CONTENTID	KSDRMAUDIOSTREAM_CONTENTID

プロパティ値 (操作データ) は、ストリームの DRM コンテンツ ID と DRM コンテンツ権限を指定するKSDRMAUDIOSTREAM_CONTENTID構造です。

戻り値

KSPROPERTY_DRMAUDIOSTREAM_CONTENTID プロパティ要求は、次の表に示すように、KS フィルターで指定された DRM コンテンツ権限を適用できるかどうかを示す状態コードを返します。

状態コード	意味
STATUS_SUCCESS	KS オーディオフィルターは、指定された DRM コンテンツ権限を適用します。
STATUS_NOT_IMPLEMENTED	KS フィルターは、指定された DRM コンテンツ権限を適用できません。

DrmForwardContentToDeviceObject 関数は、このプロパティを使用して、プロパティ要求のターゲットである KS ピンを入力するオーディオストリームの DRM コンテンツ ID とコンテンツ権限を設定します。

KS オーディオフィルターは、このプロパティ要求を同期的に処理します。要求がSTATUS_SUCCESS返された場合、ターゲット KS オーディオピンのすべてのダウンストリーム KS オーディオノード ( オーディオトポロジノードを参照) も、指定された DRM コンテンツ ID と DRM コンテンツ権限で正常に構成されました。 (ダウンストリームノードは、オーディオピンを流れるオーディオコンテンツの直接シンクまたは間接シンクであることに注意してください)。

DRM システムは、KS オーディオピンを表すファイルオブジェクトの有効期間中にいつでもこのプロパティを設定できます。要求が成功しない場合、以前に設定した DRM コンテンツ ID と DRM コンテンツ権限は、KS オーディオストリームに対して引き続き有効です。

KSPROPERTY_DRMAUDIOSTREAM_CONTENTID プロパティのハンドラーは、プロパティ要求 IRP がカーネルモードで発生していることを確認する必要があります (つまり、IRP の RequestorMode フィールドが KernelMode と等しいことを確認します)。 IRP がユーザーモードで発生した場合、ハンドラーは IRP に失敗し、状態コードINVALID_DEVICE_REQUESTを返す必要があります。

DrmForwardContentToDeviceObject は、 DRMK システムドライバーのエントリポイント Drmk.sys。 DRMK は、IRQL PASSIVE_LEVELで KSPROPERTY_DRMAUDIOSTREAM_CONTENTID プロパティのIOCTL_KS_PROPERTY要求を送信します。