ホーム › Media.WindowsMediaFormat › IWMDRMReader

IWMDRMReader

COM

📘 Microsoft Learn (日本語) · English

IIDd2827540-3ee7-432c-b14c-dc17f085d3b3継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IWMDRMReader インターフェースは、DRM コンポーネントを構成し、DRM ライセンスの取得およびクライアントアプリケーションの個別化(インディビジュアライゼーション)を管理するためのメソッドを提供します。

メソッド 8

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT AcquireLicense(DWORD dwFlags)

AcquireLicense メソッドは、ライセンス取得プロセスを開始します。

dwFlags

DWORD

DWORD。該当するフラグを格納します。

フラグ	説明
0x1	メソッドがライセンスをサイレントに取得しようとすることを示します。
0x0	OnStatus コールバックが、ライセンス取得のために Web 上で使用する URL を返すことを示します。

戻り値

このメソッドは HRESULT を返します。指定できる値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
E_OUTOFMEMORY	タスクを完了するのに十分なメモリがありません。

解説(Remarks)

これは即座に制御を返す非同期呼び出しです。

サイレント取得の場合: ライセンス取得が完了すると、status パラメーターに WMT_ACQUIRE_LICENSE を設定した状態で IWMStatusCallback::OnStatus が呼び出されます。ライセンス取得が成功した場合、pvalue パラメーターには WM_GET_LICENSE_DATA 構造体を指すバイトポインターが設定されます。ライセンス取得中にエラーが発生した場合は、OnStatus 呼び出しの HRESULT に該当するエラーコードが格納されます。

非サイレント取得の場合: OnStatus はただちに制御を返し、WMT_ACQUIRE_LICENSE イベントをアプリケーションに送信します。その場合、WM_GET_LICENSE_DATA 構造体には、ライセンス取得に使用する URL に関する情報が格納されます。

vtbl 4 HRESULT CancelLicenseAcquisition()

CancelLicenseAcquisition メソッドは、現在実行中の AcquireLicense メソッド呼び出しをキャンセルします。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

vtbl 5 HRESULT Individualize(DWORD dwFlags)

Individualize メソッドは、クライアントの DRM システムコンポーネントを更新することで、クライアントを個別化(インディビジュアライズ)します。

dwFlags

DWORD

DWORD。該当するフラグを格納します。

フラグ	説明
0x0	クライアントを再度個別化できることを示します。
0x1	クライアントを再度個別化しないことを示します。

戻り値

このメソッドは HRESULT を返します。指定できる値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	null または無効な引数が渡されました。

解説(Remarks)

これは即座に制御を返す非同期呼び出しです。この処理を中止するには、CancelIndividualization を呼び出します。

重要この操作はユーザーのシステムを変更するため、この操作が何を行うのかを説明するメッセージを表示し、個別化を実行するかどうかをユーザーが選択できるようにする必要があります。詳細と推奨されるメッセージ文言については、DRM Individualization を参照してください。

個別化とは、Microsoft Individualization Service から個別化されたコンポーネントをダウンロードしてインストールすることにより、DRM クライアントを一意にするプロセスです。この一連の処理は、アプリケーションが Individualize メソッドを呼び出した後に自動的に実行されます。アプリケーションには、個別化プロセスの進行状況が、繰り返し送信される WMT_INDIVIDUALIZE イベントを通じて通知されます。各イベントには、アプリケーションの IWMStatusCallback::OnStatus コールバックメソッドに送信される WM_INDIVIDUALIZE_STATUS 構造体が関連付けられています。

個別化プロセスを開始するタイミングは 2 つあります。1 つ目はコンテンツがそれを必要とする場合、2 つ目はプレーヤーがセットアップの一環としてクライアントを個別化する場合です。後者の場合、クライアントを再度個別化する理由はありません。

vtbl 6 HRESULT CancelIndividualization()

CancelIndividualization メソッドは、現在実行中の Individualize メソッド呼び出しをキャンセルします。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

vtbl 7 HRESULT MonitorLicenseAcquisition()

MonitorLicenseAcquisition メソッドは、非サイレントライセンス取得において、ライセンスが正常に取得されたことをアプリケーションに通知します。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは、DRM バージョン 7 のコンテンツに対して非サイレントライセンス取得を開始したときには常に使用する必要があります。これは即座に制御を返す非同期呼び出しです。このメソッドは、要求したライセンスがいつ受信されたかを判断するために、ローカルのライセンスストアを定期的にチェックするスレッドを作成します。この処理をキャンセルするには、CancelMonitorLicenseAcquisition を呼び出します。

ライセンス取得が(成功したかどうかにかかわらず)完了すると、アプリケーションの IWMStatusCallback::OnStatus メソッドに送信される WMT_LICENSE_ACQUIRE イベントを通じてアプリケーションに通知されます。

vtbl 8 HRESULT CancelMonitorLicenseAcquisition()

CancelMonitorLicenseAcquisition メソッドは、現在実行中の MonitorLicenseAcquisition メソッド呼び出しをキャンセルします。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは、直近に要求したライセンスがいつ取得されたかを判断するためにライセンスストアを定期的にチェックしているスレッドを終了します。

vtbl 9 HRESULT SetDRMProperty(LPWSTR pwstrName, WMT_ATTR_DATATYPE dwType, BYTE* pValue, WORD cbLength)

リーダーオブジェクトの SetDRMProperty メソッドは、DRM_Rights プロパティなどの DRM プロパティを設定するために使用します。

pwstrName	LPWSTR	in	設定するプロパティの名前を指定します。
dwType	WMT_ATTR_DATATYPE	in	WMT_ATTR_DATATYPE 列挙型のメンバーの 1 つ。このメソッドでサポートされる値は WMT_TYPE_STRING のみです。
pValue	BYTE*	in	属性値を格納するバイト配列へのポインター。
cbLength	WORD	in	pValue のサイズ(バイト単位)。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

vtbl 10 HRESULT GetDRMProperty(LPWSTR pwstrName, WMT_ATTR_DATATYPE* pdwType, BYTE* pValue, WORD* pcbLength)

GetDRMProperty メソッドは、DRM 固有のファイル属性および実行時プロパティを取得します。

pwstrName	LPWSTR	in	取得するプロパティまたはファイル属性を指定します。
pdwType	WMT_ATTR_DATATYPE*	out	返される値のデータ型を受け取るポインター。
pValue	BYTE*	out	pwstrName で要求した値へのポインター。
pcbLength	WORD*	inout	pValue のサイズ(バイト単位)。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは、現在のファイルの DRM ヘッダー属性と DRM ライセンス情報の両方を取得するために使用できます。DRM 関連の定数は、drmexternals.idl および wmsdkidl.idl で定義されています。

「ライセンス状態(license state)」定数を指定した場合、返されるデータは、特定の権利に対するライセンスの条件を完全に記述する WM_LICENSE_STATE_DATA 構造体へのポインターです。サポートされるライセンス状態定数は、次の表のとおりです。

定数	リテラル文字列値	説明
g_wszWMDRM_LicenseState_CollaborativePlay	"LicenseStateData.CollaborativePlay"	共同的なピアツーピアネットワークシナリオの一環としてファイルを再生する際のライセンス制限。
g_wszWMDRM_LicenseState_Copy	"LicenseStateData.Copy"	ファイルをデバイスにコピーする際のライセンス制限。
g_wszWMDRM_LicenseState_CopyToCD	"LicenseStateData.Print.redbook"	ファイルを CD にコピーする際のライセンス制限。DRM バージョン 10 のライセンスでは、すべてのコピー操作に g_wszWMDRM_LicenseState_Copy を使用してください。
g_wszWMDRM_LicenseState_CopyToNonSDMIDevice	"LicenseStateData.Transfer.NONSDMI"	ファイルを非 SDMI デバイスにコピーする際のライセンス制限。DRM バージョン 10 のライセンスでは、すべてのコピー操作に g_wszWMDRM_LicenseState_Copy を使用してください。
g_wszWMDRM_LicenseState_CopyToSDMIDevice	"LicenseStateData.Transfer.SDMI"	ファイルを SDMI デバイスにコピーする際のライセンス制限。DRM バージョン 10 のライセンスでは、すべてのコピー操作に g_wszWMDRM_LicenseState_Copy を使用してください。
g_wszWMDRM_LicenseState_Playback	"LicenseStateData.Play"	ファイルを再生する際のライセンス制限。
g_wszWMDRM_LicenseState_PlaylistBurn	"LicenseStateData.PlaylistBurn"	プレイリストの一環としてファイルを Red Book オーディオ CD にコピーする際のライセンス制限。

「許可される操作(action allowed)」定数を指定した場合、返されるデータは、指定した操作が現時点で許可されているかどうかを示すブール値です。サポートされる定数は次のとおりです。

定数	リテラル文字列値	説明
g_wszWMDRM_ActionAllowed_Backup	"ActionAllowed.Backup"	ファイルを今すぐバックアップする権利。
g_wszWMDRM_ActionAllowed_CollaborativePlay	"ActionAllowed.CollaborativePlay"	共同的なピアツーピアネットワークシナリオの一環としてファイルを再生する権利。
g_wszWMDRM_ActionAllowed_Copy	"ActionAllowed.Copy"	ファイルをデバイスにコピーする権利。
g_wszWMDRM_ActionAllowed_CopyToCD	"ActionAllowed.Print.redbook"	ファイルを CD にコピーする権利。DRM バージョン 10 のライセンスでは、すべてのコピー操作について g_wszWMDRM_ActionAllowed_Copy を確認してください。
g_wszWMDRM_ActionAllowed_CopyToSDMIDevice	"ActionAllowed.Transfer.SDMI"	ファイルを SDMI デバイスにコピーする権利。DRM バージョン 10 のライセンスでは、すべてのコピー操作について g_wszWMDRM_ActionAllowed_Copy を確認してください。
g_wszWMDRM_ActionAllowed_CopyToNonSDMIDevice	"ActionAllowed.Transfer.NONSDMI"	ファイルを非 SDMI デバイスにコピーする権利。DRM バージョン 10 のライセンスでは、すべてのコピー操作について g_wszWMDRM_ActionAllowed_Copy を確認してください。
g_wszWMDRM_ActionAllowed_Playback	"ActionAllowed.Play"	ファイルを再生する権利。
g_wszWMDRM_ActionAllowed_PlaylistBurn	"ActionAllowed.PlaylistBurn"	プレイリストの一環としてファイルを Red Book オーディオ CD にコピーする権利。

「DRM ヘッダー(DRM Header)」定数を指定した場合、返される値は指定したプロパティの文字列リテラルです。サポートされる DRM ヘッダー定数は次のとおりです。

定数	リテラル文字列値	説明
g_wszWMDRM_DRMHeader_KeyID	"DRMHeader.KID"	DRM キー値。
g_wszWMDRM_DRMHeader_LicenseAcqURL	"DRMHeader.LAINFO"	DRM ライセンス取得 URL。
g_wszWMDRM_DRMHeader_ContentID	"DRMHeader.CID"	DRM コンテンツ ID。
g_wszWMDRM_DRMHeader_IndividualizedVersion	"DRMHeader.SECURITYVERSION"	個別化バージョン。
g_wszWMDRM_DRMHeader_ContentDistributor	"DRMHeader.ContentDistributor"	コンテンツ配布元。
g_wszWMDRM_DRMHeader_SubscriptionContentID	"DRMHeader.SubscriptionContentID"	サブスクリプションコンテンツ ID。

新しいファイルに対してこのメソッドを呼び出す前に、そのファイルが DRM で保護されていることを確認するために、必ずヘルパー関数 WMIsContentProtected を呼び出してください。保護されていないコンテンツに対してこのメソッドを呼び出した場合でも成功することがあるため、これを行うことが重要です。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IWMDRMReader "{D2827540-3EE7-432C-B14C-DC17F085D3B3}"
#usecom global IWMDRMReader IID_IWMDRMReader "{}"
#comfunc global IWMDRMReader_AcquireLicense                   3 int
#comfunc global IWMDRMReader_CancelLicenseAcquisition         4
#comfunc global IWMDRMReader_Individualize                    5 int
#comfunc global IWMDRMReader_CancelIndividualization          6
#comfunc global IWMDRMReader_MonitorLicenseAcquisition        7
#comfunc global IWMDRMReader_CancelMonitorLicenseAcquisition  8
#comfunc global IWMDRMReader_SetDRMProperty                   9 wstr,int,var,int
#comfunc global IWMDRMReader_GetDRMProperty                   10 wstr,var,var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IWMDRMReader "{D2827540-3EE7-432C-B14C-DC17F085D3B3}"
#usecom global IWMDRMReader IID_IWMDRMReader "{}"
#comfunc global IWMDRMReader_AcquireLicense                   3 int
#comfunc global IWMDRMReader_CancelLicenseAcquisition         4
#comfunc global IWMDRMReader_Individualize                    5 int
#comfunc global IWMDRMReader_CancelIndividualization          6
#comfunc global IWMDRMReader_MonitorLicenseAcquisition        7
#comfunc global IWMDRMReader_CancelMonitorLicenseAcquisition  8
#comfunc global IWMDRMReader_SetDRMProperty                   9 wstr,int,sptr,int
#comfunc global IWMDRMReader_GetDRMProperty                   10 wstr,sptr,sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。