ホーム › System.SettingsManagementInfrastructure › ISettingsEngine
ISettingsEngine
COM公式ドキュメント
名前空間を開き、その開き方を制御するための中心的なインターフェイスです。
メソッド 16
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
vtbl 3 HRESULT GetNamespaces(WcmNamespaceEnumerationFlags Flags, void* Reserved, IItemEnumerator** Namespaces)
インストールされている名前空間の列挙子を返します。
| Flags | WcmNamespaceEnumerationFlags | in | 名前空間のコレクションに含めるコンテキストを指定する WcmNamespaceEnumerationFlags 値です。 |
| Reserved | void* | in | 予約されています。NULL を指定する必要があります。 |
| Namespaces | IItemEnumerator** | out | コレクションのメンバーにアクセスするためのメソッドを備えた IItemEnumerator インターフェイスポインターです。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。ストアが読み込まれていない場合は WCM_E_USERNOTFOUND を返します。
vtbl 4 HRESULT GetNamespace(ISettingsIdentity* SettingsID, WcmNamespaceAccess Access, void* Reserved, ISettingsNamespace** NamespaceItem)
ISettingsIdentity パラメーターで指定された既存の名前空間を開きます。
| SettingsID | ISettingsIdentity* | in | 取得する既存の名前空間を指定する ISettingsIdentity オブジェクトです。 |
| Access | WcmNamespaceAccess | in | アクセスの種類(読み取り専用か、読み書きアクセスか)を指定する WcmNamespaceAccess 値です。 |
| Reserved | void* | in | 予約されています。NULL を指定する必要があります。 |
| NamespaceItem | ISettingsNamespace** | out | 取得操作の結果となる ISettingsNamespace オブジェクトへのポインターです。 |
戻り値
このメソッドは、次のいずれかの値を返す場合があります。
| リターンコード | 説明 |
|---|---|
| 成功を示します。 | |
| ストアが現在読み込まれていないことを示します。 | |
| 指定された identity が、ストアに登録されている名前空間と一致しないことを示します。 |
返された HRESULT コードに対応するテキストメッセージを取得します。
| HResult | INT | in | このメソッドがエラーの説明を取得する対象の HRESULT コードです。 |
| Message | LPWSTR* | out | HRESULT コードに対応するテキストメッセージです。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。メッセージで返される文字列を割り当てるリソースが不足している場合は E_OUTOFMEMORY を返すことがあります。
vtbl 6 HRESULT CreateSettingsIdentity(ISettingsIdentity** SettingsID)
空の設定 identity を作成します。
| SettingsID | ISettingsIdentity** | out | 空の ISettingsIdentity オブジェクトへのポインターを返す値です。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。ISettingsIdentity オブジェクトを割り当てるリソースが不足している場合は E_OUTOFMEMORY を返すことがあります。
vtbl 7 HRESULT GetStoreStatus(void* Reserved, WcmUserStatus* Status)
スキーマストアの状態を取得します。
| Reserved | void* | in | 予約されています。NULL を指定する必要があります。 |
| Status | WcmUserStatus* | out | ストアの状態を示す WcmUserStatus 値です。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。
スキーマストアハイブを初期化して読み込みます。
| Flags | DWORD | in | Flags には値 0、または LINK_STORE_TO_ENGINE_INSTANCE の値を指定する必要があります。通常の操作では、ストアの読み込みはシステム全体の状態に影響する永続的な操作です。ストアはプロセスの終了後もクリーンアップされません。ハイブのリークを防ぐため、開発者は UnloadStore を呼び出す必要があります。ハイブのリークは、同じイメージにアクセスする際に将来の問題を引き起こす可能性があります。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。
解説(Remarks)
メモ 入力パラメーターとしてフラグ LINK_STORE_TO_ENGINE_INSTANCE を渡した場合、読み込まれたストアは現在のエンジンに関連付けられているとみなされ、このメソッドが呼び出された ISettingsEngine オブジェクトがファイナライズされるときにアンロードされます。ISettingsEngine オブジェクトは、そのすべてのポインターを解放するか、プロセスを終了することでファイナライズできます。開発者は UnloadStore を呼び出してストアを早期に強制アンロードすることもできますが、このフラグを使用する場合は必要ありません。
メモ ターゲットを使用する場合、つまりデフォルトファイルからレジストリのデフォルトの場所にストアを読み込むのではない場合は、ファイルをロックしていないことを確認するために UnloadStore を呼び出す必要があります。
vtbl 9 HRESULT UnloadStore(void* Reserved)
スキーマストアハイブをアンロードし、リソースを解放します。
| Reserved | void* | in | 予約されています。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。UnloadStore の呼び出し時に解放されていない SMI オブジェクトが存在する場合、UnloadStore は失敗し、E_ACCESSDENIED を返します。UnloadStore を呼び出す前に、すべての SMI オブジェクトを解放してください。ストアがまだ読み込まれていなかった場合は、E_INVALIDARG を返すことがあります。
vtbl 10 HRESULT RegisterNamespace(ISettingsIdentity* SettingsID, IStream* Stream, BOOL PushSettings, VARIANT* Results)
ストリームから名前空間を登録します。
| SettingsID | ISettingsIdentity* | in | 登録する名前空間を識別する ISettingsIdentity 値です。 |
| Stream | IStream* | in | 構成を指定するストリームです。 |
| PushSettings | BOOL | in | このフラグが TRUE に設定されている場合、設定はレジストリまたは初期化ファイルにプッシュされます。フラグが設定されていない場合は、設定用のストアのみが変更されます。 |
| Results | VARIANT* | out | Results は VT_VARIANT 型または VT_ARRAY 型の variant で、それぞれがマニフェストのコンパイル中に検出されたエラーまたは警告を記述する ISettingsResult オブジェクトを指します。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。
vtbl 11 HRESULT UnregisterNamespace(ISettingsIdentity* SettingsID, BOOL RemoveSettings)
既存の名前空間の登録を解除します。
| SettingsID | ISettingsIdentity* | in | 登録を解除する名前空間を識別する ISettingsIdentity インターフェイス値です。 |
| RemoveSettings | BOOL | in | true の場合、設定を削除する必要があることを指定します。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。
vtbl 12 HRESULT CreateTargetInfo(ITargetInfo** Target)
空のターゲットを作成します。
| Target | ITargetInfo** | out | 空のターゲットへの ITargetInfo インターフェイスポインターです。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。ITargetInfo オブジェクトを作成するリソースが不足している場合は E_OUTOFMEMORY を返すことがあります。
vtbl 13 HRESULT GetTargetInfo(ITargetInfo** Target)
エンジンの現在のオフラインターゲットを取得します。
| Target | ITargetInfo** | out | エンジンの現在のターゲットである ITargetInfo オブジェクトへのポインターです。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。
vtbl 14 HRESULT SetTargetInfo(ITargetInfo* Target)
エンジンの現在のオフラインターゲットを設定します。
| Target | ITargetInfo* | in | ターゲットを指定する ITargetInfo 値です。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。
vtbl 15 HRESULT CreateSettingsContext(DWORD Flags, void* Reserved, ISettingsContext** SettingsContext)
設定コンテキストを作成します。
| Flags | DWORD | in | Flags パラメーターの値は、"通常モード" を示す 0、または LIMITED_VALIDATION_MODE を示す 0x00000001 を指定できます。通常モードでは、設定コンテキストは、リスト項目に対して行われたすべての変更を、ターゲットイメージの現在の状態に照らして検証します。たとえば、イメージ内に既に存在するリスト要素を作成しようとすると、作成操作は失敗します。LIMITED_VALIDATION_MODE では、矛盾するデータは受け入れられません。リスト項目を変更してから追加することはできません。ただし、行われた変更をシステムの現在の状態に照らして検証する処理は行われません。LIMITED_VALIDATION_MODE は、シリアル化するコンテキストを作成する目的の場合にのみ使用してください。ISettingsEngine::ApplySettingsContext に使用するコンテキストを作成するときは、このフラグを指定しないでください。指定した場合、コンテキストが十分に検証されず、適用時に失敗する可能性があります。 |
| Reserved | void* | in | 予約されています。NULL を指定する必要があります。 |
| SettingsContext | ISettingsContext** | out | 作成されたコンテキストを表す ISettingsContext オブジェクトへのポインターです。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。ISettingsContext オブジェクトを作成するリソースが不足していた場合、このメソッドは E_OUTOFMEMORY を返すことがあります。
vtbl 16 HRESULT SetSettingsContext(ISettingsContext* SettingsContext)
| SettingsContext | ISettingsContext* | in | 設定する ISettingsContext インターフェイスへのポインタである。 |
vtbl 17 HRESULT ApplySettingsContext(ISettingsContext* SettingsContext, LPWSTR** pppwzIdentities, UINT_PTR* pcIdentities)
設定コンテキストを適用します。
| SettingsContext | ISettingsContext* | in | 適用する設定データを含むコンテキストです。 |
| pppwzIdentities | LPWSTR** | out | システムに適用された名前空間の identity を文字列形式で表したものです。 |
| pcIdentities | UINT_PTR* | out | pppwzIdentities 内の identity の数です。 |
戻り値
このメソッドは HRESULT 値を返します。S_OK は成功を示します。
vtbl 18 HRESULT GetSettingsContext(ISettingsContext** SettingsContext)
| SettingsContext | ISettingsContext** | out | 現在の ISettingsContext インターフェイスを受け取るポインタである。 |
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
出力引数:
#define global IID_ISettingsEngine "{9F7D7BB9-20B3-11DA-81A5-0030F1642E3C}" #usecom global ISettingsEngine IID_ISettingsEngine "{9F7D7BB5-20B3-11DA-81A5-0030F1642E3C}" #comfunc global ISettingsEngine_GetNamespaces 3 int,sptr,sptr #comfunc global ISettingsEngine_GetNamespace 4 sptr,int,sptr,sptr #comfunc global ISettingsEngine_GetErrorDescription 5 int,var #comfunc global ISettingsEngine_CreateSettingsIdentity 6 sptr #comfunc global ISettingsEngine_GetStoreStatus 7 sptr,var #comfunc global ISettingsEngine_LoadStore 8 int #comfunc global ISettingsEngine_UnloadStore 9 sptr #comfunc global ISettingsEngine_RegisterNamespace 10 sptr,sptr,int,var #comfunc global ISettingsEngine_UnregisterNamespace 11 sptr,int #comfunc global ISettingsEngine_CreateTargetInfo 12 sptr #comfunc global ISettingsEngine_GetTargetInfo 13 sptr #comfunc global ISettingsEngine_SetTargetInfo 14 sptr #comfunc global ISettingsEngine_CreateSettingsContext 15 int,sptr,sptr #comfunc global ISettingsEngine_SetSettingsContext 16 sptr #comfunc global ISettingsEngine_ApplySettingsContext 17 sptr,var,var #comfunc global ISettingsEngine_GetSettingsContext 18 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ISettingsEngine "{9F7D7BB9-20B3-11DA-81A5-0030F1642E3C}" #usecom global ISettingsEngine IID_ISettingsEngine "{9F7D7BB5-20B3-11DA-81A5-0030F1642E3C}" #comfunc global ISettingsEngine_GetNamespaces 3 int,sptr,sptr #comfunc global ISettingsEngine_GetNamespace 4 sptr,int,sptr,sptr #comfunc global ISettingsEngine_GetErrorDescription 5 int,sptr #comfunc global ISettingsEngine_CreateSettingsIdentity 6 sptr #comfunc global ISettingsEngine_GetStoreStatus 7 sptr,sptr #comfunc global ISettingsEngine_LoadStore 8 int #comfunc global ISettingsEngine_UnloadStore 9 sptr #comfunc global ISettingsEngine_RegisterNamespace 10 sptr,sptr,int,sptr #comfunc global ISettingsEngine_UnregisterNamespace 11 sptr,int #comfunc global ISettingsEngine_CreateTargetInfo 12 sptr #comfunc global ISettingsEngine_GetTargetInfo 13 sptr #comfunc global ISettingsEngine_SetTargetInfo 14 sptr #comfunc global ISettingsEngine_CreateSettingsContext 15 int,sptr,sptr #comfunc global ISettingsEngine_SetSettingsContext 16 sptr #comfunc global ISettingsEngine_ApplySettingsContext 17 sptr,sptr,sptr #comfunc global ISettingsEngine_GetSettingsContext 18 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。