ホーム › System.Contacts › IContactProperties

IContactProperties

COM

IID70dd27dd-5cbd-46e8-bef0-23b6b346288f継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

使用しないでください。IContact のプロパティを取得、設定、作成、および削除するために使用されます。プロパティ名と拡張メカニズムは icontactproperties.h に記載されています。

メソッド 13

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

vtbl 3 HRESULT GetString(LPWSTR pszPropertyName, DWORD dwFlags, LPWSTR pszValue, DWORD cchValue, DWORD* pdwcchPropertyValueRequired)

指定したプロパティの文字列値を、呼び出し側が確保したバッファーに取得します。

pszPropertyName	LPWSTR	in	取得するプロパティを指定します。
dwFlags	DWORD	in	CGD_DEFAULT を指定する必要があります。
pszValue	LPWSTR	inout	プロパティを格納するためのユーザー確保バッファーを指定します。
cchValue	DWORD	in	確保されたバッファーのサイズを文字数単位で指定します。
pdwcchPropertyValueRequired	DWORD*	inout	失敗時に、pszValue に必要なサイズが格納されます。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	pszValue に null 終端の値が格納されます。
S_FALSE	この値のデータがありません。過去にプロパティが存在したがその値が削除されたか、またはプロパティが他のプロパティのコンテナー(toplevel/secondlevel[3])です。pszValue のバッファーはゼロクリアされています。
ERROR_PATH_NOT_FOUND	このプロパティ名に対するデータが見つかりません。
ERROR_INSUFFICIENT_BUFFER	pszValue が値を格納するのに十分な大きさではありませんでした。必要なバッファーサイズは *pdwcchPropertyValueRequired に格納されます。

解説(Remarks)

単一レベルのプロパティを取得するには、pszPropertyName にプロパティ名を設定します。

多値(階層)プロパティから値を取得するには、目的のインデックスを pszPropertyName の一部として toplevel/secondlevel[1]/thirdlevel の形式で含めます。注: セットの最初の要素はインデックス 1 であるため、インデックス [0] は無効です。次の例は、連絡先の 4 番目の Name プロパティの Title を取得します。

L"NameCollection/Name[4]/Title"

vtbl 4 HRESULT GetDate(LPWSTR pszPropertyName, DWORD dwFlags, FILETIME* pftDateTime)

指定したプロパティの日付と時刻の値を、呼び出し側の FILETIME 構造体に取得します。すべての時刻は協定世界時(UTC)として格納および返されます。

pszPropertyName	LPWSTR	in	取得するプロパティを指定します。
dwFlags	DWORD	in	CGD_DEFAULT を指定する必要があります。
pftDateTime	FILETIME*	inout	呼び出し側が確保した FILETIME 構造体を指定します。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	pftDateTime に有効な FILETIME が格納されます。
S_FALSE	過去にプロパティが存在しましたが、その値は削除されています。 FILETIME はゼロクリアされています。
ERROR_PATH_NOT_FOUND	このプロパティ名に対するデータが見つかりません。

解説(Remarks)

単一レベルのプロパティを取得するには、pszPropertyName にプロパティ名を設定します。

多値(階層)プロパティから値を取得するには、目的のインデックスを pszPropertyName の一部として toplevel/secondlevel[1]/thirdlevel の形式で含めます。注: セットの最初の要素はインデックス 1 であるため、インデックス [0] は無効です。

vtbl 5 HRESULT GetBinary(LPWSTR pszPropertyName, DWORD dwFlags, LPWSTR pszContentType, DWORD cchContentType, DWORD* pdwcchContentTypeRequired, IStream** ppStream)

IStream インターフェイス[構造化ストレージ]を使用して、プロパティのバイナリデータを取得します。

pszPropertyName	LPWSTR	in	取得するプロパティを指定します。
dwFlags	DWORD	in	CGD_DEFAULT を指定する必要があります。
pszContentType	LPWSTR	inout	MIME コンテンツタイプを格納するためのユーザー確保バッファーを指定します。
cchContentType	DWORD	in	確保されたバッファーのサイズを文字数単位で指定します。
pdwcchContentTypeRequired	DWORD*	inout	失敗時に、pszContentType に必要なサイズが格納されます。
ppStream	IStream**	out	成功時に、新しい IStream インターフェイス[構造化ストレージ]が格納されます。これを使用してバイナリデータを取得します。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	ppStream に IStream インターフェイス[構造化ストレージ]が格納されます。呼び出し側は参照を解放する必要があります。
S_FALSE	この値のデータがありません。過去にプロパティが存在したがその値が削除されたか、またはプロパティが他のプロパティのコンテナー (toplevel/secondlevel[3])です。pszContentType のバッファーはゼロクリアされています。
ERROR_PATH_NOT_FOUND	このプロパティ名に対するデータが見つかりません。
ERROR_INVALID_DATATYPE	スキーマの都合により、このプロパティの値を取得できません。
ERROR_INSUFFICIENT_BUFFER	pszContentType が値を格納するのに十分な大きさではありませんでした。必要なバッファーサイズは pdwcchContentTypeRequired に格納されます。

解説(Remarks)

単一レベルのプロパティを取得するには、pszPropertyName にプロパティ名を設定します。

削除されたプロパティの場合、このメソッドは S_OK と長さ 0 の IStream インターフェイス[構造化ストレージ]を返します。注: バイナリ型ではないプロパティの場合、このメソッドは IStream に誤ったデータを返すことがあります。

vtbl 6 HRESULT GetLabels(LPWSTR pszArrayElementName, DWORD dwFlags, LPWSTR pszLabels, DWORD cchLabels, DWORD* pdwcchLabelsRequired)

指定した配列要素名のラベルを取得します。

pszArrayElementName	LPWSTR	in	配列要素名を指定します。
dwFlags	DWORD	in	CGD_DEFAULT を指定する必要があります。
pszLabels	LPWSTR	inout	ラベルを格納するためのユーザー確保バッファーを指定します。
cchLabels	DWORD	in	確保されたバッファーのサイズを文字数単位で指定します。
pdwcchLabelsRequired	DWORD*	inout	失敗時に、pszLabels に必要なサイズが格納されます。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	取得に成功しました。
ERROR_PATH_NOT_FOUND	このプロパティ名に対するデータが見つかりません。
ERROR_INVALID_DATATYPE	スキーマの都合により、このプロパティの値を取得できません。
ERROR_INSUFFICIENT_BUFFER	pszLabels が値を格納するのに十分な大きさではありませんでした。必要なバッファーサイズは *pdwcchLabelsRequired に格納されます。

解説(Remarks)

pszLabels のユーザー確保バッファーには、null 終端文字列を連結したリストと、それに続く空文字列が格納されます。言い換えると、最後の 4 バイトはゼロになります。例えば L"str1\0str2\0\0" のようになります。注: 多値プロパティに対してのみ成功します。また、設定した順序とは異なる順序でラベルを返すことがあります。

vtbl 7 HRESULT SetString(LPWSTR pszPropertyName, DWORD dwFlags, LPWSTR pszValue)

指定したプロパティの文字列値を、指定した null 終端文字列の値に設定します。

pszPropertyName	LPWSTR	in	設定するプロパティを指定します。
dwFlags	DWORD	in	CGD_DEFAULT を使用すると、pszPropertyName の値を作成または上書きできます。
pszValue	LPWSTR	in	格納する null 終端文字列を指定します。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	このプロパティに値が設定されました。
ERROR_PATH_NOT_FOUND	設定に対して無効なプロパティ名です。
ERROR_INVALID_DATATYPE	スキーマの都合により、このプロパティの値を設定できません。

解説(Remarks)

単一レベルのプロパティを設定するには、pszPropertyName にプロパティ名を設定します。

多値プロパティのプロパティを設定するには、pszPropertyName を次の形式にします: toplevel/secondlevel[4]/thirdlevel。

vtbl 8 HRESULT SetDate(LPWSTR pszPropertyName, DWORD dwFlags, FILETIME ftDateTime)

指定したプロパティの日付と時刻の値を、指定した FILETIME に設定します。すべての時刻は協定世界時(UTC)として格納および返されます。

pszPropertyName	LPWSTR	in	設定するプロパティを指定します。
dwFlags	DWORD	in	CGD_DEFAULT を使用すると、pszPropertyName の値を作成または上書きできます。
ftDateTime	FILETIME	in	日付として使用する FILETIME 構造体。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	このプロパティに値が設定されました。
ERROR_PATH_NOT_FOUND	設定に対して無効なプロパティ名です。
ERROR_INVALID_DATATYPE	スキーマの都合により、このプロパティの値を設定できません。

vtbl 9 HRESULT SetBinary(LPWSTR pszPropertyName, DWORD dwFlags, LPWSTR pszContentType, IStream* pStream)

指定したプロパティのバイナリデータを、指定した IStream インターフェイス[構造化ストレージ]の内容に設定します。この IStream には、null 終端文字列(MIME タイプとして)のデータが含まれます。

pszPropertyName	LPWSTR	in	設定するプロパティを指定します。
dwFlags	DWORD	in	CGD_DEFAULT を使用すると、pszPropertyName の値を作成または上書きできます。
pszContentType	LPWSTR	in	CGD_DEFAULT のときに格納する MIME タイプを表す null 終端文字列を指定します。
pStream	IStream*	in	このノードに配置するデータを含む IStream インターフェイス[構造化ストレージ]オブジェクトへのポインター。注: IStream::Read は、長さ 0 の読み取りで成功するまでデータに対して呼び出されます。それ以外の戻り値は失敗となり、変更は行われません。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	値が正常に設定されました。
ERROR_PATH_NOT_FOUND	設定に対して無効なプロパティ名であるか、削除するプロパティ名が存在しません。
ERROR_INVALID_DATATYPE	スキーマの都合により、このプロパティの値を設定できません。

解説(Remarks)

単一レベルのプロパティを設定するには、pszPropertyName にプロパティ名を設定します。

多値プロパティのプロパティを設定するには、pszPropertyName を次の形式にします: toplevel/secondlevel[4]/thirdlevel。

vtbl 10 HRESULT SetLabels(LPWSTR pszArrayElementName, DWORD dwFlags, DWORD dwLabelCount, LPWSTR* ppszLabels)

渡されたラベルのセットを、指定したプロパティのラベルセットに追加します。注: このメソッドは重複するラベルのチェックを行いません。

pszArrayElementName	LPWSTR	in	ラベルを付けるプロパティを指定します。
dwFlags	DWORD	in	CGD_DEFAULT を指定する必要があります。
dwLabelCount	DWORD	in	配列内のラベルの数を指定します。
ppszLabels	LPWSTR*	in	LPCWSTR ラベルの配列を指定します。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	ラベルが正常に設定されました。
ERROR_PATH_NOT_FOUND	このプロパティ名に対するデータが見つかりません。
ERROR_INVALID_DATATYPE	スキーマの都合により、このプロパティの値を設定できません。

vtbl 11 HRESULT CreateArrayNode(LPWSTR pszArrayName, DWORD dwFlags, BOOL fAppend, LPWSTR pszNewArrayElementName, DWORD cchNewArrayElementName, DWORD* pdwcchNewArrayElementNameRequired)

多値プロパティに新しい配列ノードを作成します。

pszArrayName	LPWSTR	in	新しいノードを作成する対象のトップレベルプロパティを指定します。
dwFlags	DWORD	in	CGD_DEFAULT を指定する必要があります。
fAppend	BOOL	in	後に挿入する場合は TRUE、前に挿入する場合は FALSE。
pszNewArrayElementName	LPWSTR	inout	新しい配列要素名を格納するためのユーザー確保バッファーを指定します。
cchNewArrayElementName	DWORD	in	確保されたバッファーのサイズを文字数単位で指定します。
pdwcchNewArrayElementNameRequired	DWORD*	inout	失敗時に、pszNewArrayElementName に必要なサイズが格納されます。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	新しいノードが作成され、その名前が pszNewArrayElementName に格納されます。
ERROR_PATH_NOT_FOUND	配列名が無効な場合に、マクロ HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND) が返されます。
ERROR_INSUFFICIENT_BUFFER	pszNewArrayElementName が値を格納するのに十分な大きさでない場合に、マクロ HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) が返されます。必要なバッファーサイズは pdwcchNewArrayElementNameRequired に格納されます。

解説(Remarks)

注既存のセットの最初の要素はインデックス 1 にあります。

toplevel/secondlevel[1] に pszArrayName を作成するには、 pszArrayName == toplevel、fAppend=FALSE でこの関数を呼び出します。

[namespace]toplevel/secondlevel[1] の拡張である配列ノードを作成するには、 pszArrayName == [namespace:secondlevel]toplevel でこの関数を呼び出します。

セットに追加するには、代わりに fAppend=TRUE を渡します。その場合、pszNewArrayElementName にはインデックスを含む結果の配列ノード名が格納されます。

vtbl 12 HRESULT DeleteProperty(LPWSTR pszPropertyName, DWORD dwFlags)

指定したプロパティの値を削除します。プロパティの変更情報とバージョン情報は、引き続き IContactPropertyCollection で列挙できます。

pszPropertyName	LPWSTR	in	値を削除するプロパティを指定します。
dwFlags	DWORD	in	CGD_DEFAULT を指定する必要があります。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	プロパティが正常に削除されました。
ERROR_PATH_NOT_FOUND	削除するプロパティ名が存在しません。

vtbl 13 HRESULT DeleteArrayNode(LPWSTR pszArrayElementName, DWORD dwFlags)

指定した配列エントリのデータを削除します。

pszArrayElementName	LPWSTR	in	すべてのデータを削除する対象の配列エントリを指定します。
dwFlags	DWORD	in	CGD_DEFAULT を指定する必要があります。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	ノードが削除されました。
ERROR_PATH_NOT_FOUND	削除するプロパティ名が存在しません。

解説(Remarks)

注要素のインデックスはセット全体を通じて変更されません。配列ノードの要素 ID、変更情報、バージョン情報は、引き続き IContactPropertyCollection で列挙できます。

vtbl 14 HRESULT DeleteLabels(LPWSTR pszArrayElementName, DWORD dwFlags)

指定した配列エントリのラベルを削除します。

pszArrayElementName	LPWSTR	in	ラベルを削除する対象のプロパティを指定します。
dwFlags	DWORD	in	CGD_DEFAULT を指定する必要があります。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	ラベルが正常に削除されました。
ERROR_PATH_NOT_FOUND	削除するプロパティ名が存在しません。

vtbl 15 HRESULT GetPropertyCollection(IContactPropertyCollection** ppPropertyCollection, DWORD dwFlags, LPWSTR pszMultiValueName, DWORD dwLabelCount, LPWSTR* ppszLabels, BOOL fAnyLabelMatches)

現在の連絡先に対する IContactPropertyCollection を返します。オプションで、一部の値のみを列挙するように IContactPropertyCollection をフィルターできます。

ppPropertyCollection	IContactPropertyCollection**	out	成功時に、新しい IContactPropertyCollection を指します。
dwFlags	DWORD	in	CGD_DEFAULT を指定する必要があります。
pszMultiValueName	LPWSTR	in	コレクションの名前を指定します(例: emailAddresses または [namespace]arrayNode)。 NULL の場合、すべてのコレクションから ppszLabels が検索されます。
dwLabelCount	DWORD	in	ppszLabels 内のラベルの数を指定します。ゼロの場合、ラベルを持つすべてのサブプロパティが返されます。
ppszLabels	LPWSTR*	in	テスト対象となる文字列ラベルの配列を指定します。配列内のすべてのラベルは有効な文字列(NULL でない)に設定する必要があります。
fAnyLabelMatches	BOOL	in	特定のプロパティにいずれかのラベルが存在すればそのプロパティに一致とする場合は TRUE。プロパティに一致させるためにすべてのラベルが存在する必要がある場合は FALSE。

戻り値

型: HRESULT

次のいずれかの値を返します:

戻り値	説明
S_OK	常に成功を返します。

解説(Remarks)

呼び出し側は、オプションのラベルフィルターを適用して、トップレベルプロパティのすべての子プロパティを列挙できます。例えば、label="work" であるすべての emailAddresses などです。成功時には、コレクションは(要素が存在する場合)最初の要素の前の位置にリセットされます。データのクエリを開始するには Next を呼び出します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IContactProperties "{70DD27DD-5CBD-46E8-BEF0-23B6B346288F}"
#usecom global IContactProperties IID_IContactProperties "{}"
#comfunc global IContactProperties_GetString              3 wstr,int,var,int,var
#comfunc global IContactProperties_GetDate                4 wstr,int,var
#comfunc global IContactProperties_GetBinary              5 wstr,int,var,int,var,sptr
#comfunc global IContactProperties_GetLabels              6 wstr,int,var,int,var
#comfunc global IContactProperties_SetString              7 wstr,int,wstr
#comfunc global IContactProperties_SetDate                8 wstr,int,int
#comfunc global IContactProperties_SetBinary              9 wstr,int,wstr,sptr
#comfunc global IContactProperties_SetLabels              10 wstr,int,int,var
#comfunc global IContactProperties_CreateArrayNode        11 wstr,int,int,var,int,var
#comfunc global IContactProperties_DeleteProperty         12 wstr,int
#comfunc global IContactProperties_DeleteArrayNode        13 wstr,int
#comfunc global IContactProperties_DeleteLabels           14 wstr,int
#comfunc global IContactProperties_GetPropertyCollection  15 sptr,int,wstr,int,var,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IContactProperties "{70DD27DD-5CBD-46E8-BEF0-23B6B346288F}"
#usecom global IContactProperties IID_IContactProperties "{}"
#comfunc global IContactProperties_GetString              3 wstr,int,sptr,int,sptr
#comfunc global IContactProperties_GetDate                4 wstr,int,sptr
#comfunc global IContactProperties_GetBinary              5 wstr,int,sptr,int,sptr,sptr
#comfunc global IContactProperties_GetLabels              6 wstr,int,sptr,int,sptr
#comfunc global IContactProperties_SetString              7 wstr,int,wstr
#comfunc global IContactProperties_SetDate                8 wstr,int,int
#comfunc global IContactProperties_SetBinary              9 wstr,int,wstr,sptr
#comfunc global IContactProperties_SetLabels              10 wstr,int,int,sptr
#comfunc global IContactProperties_CreateArrayNode        11 wstr,int,int,sptr,int,sptr
#comfunc global IContactProperties_DeleteProperty         12 wstr,int
#comfunc global IContactProperties_DeleteArrayNode        13 wstr,int
#comfunc global IContactProperties_DeleteLabels           14 wstr,int
#comfunc global IContactProperties_GetPropertyCollection  15 sptr,int,wstr,int,sptr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。