ホーム › System.SettingsManagementInfrastructure › ISettingsItem

ISettingsItem

COM

📘 Microsoft Learn (日本語) · English

IID9f7d7bbb-20b3-11da-81a5-0030f1642e3c継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

設定ツリーを走査し、特定の設定のメタデータを取得し、その値を取得または変更します。

メソッド 22

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

vtbl 3 HRESULT GetName(LPWSTR* Name)

アイテムの名前を取得します。

Name

LPWSTR*

out

アイテムの名前。

戻り値

このメソッドは HRESULT 値を返します。S_OK は成功を示します。Name を割り当てるためのリソースが不足している場合は E_OUTOFMEMORY を返すことがあります。

vtbl 4 HRESULT GetValue(VARIANT* Value)

アイテムから現在の値を取得します。

Value

VARIANT*

out

アイテムの値。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
HRESULT_FROM_WIN32 (ERROR_INVALID_OPERATION)	アイテムがスカラー設定ではないことを示します。
E_OUTOFMEMORY	返すデータを割り当てるためのリソースが不足していることを示します。
S_FALSE	アイテムに値が存在しないことを示します。

vtbl 5 HRESULT SetValue(VARIANT* Value)

アイテムの値を設定します。

Value

VARIANT*

アイテムの値を格納する Variant。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
WCM_E_INVALIDVALUE, WCM_E_INVALIDVALUEFORMAT, or WCM_E_INVALIDDATATYPE	値がアイテムに対して正しい型ではないか、値を正しい型に変換できないことを示します。
WCM_E_READONLYITEM	アイテムが読み取り専用であるか、名前空間が ReadOnly モードで開かれているため、アイテムに書き込めないことを示します。

vtbl 6 HRESULT GetSettingType(WcmSettingType* Type)

アイテムの設定タイプを取得します。

Type

WcmSettingType*

out

アイテムの設定タイプを格納する WcmSettingType 値。

戻り値

このメソッドは HRESULT 値を返します。S_OK は成功を示します。

vtbl 7 HRESULT GetDataType(WcmDataType* Type)

アイテムの型情報を取得します。

Type

WcmDataType*

out

アイテムのデータ型を示す WcmDataType 値。

戻り値

このメソッドは HRESULT 値を返します。S_OK は成功を示します。

vtbl 8 HRESULT GetValueRaw(BYTE** Data, DWORD* DataSize)

現在のアイテムから値をバイト配列として取得します。

Data	BYTE**	out	CoTaskMemAlloc で割り当てられた、長さ DataSize の BYTE ポインターの配列。
DataSize	DWORD*	out	データの長さ。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
HRESULT_FROM_WIN32 (ERROR_INVALID_OPERATION)	アイテムがスカラー設定ではないことを示します。
E_OUTOFMEMORY	返すデータを割り当てるためのリソースが不足していることを示します。
S_FALSE	アイテムに値が存在しないことを示します。

vtbl 9 HRESULT SetValueRaw(INT DataType, BYTE* Data, DWORD DataSize)

生データを与えることで現在のアイテムの値を設定します。

DataType	INT	in	アイテムのデータ型。
Data	BYTE*	in	アイテムの値を格納するバイト配列。
DataSize	DWORD	in	バイト配列のサイズ。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
WCM_E_INVALIDVALUE, WCM_E_INVALIDVALUEFORMAT, or WCM_E_INVALIDDATATYPE	値がアイテムに対して正しい型ではないか、値を正しい型に変換できないことを示します。
WCM_E_READONLYITEM	アイテムが読み取り専用であるか、名前空間が ReadOnly モードで開かれているため、アイテムに書き込めないことを示します。

vtbl 10 HRESULT HasChild(BOOL* ItemHasChild)

現在のアイテムが子アイテムを持つかどうかを判定します。

ItemHasChild

BOOL*

out

子アイテムが存在する場合は True、それ以外の場合は false。

戻り値

このメソッドは HRESULT 値を返します。S_OK は成功を示します。

vtbl 11 HRESULT Children(IItemEnumerator** Children)

このアイテムに対応する子アイテムのディクショナリを取得します。

Children

IItemEnumerator**

out

子にアクセスするために使用する IItemEnumerator インターフェイスポインター。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
E_OUTOFMEMORY	子の列挙子を割り当てるためのリソースが不足していることを示します。
HRESULT_FROM_WIN32 (ERROR_INVALID_OPERATION)	アイテムが子を持つことをサポートしていないことを示します。

vtbl 12 HRESULT GetChild(LPWSTR Name, ISettingsItem** Child)

指定した名前を持つ子アイテムを取得します。

Name	LPWSTR	in	子アイテムの名前。
Child	ISettingsItem**	out	子アイテムに対応する ISettingsItem オブジェクトへのポインター。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
WCM_E_STATENODENOTFOUND	要求された名前がアイテムの子ではないことを示します。
WCM_E_WRONGESCAPESTRING	名前に認識できない XML エスケープシーケンスが含まれていることを示します。
WCM_E_INVALIDPATH	名前の形式が正しくないことを示します。
WCM_E_INVALIDKEY	パスの指定が正しくなく、リストアイテムに対して誤ったキーを参照していることを示します。
HRESULT_FROM_WIN32(ERROR_INVALID_OPERATION)	アイテムが子をサポートしていないことを示します。

vtbl 13 HRESULT GetSettingByPath(LPWSTR Path, ISettingsItem** Setting)

指定したパスに基づいて設定を取得します。

Path	LPWSTR	in	取得するリスト要素または属性のパス。パスは現在の設定からの相対パスです。
Setting	ISettingsItem**	out	アイテムにアクセスするために使用する ISettingsItem インターフェイスポインター。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
WCM_E_STATENODENOTFOUND	存在しないアイテムを取得しようとしたことを示します。
WCM_E_WRONGESCAPESTRING	パスに認識できない XML エスケープシーケンスが含まれていることを示します。
WCM_E_INVALIDPATH	パスの形式が正しくないことを示します。
WCM_E_INVALIDKEY	パスの指定が正しくなく、リストアイテムに対して誤ったキーを参照していることを示します。

vtbl 14 HRESULT CreateSettingByPath(LPWSTR Path, ISettingsItem** Setting)

パスで指定された設定オブジェクトを作成します。

Path	LPWSTR	in	パスへのポインター。
Setting	ISettingsItem**	out	新しく作成された ISettingsItem アイテムへのポインター。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
WCM_E_STATENODENOTFOUND	リスト要素ではない、またはまだ存在しないアイテムを作成するためにメソッドが呼び出されたことを示します。
WCM_E_READONLYITEM	アイテムが読み取り専用である、または名前空間が ReadOnly モードで開かれているなどの理由で、アイテムに書き込めないことを示します。
WCM_E_INVALIDVALUE, WCM_E_INVALIDVALUEFORMAT, or WCM_E_INVALIDDATATYPE	キーに対して指定された値を、文字列値を符号なし整数に変換するなど、適切な型に変換できないことを示します。
WCM_E_WRONGESCAPESTRING	パスに認識できない XML エスケープシーケンスが含まれていることを示します。
WCM_E_INVALIDKEY	パスの指定が正しくなく、リストアイテムに対して誤ったキーを参照していることを示します。

解説(Remarks)

Note スカラーのリストアイテムを作成する場合は、結果として得られる ISettingsItem を解放する前に値を設定する必要があります。そうしないと永続化されません。

vtbl 15 HRESULT RemoveSettingByPath(LPWSTR Path)

パスで指定された設定オブジェクトを削除します。

Path

LPWSTR

削除するアイテムのパス。パスは現在のアイテムからの相対パスです。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
WCM_E_STATENODENOTFOUND	存在しないアイテムを削除しようとしたことを示します。
HRESULT_FROM_WIN32 (ERROR_INVALID_OPERATION)	リスト要素ではない要素を削除しようとしたことを示します。
WCM_E_READONLYITEM	アイテムが読み取り専用であるか、名前空間が ReadOnly モードで開かれているため、アイテムに書き込めないことを示します。
WCM_E_WRONGESCAPESTRING	パスに認識できない XML エスケープシーケンスが含まれていることを示します。
WCM_E_INVALIDPATH	パスの形式が正しくないことを示します。
WCM_E_INVALIDKEY	パスの指定が正しくなく、リストアイテムに対して誤ったキーを参照していることを示します。

vtbl 16 HRESULT GetListKeyInformation(LPWSTR* KeyName, WcmDataType* DataType)

このアイテムのリスト情報を取得します。

KeyName	LPWSTR*	out	キーの名前。
DataType	WcmDataType*	out	アイテムのデータ型を示す WcmDataType 値。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
S_FALSE	リストが keyValue でキー付けされており、KeyName が NULL であることを示します。
HRESULT_FROM_WIN32(ERROR_INVALID_OPERATION)	アイテムがリストまたはリスト要素ではないことを示します。
E_OUTOFMEMORY	操作を完了するためのリソースが不足していることを示します。

vtbl 17 HRESULT CreateListElement(VARIANT* KeyData, ISettingsItem** Child)

新しいリスト要素を作成します。

KeyData	VARIANT*	in	新しいリストアイテムの識別情報を定義するキーの情報。key data パラメーターの正しい値を判断するには、ISettingsItem::GetListKeyInformation から返される情報を参照してください。ISettingsItem::GetListKeyInformation から取得した variant は、キーの型に変換できる必要があります。ISettingsItem::GetListKeyInformation メソッドが S_FALSE を返す場合は、key data に文字列型を使用してください。
Child	ISettingsItem**	out	新しく作成された ISettingsItem リストアイテムへのポインター。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
HRESULT_FROM_WIN32 (ERROR_INVALID_OPERATION)	設定タイプが list ではないアイテムに対してメソッドが呼び出されたことを示します。
WCM_E_INVALIDVALUE, WCM_E_INVALIDVALUEFORMAT, or WCM_E_INVALIDDATATYPE	キーを正しい型に変換できないリストを作成しようとしたことを示します。
WCM_E_READONLYITEM	アイテムが読み取り専用であるか、名前空間が ReadOnly モードで開かれているため、アイテムに書き込めないことを示します。

解説(Remarks)

vtbl 18 HRESULT RemoveListElement(LPWSTR ElementName)

指定した名前の既存のリスト要素を削除します。

ElementName

LPWSTR

削除する要素の名前。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
WCM_E_STATENODENOTFOUND	存在しないアイテムを削除しようとしたことを示します。
E_INVALIDARG	アイテムの設定タイプが list ではないことを示します。
WCM_E_READONLYITEM	アイテムが読み取り専用であるか、名前空間が ReadOnly モードで開かれているため、アイテムに書き込めないことを示します。
WCM_E_WRONGESCAPESTRING	パスに認識できない XML エスケープシーケンスが含まれていることを示します。
WCM_E_INVALIDPATH	パスの形式が正しくないことを示します。
WCM_E_INVALIDKEY	パスの指定が正しくなく、リストアイテムに対して誤ったキーを参照していることを示します。

vtbl 19 HRESULT Attributes(IItemEnumerator** Attributes)

属性のディクショナリを取得します。

Attributes

IItemEnumerator**

out

属性のディクショナリを表す IItemEnumerator オブジェクトへのポインター。

戻り値

このメソッドは HRESULT 値を返します。S_OK は成功を示します。属性を割り当てるためのリソースが不足している場合は E_OUTOFMEMORY を返すことがあります。

vtbl 20 HRESULT GetAttribute(LPWSTR Name, VARIANT* Value)

名前を指定して属性の値を取得します。

Name	LPWSTR	in	属性の名前。
Value	VARIANT*	out	属性の値。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
WCM_E_ATTRIBUTENOTFOUND	要求された属性がアイテムに指定されていないことを示します。
E_OUTOFMEMORY	ユーザーに情報を返すためのリソースが不足していることを示します。

vtbl 21 HRESULT GetPath(LPWSTR* Path)

アイテムのパスを取得します。

Path

LPWSTR*

out

現在の設定へのパス。このパスは不透明なものとして扱い、CreateSettingByPath、GetSettingByPath、または RemoveSettingByPath の呼び出しにのみ使用してください。

戻り値

このメソッドは HRESULT 値を返します。S_OK は成功を示します。リソースが不足している場合は E_OUTOFMEMORY を返すことがあります。

vtbl 22 HRESULT GetRestrictionFacets(WcmRestrictionFacets* RestrictionFacets)

このアイテムに対して定義された制限を取得します。

RestrictionFacets

WcmRestrictionFacets*

out

このアイテムに対して定義された WcmRestrictionFacets 値のビットマスク。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
HRESULT_FROM_WIN32 (ERROR_INVALID_OPERATION)	アイテムがスカラー設定ではないことを示します。
S_FALSE	アイテムに値が存在しないことを示します。

vtbl 23 HRESULT GetRestriction(WcmRestrictionFacets RestrictionFacet, VARIANT* FacetData)

指定した制限の情報を取得します。

RestrictionFacet	WcmRestrictionFacets	in	制限ファセットの種類を示す WcmRestrictionFacets 値。
FacetData	VARIANT*	out	ファセットデータへのポインター。

戻り値

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

リターンコード	説明
S_OK	成功を示します。
HRESULT_FROM_WIN32 (ERROR_INVALID_OPERATION)	非スカラー設定に対してメソッドが呼び出されたことを示します。
E_INVALIDARG	要求された制限ファセットがこのアイテムに対して定義されていないことを示します。

vtbl 24 HRESULT GetKeyValue(VARIANT* Value)

イメージ内に既に存在する任意のリスト(たとえば DNS、http 設定、ユーザーアカウント情報など)のキー値を抽出します。

Value

VARIANT*

out

リスト要素のキーの値。返される値の型は、キーの実際の型です。たとえば、動的にキー付けされたリストの場合、型は文字列です。値は、格納のために SMI によって加えられた変更を元に戻すために適切にアンエスケープされます。事前定義された VARIANT 型が正しくない場合、VARIANT 型は正しい型で上書きされます。

戻り値

リターンコード	説明
HRESULT_FROM_WIN32 (ERROR_INVALID_OPERATION)	アイテムがリスト要素ではありません。
E_OUTOFMEMORY	ユーザーに情報を返すためのリソースが不足しています。
E_INVALIDARG	値が null です。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ISettingsItem "{9F7D7BBB-20B3-11DA-81A5-0030F1642E3C}"
#usecom global ISettingsItem IID_ISettingsItem "{}"
#comfunc global ISettingsItem_GetName                3 var
#comfunc global ISettingsItem_GetValue               4 var
#comfunc global ISettingsItem_SetValue               5 var
#comfunc global ISettingsItem_GetSettingType         6 var
#comfunc global ISettingsItem_GetDataType            7 var
#comfunc global ISettingsItem_GetValueRaw            8 var,var
#comfunc global ISettingsItem_SetValueRaw            9 int,var,int
#comfunc global ISettingsItem_HasChild               10 var
#comfunc global ISettingsItem_Children               11 sptr
#comfunc global ISettingsItem_GetChild               12 wstr,sptr
#comfunc global ISettingsItem_GetSettingByPath       13 wstr,sptr
#comfunc global ISettingsItem_CreateSettingByPath    14 wstr,sptr
#comfunc global ISettingsItem_RemoveSettingByPath    15 wstr
#comfunc global ISettingsItem_GetListKeyInformation  16 var,var
#comfunc global ISettingsItem_CreateListElement      17 var,sptr
#comfunc global ISettingsItem_RemoveListElement      18 wstr
#comfunc global ISettingsItem_Attributes             19 sptr
#comfunc global ISettingsItem_GetAttribute           20 wstr,var
#comfunc global ISettingsItem_GetPath                21 var
#comfunc global ISettingsItem_GetRestrictionFacets   22 var
#comfunc global ISettingsItem_GetRestriction         23 int,var
#comfunc global ISettingsItem_GetKeyValue            24 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ISettingsItem "{9F7D7BBB-20B3-11DA-81A5-0030F1642E3C}"
#usecom global ISettingsItem IID_ISettingsItem "{}"
#comfunc global ISettingsItem_GetName                3 sptr
#comfunc global ISettingsItem_GetValue               4 sptr
#comfunc global ISettingsItem_SetValue               5 sptr
#comfunc global ISettingsItem_GetSettingType         6 sptr
#comfunc global ISettingsItem_GetDataType            7 sptr
#comfunc global ISettingsItem_GetValueRaw            8 sptr,sptr
#comfunc global ISettingsItem_SetValueRaw            9 int,sptr,int
#comfunc global ISettingsItem_HasChild               10 sptr
#comfunc global ISettingsItem_Children               11 sptr
#comfunc global ISettingsItem_GetChild               12 wstr,sptr
#comfunc global ISettingsItem_GetSettingByPath       13 wstr,sptr
#comfunc global ISettingsItem_CreateSettingByPath    14 wstr,sptr
#comfunc global ISettingsItem_RemoveSettingByPath    15 wstr
#comfunc global ISettingsItem_GetListKeyInformation  16 sptr,sptr
#comfunc global ISettingsItem_CreateListElement      17 sptr,sptr
#comfunc global ISettingsItem_RemoveListElement      18 wstr
#comfunc global ISettingsItem_Attributes             19 sptr
#comfunc global ISettingsItem_GetAttribute           20 wstr,sptr
#comfunc global ISettingsItem_GetPath                21 sptr
#comfunc global ISettingsItem_GetRestrictionFacets   22 sptr
#comfunc global ISettingsItem_GetRestriction         23 int,sptr
#comfunc global ISettingsItem_GetKeyValue            24 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。