IFunctionInstance
COM公式ドキュメント
関数インスタンスは、いずれかの IFunctionDiscovery メソッドを呼び出した結果として作成されます。クライアントプログラムがこれらのオブジェクトを自分で作成することはありません。
メソッド 4
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
関数インスタンスの識別子文字列を取得します。
| ppszCoMemIdentity | WORD** | out | 関数インスタンスの識別子文字列。この文字列のサイズに上限はありません。 この文字列は Function Discovery によって生成される合成文字列で、プロバイダーインスタンス識別子文字列を部分文字列として含みます。プロバイダー識別子の詳細については、IFunctionInstance::GetProviderInstanceID を参照してください。 組み込みプロバイダーによって返される関数インスタンスの場合、この識別子は、リソースが切断されて再接続された場合でも、システム上のリソースを一意に識別することが保証されます。カスタムプロバイダーによって返される関数インスタンスの場合、プロバイダーが一意のプロバイダー識別子を持っていれば、関数インスタンス識別子は一意になります。 この識別子はプログラムによって操作したり生成したりしないでください。この文字列は関数インスタンスの取得および比較の目的にのみ使用してください。 このバッファーは CoTaskMemFree を使用して必ず解放してください。 |
戻り値
戻り値には次のものが含まれますが、これらに限定されません。
| 戻り値コード | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| ppszCoMemID の値が無効です。 | |
| この操作の実行に必要なメモリをメソッドが割り当てられません。 |
プロバイダーインスタンスの識別子文字列を取得します。
| ppszCoMemProviderInstanceIdentity | WORD** | out | プロバイダーインスタンスの識別子文字列。ルートデバイスの場合、この文字列は PKEY_PNPX_GlobalIdentity と同じ値になります。 このバッファーは CoTaskMemFree を使用して必ず解放してください。 |
戻り値
戻り値には次のものが含まれますが、これらに限定されません。
| 戻り値コード | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| ppszCoMemProviderInstanceID の値が無効です。 | |
| この操作の実行に必要なメモリをメソッドが割り当てられません。 |
関数インスタンスのプロパティストアを開きます。
| dwStgAccess | STGM | in | 開いたストリームに割り当てるアクセスモード。このメソッドでは、次のアクセスモードがサポートされます。 STGM_READSTGM_READWRITESTGM_WRITE |
| ppIPropertyStore | IPropertyStore** | out | IPropertyStore インターフェイスポインターへのポインター。 |
戻り値
戻り値には次のものが含まれますが、これらに限定されません。
| 戻り値コード | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 呼び出し元のアクセス権が不足しているか、Discovery プロバイダーがそのプロパティストアへの書き込みアクセスを許可していないため、書き込み可能なプロパティストアを開けませんでした。 | |
| dwStgAccess の値が無効です。 | |
| ppIPropertyStore が無効なメモリを指しています。 | |
| この操作の実行に必要なメモリをメソッドが割り当てられません。 |
解説(Remarks)
1 つの関数インスタンスにつき、同時に開けるプロパティストアは 1 つだけです。同じ関数インスタンスに対して OpenPropertyStore を 2 回呼び出した場合、両方の ppIPropertyStore ポインターは同じプロパティストアを指すことになります。さらに、アクセスモード(dwStgAccess パラメーターで指定)は、直近の OpenPropertyStore の呼び出しによって決定されます。アプリケーションは、別のプロパティストアを開く前に、Release を呼び出してプロパティストアを閉じる必要があります。
OpenPropertyStore が、既に削除されたデバイスのプロパティストアを返す場合があります。この場合、ストア内のプロパティキーは空になります。この状況は、デバイスの devnode が削除されたものの、そのデバイスの関数インスタンスに関連付けられたプロパティストアがまだアクセス可能な場合に発生することがあります。この状況はまれにしか発生しません。
関数インスタンスのカテゴリおよびサブカテゴリの文字列を取得します。
| ppszCoMemCategory | WORD** | out | カテゴリの null 終端識別子文字列。Category Definitions を参照してください。 このバッファーは CoTaskMemFree を使用して必ず解放してください。 |
| ppszCoMemSubCategory | WORD** | out | サブカテゴリの null 終端識別子文字列。Subcategory Definitions を参照してください。 |
戻り値
戻り値には次のものが含まれますが、これらに限定されません。
| 戻り値コード | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| この操作の実行に必要なメモリをメソッドが割り当てられません。 |
解説(Remarks)
関数インスタンスのカテゴリおよびサブカテゴリは、常にその関数インスタンスの取得元となったプロバイダーのカテゴリを指します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IFunctionInstance "{33591C10-0BED-4F02-B0AB-1530D5533EE9}" #usecom global IFunctionInstance IID_IFunctionInstance "{}" #comfunc global IFunctionInstance_GetID 4 var #comfunc global IFunctionInstance_GetProviderInstanceID 5 var #comfunc global IFunctionInstance_OpenPropertyStore 6 int,sptr #comfunc global IFunctionInstance_GetCategory 7 var,var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IFunctionInstance "{33591C10-0BED-4F02-B0AB-1530D5533EE9}" #usecom global IFunctionInstance IID_IFunctionInstance "{}" #comfunc global IFunctionInstance_GetID 4 sptr #comfunc global IFunctionInstance_GetProviderInstanceID 5 sptr #comfunc global IFunctionInstance_OpenPropertyStore 6 int,sptr #comfunc global IFunctionInstance_GetCategory 7 sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。