IResourceManager

IResourceManager インターフェイスは、システムリソースの競合を解決します。このインターフェイスはフィルターグラフマネージャーによって公開されます。

Register メソッドは、名前付きリソースを 1 つリソースマネージャーに登録します。

実装に依存する HRESULT 値を返します。HRESULT は次の標準的な定数のいずれか、またはここに記載されていない他の値になります。

戻り値コード	説明
E_FAIL	失敗。
E_POINTER	NULL ポインター引数。
E_INVALIDARG	無効な引数。
E_NOTIMPL	メソッドはサポートされていません。
S_OK または NOERROR	成功。

このメソッドは、複数のリソースを含みうる名前付きリソースを登録し、そのリソースを要求する際に使用するトークンを返します。リソースが既に登録済みであってもエラーにはなりません。cResource パラメーターの数が既に登録されている数より少ない場合、リソースは新しい数まで解放されます。リソースの登録を解除するには、cResource に 0 を渡します。

RegisterGroup メソッドは、名前付きリソースグループをリソースマネージャーに登録します。

実装に依存する HRESULT 値を返します。HRESULT は次の標準的な定数のいずれか、またはここに記載されていない他の値になります。

戻り値コード	説明
E_FAIL	失敗。
E_POINTER	NULL ポインター引数。
E_INVALIDARG	無効な引数。
E_NOTIMPL	メソッドはサポートされていません。
S_OK または NOERROR	成功。

RequestResource メソッドは、登録済みの指定リソースの使用を要求します。

HRESULT 値を返します。要求したリソースが返される場合は S_OK を、リソースが利用できない場合は S_FALSE を返します。後者の場合、リソースが利用可能になったときにリソースマネージャーが要求元のオブジェクトをコールバックします。それ以外の戻り値はエラーです。

リソースに対する要求が複数存在する場合、リソースマネージャーは各要求とともに渡されたフォーカスオブジェクトを、直近の IResourceManager::SetFocus メソッドで渡されたフォーカスオブジェクトと比較して優先順位を決定します。

要求は次の優先順位で処理されます。

1. 直近の SetFocus メソッドとまったく同じフォーカスオブジェクトで行われた要求。
2. フォーカスオブジェクトが共通のソースフィルターを共有し、そのフォーカスオブジェクトが共通のフィルターグラフを共有する要求。
3. フォーカスと同じプロセス内の要求。

この優先順位を確認する際、リソースマネージャーはフォーカスオブジェクトに対して IID_IFilter で QueryInterface を実行します。見つかった場合、リソースマネージャーは IBaseFilter のメソッドを使用してフィルターグラフを調べ、現在のフォーカスオブジェクトと共通のソースフィルターを探します。

フィルターは、pFocusObject パラメーターにフィルターの IUnknown インターフェイスを渡す必要があります。フィルターグラフマネージャーはフィルターをフィルターグラフと突き合わせ、フォーカスオブジェクトを確認する際に共通のソースフィルターまでフィルターをたどろうとします。

フォーカスオブジェクトは、要求の存続期間全体にわたって有効でなければなりません。すなわち、IResourceManager::CancelRequest メソッドが呼び出されるか、bStillWant パラメーターを FALSE に設定して IResourceManager::NotifyRelease メソッドが呼び出されるまで有効である必要があります。

NotifyAcquire メソッドは、リソースを取得しようとする試みが完了したことをリソースマネージャーに通知します。

実装に依存する HRESULT 値を返します。HRESULT は次の標準的な定数のいずれか、またはここに記載されていない他の値になります。

戻り値コード	説明
E_FAIL	失敗。
E_POINTER	NULL ポインター引数。
E_INVALIDARG	無効な引数。
E_NOTIMPL	メソッドはサポートされていません。
S_OK または NOERROR	成功。

IResourceConsumer::AcquireResource メソッドが S_FALSE 値を返し、取得が非同期(すなわちコールバック機構によって処理される)であることを示した後に、このメソッドを使用します。hr パラメーターが S_OK の場合、リソースマネージャーはリソースが現在呼び出し元によって保持されているものとみなします。hr パラメーターが S_OK 以外の場合、リソースマネージャーはリソースの取得の試みが失敗したものとみなし、リソースを他の要求に再割り当てします。

NotifyRelease メソッドは、IResourceConsumer がリソースを解放したことをリソースマネージャーに通知します。

実装に依存する HRESULT 値を返します。HRESULT は次の標準的な定数のいずれか、またはここに記載されていない他の値になります。

戻り値コード	説明
E_FAIL	失敗。
E_POINTER	NULL ポインター引数。
E_INVALIDARG	無効な引数。
E_NOTIMPL	メソッドはサポートされていません。
S_OK または NOERROR	成功。

このメソッドは、IResourceConsumer::ReleaseResource メソッドへの応答として、またはリソースの使用を終えたときに使用します。

CancelRequest メソッドは、リソースの要求をキャンセルします。

実装に依存する HRESULT 値を返します。HRESULT は次の標準的な定数のいずれか、またはここに記載されていない他の値になります。

戻り値コード	説明
E_FAIL	失敗。
E_POINTER	NULL ポインター引数。
E_INVALIDARG	無効な引数。
E_NOTIMPL	メソッドはサポートされていません。
S_OK または NOERROR	成功。

このメソッドは、リソースを要求した IResourceConsumer オブジェクトがそのリソースを受け取っておらず、かつ不要になった場合に呼び出す必要があります。既にリソースを受け取っている場合は、IResourceManager::NotifyRelease メソッドを使用してください。

SetFocus メソッドは、指定したオブジェクトにユーザーのフォーカスが与えられたことをリソースマネージャーに通知します。

実装に依存する HRESULT 値を返します。HRESULT は次の標準的な定数のいずれか、またはここに記載されていない他の値になります。

戻り値コード	説明
E_FAIL	失敗。
E_POINTER	NULL ポインター引数。
E_INVALIDARG	無効な引数。
E_NOTIMPL	メソッドはサポートされていません。
S_OK または NOERROR	成功。

DirectShow では、ユーザーのフォーカスが与えられるオブジェクトは通常、そのウィンドウがフォーカスを受け取ったビデオレンダラーです。リソースマネージャーは、リソースの要求に対して次の順序で優先順位を与えます。

1. pFocusObject パラメーターで指定されたフォーカスオブジェクトで行われた要求。
2. フォーカスオブジェクトが共通のソースフィルターを共有する要求。
3. フォーカスオブジェクトが共通のフィルターグラフを共有する要求。
4. フォーカスと同じプロセス内の要求。

フォーカスが設定された後、リソースマネージャーは ReleaseFocus が呼び出されるまでフォーカスオブジェクトを保持しなければなりません。すなわち、このメソッドを呼び出した後は、その間に別のオブジェクトによって SetFocus が呼び出されることを保証できる場合を除き、フォーカスオブジェクトの IUnknown インターフェイスが無効になる前に ReleaseFocus を使用する必要があります。フォーカスオブジェクトに対する参照カウントは保持されません。

リソースマネージャーは、このポインターが置き換えられるかキャンセルされるまで保持し、リソースの競合を解決するために使用します。少なくとも IBaseFilter インターフェイスに対して QueryInterface を使用し、見つかった場合はそのインターフェイスのメソッドを使用します。オーディオレンダラーが 2 つある場合にどちらを使用するかを決定するために(フォーカスオブジェクトと共通のソースフィルターを持つ方を選択します)、また 2 つのオブジェクトが同じフィルターグラフ内にあるかどうかを判断するために、IBaseFilter のメソッドを呼び出します。

ReleaseFocus メソッドは、現在のフォーカスオブジェクトがこのメソッドで指定されたものと一致する場合に、リソースマネージャー内のフォーカスオブジェクトを NULL に設定します。

実装に依存する HRESULT 値を返します。HRESULT は次の標準的な定数のいずれか、またはここに記載されていない他の値になります。

戻り値コード	説明
E_FAIL	失敗。
E_POINTER	NULL ポインター引数。
E_INVALIDARG	無効な引数。
E_NOTIMPL	メソッドはサポートされていません。
S_OK または NOERROR	成功。

フォーカスオブジェクトが破棄されようとしているときに、フォーカスがまだ参照されていない状態にするためにこのメソッドを使用します。

#define global IID_IResourceManager "{56A868AC-0AD4-11CE-B03A-0020AF0BA770}"
#usecom global IResourceManager IID_IResourceManager "{}"
#comfunc global IResourceManager_Register         3 wstr,int,var
#comfunc global IResourceManager_RegisterGroup    4 wstr,int,var,var
#comfunc global IResourceManager_RequestResource  5 int,sptr,sptr
#comfunc global IResourceManager_NotifyAcquire    6 int,sptr,int
#comfunc global IResourceManager_NotifyRelease    7 int,sptr,int
#comfunc global IResourceManager_CancelRequest    8 int,sptr
#comfunc global IResourceManager_SetFocus         9 sptr
#comfunc global IResourceManager_ReleaseFocus     10 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。