IMAPIProp::GetNamesFromIDs
適用対象: Outlook 2013 | Outlook 2016
1 つ以上のプロパティ識別子に対応するプロパティ名を提供します。
HRESULT GetNamesFromIDs(
LPSPropTagArray FAR * lppPropTags,
LPGUID lpPropSetGuid,
ULONG ulFlags,
ULONG FAR * lpcPropNames,
LPMAPINAMEID FAR * FAR * lpppPropNames
);
パラメーター
lppPropTags
[in, out]入力時に、プロパティ タグの配列を含む SPropTagArray 構造体へのポインター。それ以外の場合は NULL。すべての名前を返す必要があることを示します。 プロパティ タグ配列 の cValues メンバーを 0 にすることはできません。 lppPropTags が入力の有効なポインターである場合、GetNamesFromIDs は配列に含まれる各プロパティ識別子の名前を返します。
lpPropSetGuid
[in]プロパティ セットを識別する GUID ( GUID 構造体) へのポインター。 lpPropSetGuid パラメーターは、有効なプロパティ セットを指すか、NULL にすることができます。
ulFlags
[in]返される名前の種類を示すフラグのビットマスク。 次のフラグを使用できます (両方のフラグが設定されている場合、名前は返されません)。
MAPI_NO_IDS
Unicode 文字列として格納されている名前のみを返す要求。
MAPI_NO_STRINGS
数値識別子として格納されている名前のみを返す要求。
lpcPropNames
[out] lppPropNames パラメーターによって指される配列内のプロパティ名ポインターの数へのポインター。
lpppPropNames
[out]プロパティ名を含む MAPINAMEID 構造体へのポインターの配列へのポインター。
戻り値
S_OK
プロパティ名が正常に返されました。
MAPI_E_NO_SUPPORT
オブジェクトは名前付きプロパティをサポートしていません。
MAPI_W_ERRORS_RETURNED
呼び出しは全体的に成功しましたが、1 つ以上のプロパティの名前を返できませんでした。 失敗したプロパティのプロパティ タグには、プロパティの種類 がPT_ERROR。 この警告が返されたら、呼び出しは成功として処理する必要があります。 この警告をテストするには、 HR_FAILED マクロを使用します。 詳細については、「 エラー処理にマクロを使用する」を参照してください。
MAPI_E_INVALID_PARAMETER
lppPropTags が指すプロパティ タグ配列内の 1 つ以上のエントリの cValues メンバーは、0 に設定されます。
注釈
ほとんどのプロパティへのアクセスはプロパティ識別子によって行われますが、一部のプロパティには名前でアクセスできます。 IMAPIProp::GetNamesFromIDs メソッドを呼び出して、次の操作を行うことができます。
特定のプロパティ セット内の特定のプロパティ識別子の名前を取得します。
任意のプロパティ セット内の特定のプロパティ識別子の名前を取得します。
オブジェクトのマッピングに含まれるすべての名前付きプロパティの名前を取得します。
lppPropTags が 1 つ以上のプロパティ識別子を持つ有効なプロパティ タグ配列を指し、lpPropSetGuid が有効なプロパティ セットを指している場合、GetNamesFromIDs はプロパティ セットとプロパティ型を無視し、指定された識別子にマップされるすべての名前を返します。
lppPropTags が 1 つ以上のプロパティ識別子を持つ有効なプロパティ タグ配列を指し示し、lpPropSetGuid が NULL の場合、GetNamesFromIDs は、指定された識別子にマップされるすべての名前を返します。
指定した識別子に名前がない場合、 GetNamesFromIDs は lpppPropNames で返される構造体内のその識別子の場所で NULL を返し、MAPI_W_ERRORS_RETURNEDも返します。
lpPropSetGuid と lppPropTags の両方が NULL の場合、GetNamesFromIDs は新しいプロパティ タグ配列を割り当て、オブジェクトのすべての名前付きプロパティのすべての名前を返します。
要求されたプロパティ セットにプロパティがない場合、またはすべてのプロパティがフラグによって除外された型である場合、 GetNamesFromIDs は次の処理を行います。
S_OKを返します。
cValues メンバーを 0 に設定して、新しい SPropTagArray 構造体を割り当てます。
lpcPropNames の内容を 0 に設定します。
lpppPropNames の内容を NULL に設定します。
実装に関するメモ
lpPropSetGuid が有効なプロパティ セットをポイントし、lppPropTags が NULL の場合、結果は未定義です。 次のいずれかの方法を使用できます。
プロパティ セットを無視し、プロパティ タグ配列内の識別子の名前を返します。
指定したプロパティ セットに属するプロパティ タグ配列内の識別子の名前のみを返します。
呼び出しに失敗し、MAPI_E_INVALID_PARAMETERを返します。
呼び出し側への注意
オブジェクトのすべての名前付きプロパティを取得するには、まずオブジェクトの IMAPIProp::GetPropList メソッドを呼び出し、0x8000範囲を超える返された識別子を GetNamesFromIDs に渡す必要があります。
有効なプロパティ セットを渡したが、有効なプロパティ タグ配列を渡さない場合は、予期しない結果に備えて準備してください。 GetNamesFromID の一部の実装では、プロパティ セットが無視され、プロパティ タグ配列内の識別子の名前が返されます。 一部の実装では、MAPI_E_INVALID_PARAMETERが返されます。 その他の実装では、プロパティ セット内のすべてのプロパティの識別子の名前が返されます。 プロパティ セットがPS_PUBLIC_STRINGSされている場合、 GetNamesFromIDs は作成されたすべての名前を返すことができます。 サービス プロバイダーがパブリック文字列に関連付けられている識別子の下にプロパティを格納するかどうかは重要ではありません。
プロパティ名が完成したら、lpcPropNames パラメーターの内容をチェックして、名前が返されたかどうかを判断します。 その場合は、 MAPIFreeBuffer 関数を呼び出して、成功した結果が返されたときに lppPropTags と lpppPropNames が指すメモリを解放します。 MAPIFreeBuffer の呼び出しは、パラメーターごとに 1 回で十分です。ポインターの配列を走査し、各 MAPINAMEID 構造体を個別に解放する必要はありません。
名前付きプロパティの詳細については、「 MAPI の名前付きプロパティ」を参照してください。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| SingleMAPIPropListCtrl.cpp |
CSingleMAPIPropListCtrl::FindAllNamedProps |
MFCMAPI では、 IMAPIProp::GetNamesFromIDs メソッドを使用して、以前にマップされた名前付きプロパティを検索します。 |