MAPI 名前付きプロパティ
適用対象: Outlook 2013 | Outlook 2016
MAPI には、プロパティに名前を割り当てる機能、これらの名前を一意の識別子にマッピングする機能、およびこのマッピングを永続的にする機能が用意されています。 識別子マッピングに対する永続的な命名により、プロパティ名がセッション間で有効性を保つことができます。
名前付きプロパティを定義するために、クライアントまたはサービス プロバイダーは名前を構成し、MAPINAMEID 構造体に格納します。 名前は 128 ビットのグローバル一意識別子 (GUID) で構成され、Unicode 文字列または 32 ビットの数値で構成されているため、名前付きプロパティの作成者は重複を恐れずに意味のある名前を作成できます。 名前は一意に定まり、識別子の値に関係なく使用できます。
名前付きプロパティをサポートするには、サービス プロバイダーは、IMAPIProp::GetIDsFromNames と IMAPIProp::GetNamesFromIDs の 2 つのメソッドを実装して、名前と識別子の間で翻訳し、そのIMAPIProp::GetPropsIMAPIProp::SetProps メソッドが名前付きプロパティの範囲の識別子を持つプロパティを取得および変更できるようにします。 名前付きプロパティ識別子の範囲は、0x8000と0xFFFEの間です。
IMAPIProp インターフェイスを実装する任意のオブジェクトは、名前付きプロパティをサポートできます。 このサポートを提供するには、任意のメッセージ タイプの作成に使用できる他のプロバイダーからのエントリをコンテナーおよびメッセージ ストア プロバイダーにコピーできるようにするアドレス帳プロバイダーが必要です。 これは、他のすべてのサービス プロバイダーのためのオプションです。 名前付きプロパティをサポートしていないプロバイダーは、GetIDsFromNamesとGetNamesFromIDs メソッドから MAPI_E_NO_SUPPORT を返し、0x8000 以上の識別子を持つプロパティの設定を拒否し、SPropProblemarrayで MAPI_E_UNEXPECTED を返します。
プロパティの名前を作成することは、クライアントが既存のメッセージ クラスまたはカスタム メッセージ クラスの新しいプロパティを定義する 1 つの方法です。 サービス プロバイダーは、名前付きプロパティを使用して、メッセージング システムの固有の機能を公開できます。 名前付きプロパティのもう 1 つの用途は、0x8000 以下の識別子を持つプロパティを参照する別の方法を提供することです。
たとえば、オブジェクトのすべての名前付きプロパティの名前を取得するために、クライアントは次のコードに似たコードを使用できます。
LPSPropTagArray FAR * lppPropTags = NULL;
LPGUID lpPropSetGuid = NULL;
ULONG FAR * lpcPropNames;
LPMAPINAMEID FAR * FAR * lpppPropNames;
lpMAPIProp->GetNamesFromIDs (lppPropTags,
lpPropSetGuid,
0,
lpcPropNames,
lpppPropNames);
PS_PUBLIC_STRINGS プロパティ セットからすべての名前を要求するために、クライアントはプロパティ セット パラメーターの NULL 値を次のように PS_PUBLIC_STRINGS に置き換えます:
LPSPropTagArray FAR * lppPropTags = NULL;
LPGUID lpPropSetGuid = &PS_PUBLIC_STRINGS;
ULONG FAR * lpcPropNames;
LPMAPINAMEID FAR * FAR * lpppPropNames;
lpMAPIProp->GetNamesFromIDs (lppPropTags,
lpPropSetGuid,
0,
lpcPropNames,
lpppPropNames);