ISCPSecureQuery
COM公式ドキュメント
ISCPSecureQuery インターフェイスは、保護されたコンテンツの所有権を判断するために Windows Media Device Manager から照会されます。
メソッド 4
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
GetDataDemands メソッドは、指定されたコンテンツに対する権利と責任を判断するためにセキュア コンテンツ プロバイダーが必要とするデータを報告します。
| pfuFlags | DWORD* | out | セキュア コンテンツ プロバイダーが判断を行うために必要とするデータを示すフラグです。このパラメーターは、出力メッセージ認証コードに含まれます。次のフラグのうち少なくとも 1 つを使用する必要があります。
| ||||||||||||||
| pdwMinRightsData | DWORD* | out | このコンテンツの権利を判断するために必要な最小のデータ量を示す DWORD へのポインターです。このパラメーターは、出力メッセージ認証コードに含まれます。 | ||||||||||||||
| pdwMinExamineData | DWORD* | out | セキュア コンテンツ プロバイダーがそのコンテンツに対して責任を持つかどうかを判断するために必要な最小のデータ バイト数を格納する DWORD へのポインターです。このパラメーターは、出力メッセージ認証コードに含まれます。 | ||||||||||||||
| pdwMinDecideData | DWORD* | out | セキュア コンテンツ プロバイダーがコンテンツのダウンロードを許可するかどうかを判断するために必要な最小のデータ バイト数を格納する DWORD へのポインターです。このパラメーターは、出力メッセージ認証コードに含まれます。 | ||||||||||||||
| abMac | BYTE* | inout | このメソッドのパラメーター データに対するメッセージ認証コードを格納する 8 バイトの配列です。(WMDM_MAC_LENGTH は 8 として定義されています。) |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラー コードを返します。
| 戻り値 | 説明 |
|---|---|
| メッセージ認証コードが無効です。 | |
| パラメーターが無効であるか、NULL ポインターです。 | |
| 原因不明のエラーが発生しました。 |
解説(Remarks)
このメソッドは、ISCPSecureQuery の他のメソッドを呼び出す前に呼び出す必要があります。
このメソッドは、証明書の交換が正常に完了した後に呼び出されます。セキュア コンテンツ プロバイダーは、コンテンツに関する判断を行うための要件を示すフラグとデータを、各パラメーターに設定します。
セキュア コンテンツ プロバイダーが WMDM_SCP_RIGHTS_DATA フラグを設定した場合、Windows Media Device Manager は ISCPSecureQuery::GetRights を呼び出して、pdwMinRightsData で指定された量のデータを送信します。
セキュア コンテンツ プロバイダーが WMDM_SCP_EXAMINE_DATA フラグを設定した場合、Windows Media Device Manager は ISCPSecureQuery::ExamineData を呼び出して、pdwMinExamineData で指定された量のデータを送信します。
セキュア コンテンツ プロバイダーが WMDM_SCP_DECIDE_DATA フラグを設定した場合、Windows Media Device Manager は ISCPSecureQuery::MakeDecision を呼び出して、pdwMinDecideData で指定された量のデータを送信します。
examine 系のフラグが 1 つも設定されていない場合、Windows Media Device Manager はそれ以上の呼び出しを行いません。decide 系のフラグが設定されていない場合でも、Windows Media Device Manager は ISCPSecureQuery::ExamineData を呼び出します。
このメソッドが S_OK を返さない場合、Windows Media Device Manager はこのセキュア コンテンツ プロバイダーに対してそれ以上の呼び出しを行いません。
ExamineData メソッドは、Windows Media Device Manager から渡されたデータを調べて、コンテンツに対する権利と責任を判断します。
| fuFlags | DWORD | in | セキュア コンテンツ プロバイダーが判断を行うために提供されるデータを示すフラグです。次のフラグを指定できます。
| ||||
| pwszExtension | LPWSTR | inoptional | セキュア コンテンツ プロバイダーが GetDataDemands の呼び出しで拡張子を要求した場合に、調査対象となるファイル名拡張子へのポインターです。 | ||||
| pData | BYTE* | in | 調査対象となるファイルの先頭部分のデータへのポインターです。このパラメーターは入力メッセージ認証コードに含める必要があり、暗号化されている必要があります。 | ||||
| dwSize | DWORD | in | 調査対象データの長さ (バイト単位) を格納する DWORD です。このパラメーターは、入力メッセージ認証コードに含める必要があります。 | ||||
| abMac | BYTE* | inout | このメソッドのパラメーター データに対するメッセージ認証コードを格納する 8 バイトの配列です。(WMDM_MAC_LENGTH は 8 として定義されています。) |
戻り値
このメソッドは HRESULT を返します。指定できる値には、次の表に示す値などがありますが、これらに限定されません。
| 戻り値 | 説明 |
|---|---|
| メソッドは成功しました。セキュア コンテンツ プロバイダーは、このコンテンツに対して責任を持ちます。 | |
| このメソッドが正しい順序で呼び出されませんでした。先に GetDataDemands を呼び出す必要があります。 | |
| メッセージ認証コードが無効です。 | |
| Windows Media Device Manager は、別のデータ パケットを指定してこのメソッドを再度呼び出す必要があります。パケットのサイズは、GetDataDemands メソッドの pdwMinExamineData パラメーターによって決まります。 | |
| セキュア コンテンツ プロバイダーは、このコンテンツに対して責任を持ちません。セキュア コンテンツ プロバイダーとのやり取りを終了してください。 | |
| パラメーターが無効であるか、NULL ポインターです。 | |
| 原因不明のエラーが発生しました。 |
解説(Remarks)
このメソッドは、GetDataDemands メソッドの後に呼び出されます。セキュア コンテンツ プロバイダーは、このメソッドで渡された情報を使用して、そのコンテンツに対して責任を持つかどうかを判断します。fuFlags パラメーターを参照して、どのデータが調査用に提示されたかを判断します。pData パラメーターは、権利と責任に関するデータの先頭を指します。dwSize パラメーターには、権利と責任に関するデータの長さ (バイト単位) が格納されます。
WMDM_SCP_EXAMINE_DATA フラグが設定されている場合、pDataBuffer パラメーターには、セキュア コンテンツ プロバイダーが調査するための dwDataLength バイトのデータが格納されます。
このメソッドが S_OK または WMDM_E_MOREDATA を返さない場合、Windows Media Device Manager はこのセキュア コンテンツ プロバイダーに対してそれ以上の呼び出しを行いません。
MakeDecision メソッドは、コンテンツへのアクセスが許可されるかどうかを判断します。アクセスが許可される場合、このメソッドはコンテンツへのアクセスに使用されるインターフェイスを返します。
| fuFlags | DWORD | in | セキュア コンテンツ プロバイダーが判断を行うために提供されるデータを示すフラグです。このパラメーターは、入力メッセージ認証コードに含める必要があります。次のフラグを指定できます。
| ||||||||
| pData | BYTE* | in | 調査対象のデータを格納するデータ オブジェクトへのポインターです。このパラメーターは入力メッセージ認証コードに含める必要があり、暗号化されている必要があります。 | ||||||||
| dwSize | DWORD | in | 調査対象データの長さ (バイト単位) を格納する DWORD です。このパラメーターは、入力メッセージ認証コードに含める必要があります。 | ||||||||
| dwAppSec | DWORD | in | Windows Media Device Manager の現在のセキュリティ レベルを示す DWORD です。これは、アプリケーションと対象のサービス プロバイダーの現在のセキュリティ レベルのうち、小さい方の値です。このパラメーターは、入力メッセージ認証コードに含める必要があります。 | ||||||||
| pbSPSessionKey | BYTE* | in | pStgGlobals が指すサービス プロバイダーとの通信を保護するためのセッション キーを格納するバイト配列へのポインターです。このパラメーターは入力メッセージ認証コードに含める必要があり、暗号化されている必要があります。 | ||||||||
| dwSessionKeyLen | DWORD | in | pbSPSessionKey が指すバイト配列の長さです。このパラメーターは、入力メッセージ認証コードに含める必要があります。 | ||||||||
| pStorageGlobals | IMDSPStorageGlobals* | inoptional | ファイルの転送元または転送先となるメディアまたはデバイスのルート ストレージ上の IWMDMStorageGlobals インターフェイスへのポインターです。このパラメーターは、入力メッセージ認証コードに含める必要があります。 | ||||||||
| ppExchange | ISCPSecureExchange** | out | 交換インターフェイスを受け取る交換オブジェクトへのポインターです。 | ||||||||
| abMac | BYTE* | inout | このメソッドのパラメーター データに対するメッセージ認証コードを格納する 8 バイトの配列です。(WMDM_MAC_LENGTH は 8 として定義されています。) |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラー コードを返します。
| 戻り値 | 説明 |
|---|---|
| このメソッドが正しい順序で呼び出されませんでした。 | |
| メッセージ認証コードが無効です。 | |
| Windows Media Device Manager は、別のデータ パケットを指定してこのメソッドを再度呼び出す必要があります。パケットのサイズは、ISCPSecureQuery::GetDataDemands メソッドの pdwMinDecisionData パラメーターによって決まります。 | |
| 呼び出し元は、要求された転送を実行するために必要な権利を持っていません。 | |
| パラメーターが無効であるか、NULL ポインターです。 | |
| 原因不明のエラーが発生しました。 |
解説(Remarks)
このメソッドは ISCPSecureQuery::ExamineData メソッドの後に呼び出され、コンテンツへのアクセスを許可するかどうかの最終的な判断を行います。
GetRights メソッドは、現在のコンテンツに関する権利情報を取得します。権利はファイルごとに固有です。
| pData | BYTE* | in | GetDataDemands によって要求されたデータへのポインターです。このパラメーターは入力メッセージ認証コードに含める必要があり、暗号化されている必要があります。 |
| dwSize | DWORD | in | pData バッファー内のデータのバイト数です。このパラメーターは、入力メッセージ認証コードに含める必要があります。 |
| pbSPSessionKey | BYTE* | in | pStgGlobals が指すサービス プロバイダーとの通信を保護するためのセッション キーを格納するバイト配列へのポインターです。このパラメーターは入力メッセージ認証コードに含める必要があり、暗号化されている必要があります。 |
| dwSessionKeyLen | DWORD | in | pbSPSessionKey が指すバイト配列の長さです。このパラメーターは、入力メッセージ認証コードに含める必要があります。 |
| pStgGlobals | IMDSPStorageGlobals* | inoptional | ファイルの転送元または転送先となるメディアまたはデバイスのルート ストレージ上の IWMDMStorageGlobals インターフェイスへのポインターです。 |
| ppRights | WMDMRIGHTS** | out | このオブジェクトの権利情報を格納する WMDMRIGHTS 構造体の配列へのポインターです。この配列はこのメソッドによって割り当てられるため、CoTaskMemFree を使用して解放する必要があります。このパラメーターは、出力メッセージ認証コードに含まれます。 |
| pnRightsCount | DWORD* | out | ppRights 配列内の WMDMRIGHTS 構造体の数です。このパラメーターは、出力メッセージ認証コードに含まれます。 |
| abMac | BYTE* | inout | このメソッドのパラメーター データに対するメッセージ認証コードを格納する 8 バイトの配列です。(WMDM_MAC_LENGTH は 8 として定義されています。) |
戻り値
メソッドが成功した場合は S_OK を返します。失敗した場合は HRESULT エラー コードを返します。
| 戻り値 | 説明 |
|---|---|
| このメソッドが正しい順序で呼び出されませんでした。先に GetDataDemands、次に ExamineData を、この順序で呼び出す必要があります。 | |
| メッセージ認証コードが無効です。 | |
| 呼び出し元は、要求された操作を実行するために必要な権利を持っていません。 | |
| パラメーターが無効であるか、NULL ポインターです。 | |
| 原因不明のエラーが発生しました。 |
解説(Remarks)
このメソッドは、GetDataDemands、ExamineData の順に呼び出しが行われるまで呼び出してはなりません。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_ISCPSecureQuery "{1DCB3A0D-33ED-11D3-8470-00C04F79DBC0}" #usecom global ISCPSecureQuery IID_ISCPSecureQuery "{}" #comfunc global ISCPSecureQuery_GetDataDemands 3 var,var,var,var,var #comfunc global ISCPSecureQuery_ExamineData 4 int,wstr,var,int,var #comfunc global ISCPSecureQuery_MakeDecision 5 int,var,int,int,var,int,sptr,sptr,var #comfunc global ISCPSecureQuery_GetRights 6 var,int,var,int,sptr,var,var,var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ISCPSecureQuery "{1DCB3A0D-33ED-11D3-8470-00C04F79DBC0}" #usecom global ISCPSecureQuery IID_ISCPSecureQuery "{}" #comfunc global ISCPSecureQuery_GetDataDemands 3 sptr,sptr,sptr,sptr,sptr #comfunc global ISCPSecureQuery_ExamineData 4 int,wstr,sptr,int,sptr #comfunc global ISCPSecureQuery_MakeDecision 5 int,sptr,int,int,sptr,int,sptr,sptr,sptr #comfunc global ISCPSecureQuery_GetRights 6 sptr,int,sptr,int,sptr,sptr,sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。