ホーム › System.ComponentServices › IHolder

IHolder

COM

📘 Microsoft Learn (日本語) · English

IIDbf6a1850-2b45-11cf-be10-00aa00a2fa25継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

インストールされている Resource Dispenser のリソースを割り当てまたは解放します。

メソッド 8

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

vtbl 3 HRESULT AllocResource(UINT_PTR __MIDL__IHolder0000, UINT_PTR* __MIDL__IHolder0001)

在庫からリソースを割り当てます。

__MIDL__IHolder0000	UINT_PTR	in	割り当てるリソースの種類。
__MIDL__IHolder0001	UINT_PTR*	inout	割り当てられたリソースのハンドルが返される場所へのポインター。

戻り値

このメソッドは次の値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	ResTypId が NULL または空の文字列であるか、Resource Dispenser の IDispenserDriver::CreateResource メソッドが空または重複した RESID を生成しました。
E_FAIL	メソッドは失敗しました。pResId パラメーターは設定されていません。原因として、呼び出し元のトランザクションが中止されていることが考えられます。

解説(Remarks)

Dispenser Manager はリソースを見つけるために次の手順を実行します。

この RESTYPID の空きリソースのうち、呼び出し元の現在のトランザクションに既にエンリストされているものをプールから検索します。
この RESTYPID の空きでエンリストされていないリソースをプールから検索し、呼び出し元の現在のトランザクションにエンリストします。
Resource Dispenser の IDispenserDriver::CreateResource メソッドをコールバックしてリソースを作成し、エンリストします。

呼び出し元に現在のトランザクションがない場合、エンリストはスキップされます。また、Resource Dispenser がエンリストを拒否した場合(リソースがトランザクションに対応していないことを意味します)も、エンリストはスキップされます。

vtbl 4 HRESULT FreeResource(UINT_PTR __MIDL__IHolder0002)

リソースを在庫に戻します。

__MIDL__IHolder0002

UINT_PTR

解放するリソースのハンドル。

戻り値

このメソッドは次の値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	ResTypId が有効なリソースハンドルではありません。
E_FAIL	メソッドは失敗しました。リソースは解放されていません。

解説(Remarks)

元々 IHolder::AllocResource によって返されたリソースがプールに戻されます。これは IDispenserDriver::ResetResource を通じて Resource Dispenser に通知され、リソースがプールに戻される前に Resource Dispenser がリソースを準備する機会となります。

vtbl 5 HRESULT TrackResource(UINT_PTR __MIDL__IHolder0003)

リソースを追跡します。

__MIDL__IHolder0003

UINT_PTR

追跡するリソースのハンドル。Resource Dispenser は TrackResource を呼び出す前に、このリソースを既に作成しています。

戻り値

このメソッドは次の値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	ResId が有効なリソースハンドルではありません。
E_FAIL	メソッドは失敗しました。リソースは追跡されていません。原因として、呼び出し元のトランザクションが中止されていることが考えられます。

解説(Remarks)

一部のリソースは在庫として保持されず、常に必要に応じて生成されます。Holder は、オブジェクトの有効期間の終了時に残されたリソースを自動的に解放するためのメカニズムとしてのみ使用されます。

TrackResource は、IHolder::UntrackResource を呼び出して解放されるまで、または TrackResource を呼び出したオブジェクトが解放されるまでリソースを追跡すべきことを Holder に伝えます。オブジェクトが解放されると、Dispenser Manager はリソースを自動的に解放します。

TrackResource がトランザクションオブジェクトから呼び出された場合、Resource Dispenser の IDispenserDriver::EnlistResource メソッドをコールバックします。EnlistResource メソッドはリソースをトランザクションにエンリストできます。または、リソースがトランザクションに対応しておらずエンリストされていないことを示す S_FALSE を返すこともできます。

このリソースは、最終的に次の両方が満たされた後に破棄されます。

Resource Dispenser が IHolder::UntrackResource を呼び出す(多くの場合、コンポーネントの要求による)か、オブジェクトの有効期間が終了する。
リソースがエンリストされていたトランザクション(存在する場合)が完了する。

vtbl 6 HRESULT TrackResourceS(WORD* __MIDL__IHolder0004)

リソースを追跡します(文字列バージョン)。

__MIDL__IHolder0004

WORD*

inout

追跡するリソースのハンドル。Resource Dispenser は TrackResourceS を呼び出す前に、このリソースを既に作成しています。

戻り値

このメソッドは次の値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	SResId が有効なリソースハンドルではありません。
E_FAIL	メソッドは失敗しました。リソースは追跡されていません。原因として、呼び出し元のトランザクションが中止されていることが考えられます。

vtbl 7 HRESULT UntrackResource(UINT_PTR __MIDL__IHolder0005, BOOL __MIDL__IHolder0006)

リソースの追跡を停止します。

__MIDL__IHolder0005	UINT_PTR	in	追跡を停止するリソースのハンドル。
__MIDL__IHolder0006	BOOL	in	TRUE の場合、呼び出し元は IDispenserDriver::DestroyResource を呼び出してリソースを破棄することを要求します。FALSE の場合、呼び出し元がリソースを破棄します。

戻り値

このメソッドは次の値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	ResId が有効なリソースハンドルではありません。
E_FAIL	メソッドは失敗しました。

vtbl 8 HRESULT UntrackResourceS(WORD* __MIDL__IHolder0007, BOOL __MIDL__IHolder0008)

リソースの追跡を停止します(文字列バージョン)。

__MIDL__IHolder0007	WORD*	inout	追跡を停止するリソースのハンドル。
__MIDL__IHolder0008	BOOL	in	TRUE の場合、呼び出し元は IDispenserDriver::DestroyResource を呼び出してリソースを破棄することを要求します。FALSE の場合、呼び出し元がリソースを破棄します。

戻り値

このメソッドは次の値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	SResId が有効なリソースハンドルではありません。
E_FAIL	メソッドは失敗しました。

vtbl 9 HRESULT Close()

Holder を閉じます。

戻り値

このメソッドが成功した場合、S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

これは Resource Dispenser の Holder を閉じます。その後、Resource Dispenser はおそらく解放されます。

閉じる前に、残っている在庫はすべて Resource Dispenser の IDispenserDriver::DestroyResource メソッドをコールバックすることによって破棄されます。

次のシーケンスは、Resource Dispenser を閉じる方法を説明しています。

Resource Dispenser(IDispenserDriver を公開するオブジェクト)への参照を取得します。
実装内で IHolder::Close を呼び出す Resource Dispenser のメソッドを呼び出します。
IHolder::Close は、Resource Dispenser の IDispenserDriver::DestroyResource メソッドをコールバックして、残っている在庫をすべて破棄します。
IHolder::Close は Dispenser Manager を呼び出して、この Holder を Holder リストから削除します。(Holder が 1 つも残っていない場合、Dispenser Manager オブジェクトは自身を削除します。)
IHolder::Close は、Resource Dispenser の IDispenserDriver インターフェイスへの参照を解放します。これが手順 1 で参照が必要な理由です。そうしないと、後続の手順が完了する前に Resource Dispenser が早すぎるタイミングで自身を削除してしまいます。
IHolder::Close は Resource Dispenser に戻ります。
Resource Dispenser が IDispenserDriver::DestroyResource を呼び出します。ここで Holder は自身を削除します。
手順 2 で呼び出したメソッドがここで戻ります。
Resource Dispenser への最後の参照を解放します。これにより Resource Dispenser は自身を削除します。

IDispenserManager::RegisterDispenser メソッドはその pDispenserDriver オブジェクトに対して AddRef を呼び出しませんが、IHolder::Close は pDispenserDriver に対して Release を実行します。これにより、Resource Dispenser オブジェクトが早すぎるタイミングで破棄される可能性があります。この早すぎる破棄を防ぐため、IHolder::Close の呼び出し元は、手順 1 および 5 で説明したように Resource Dispenser オブジェクトへの参照を保持する必要があります。

vtbl 10 HRESULT RequestDestroyResource(UINT_PTR __MIDL__IHolder0009)

リソースを削除し、そのデストラクターを呼び出してメモリおよびその他の関連するシステムリソースを解放します。

__MIDL__IHolder0009

UINT_PTR

破棄するリソース。

戻り値

このメソッドは次の値を返すことがあります。

リターンコード	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	ResId が有効なリソースハンドルではありません。
E_FAIL	メソッドは失敗しました。リソースは破棄されていません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IHolder "{BF6A1850-2B45-11CF-BE10-00AA00A2FA25}"
#usecom global IHolder IID_IHolder "{}"
#comfunc global IHolder_AllocResource           3 sptr,var
#comfunc global IHolder_FreeResource            4 sptr
#comfunc global IHolder_TrackResource           5 sptr
#comfunc global IHolder_TrackResourceS          6 var
#comfunc global IHolder_UntrackResource         7 sptr,int
#comfunc global IHolder_UntrackResourceS        8 var,int
#comfunc global IHolder_Close                   9
#comfunc global IHolder_RequestDestroyResource  10 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IHolder "{BF6A1850-2B45-11CF-BE10-00AA00A2FA25}"
#usecom global IHolder IID_IHolder "{}"
#comfunc global IHolder_AllocResource           3 sptr,sptr
#comfunc global IHolder_FreeResource            4 sptr
#comfunc global IHolder_TrackResource           5 sptr
#comfunc global IHolder_TrackResourceS          6 sptr
#comfunc global IHolder_UntrackResource         7 sptr,int
#comfunc global IHolder_UntrackResourceS        8 sptr,int
#comfunc global IHolder_Close                   9
#comfunc global IHolder_RequestDestroyResource  10 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。