IMAPIProp::GetIDsFromNames
適用対象: Outlook 2013 | Outlook 2016
1 つ以上のプロパティ名に対応するプロパティ識別子を提供します。
HRESULT GetIDsFromNames(
ULONG cPropNames,
LPMAPINAMEID FAR * lppPropNames,
ULONG ulFlags,
LPSPropTagArray FAR * lppPropTags
);
パラメーター
cPropNames
[in] lppPropNames パラメーターによって指されるプロパティ名の数。 lppPropNames が NULL の場合、cPropNames パラメーターは 0 である必要があります。
lppPropNames
[in]プロパティ名の配列 (NULL) へのポインター。 NULL 要求を渡すと、オブジェクトが情報を持つすべてのプロパティ セット内のすべてのプロパティ名のプロパティ識別子が要求されます。 MAPI_CREATE フラグが ulFlags パラメーターに設定されている場合、lppPropNames パラメーターは NULL にすることはできません。
ulFlags
[in]プロパティ識別子を返す方法を示すフラグのビットマスク。 次のフラグを設定できます。
MAPI_CREATE
まだ割り当てられていない場合は、 lppPropNames が指すプロパティ名配列に含まれる 1 つ以上の名前にプロパティ識別子を割り当てます。 このフラグは、名前と識別子のマッピング テーブルに識別子を内部的に登録します。
lppPropTags
[out]既存または新しく割り当てられたプロパティ識別子を含むプロパティ タグの配列へのポインターへのポインター。 この配列のプロパティ タグのプロパティ型は 、PT_UNSPECIFIEDに設定されます。
戻り値
S_OK
指定したプロパティ名の識別子が正常に返されました。
MAPI_E_NO_SUPPORT
オブジェクトは名前付きプロパティをサポートしていません。
MAPI_E_NOT_ENOUGH_MEMORY
識別子を取得するために使用できるメモリが不足していました。
MAPI_E_TOO_BIG
返されるプロパティ タグが多すぎるため、操作を実行できません。
MAPI_W_ERRORS_RETURNED
呼び出しは全体的に成功しましたが、1 つ以上のプロパティ識別子を返できませんでした。 使用できない各プロパティの対応するプロパティの種類は 、PT_ERROR に設定され、その識別子は 0 に設定されます。 この警告が返されたら、呼び出しを成功として処理します。 この警告をテストするには、 HR_FAILED マクロを使用します。 エラー処理のマクロの使用に関するページを参照してください。
注釈
IMAPIProp::GetIDsFromNames メソッドは、1 つ以上の名前付きプロパティのプロパティ識別子を保持するプロパティ タグの配列を取得します。 IMAPIProp::GetIDsFromNames を呼び出して、次の操作を行うことができます。
新しい名前の識別子を作成します。
特定の名前の識別子を取得します。
オブジェクトのマッピングに含まれるすべての名前付きプロパティの識別子を取得します。
名前付きプロパティは、通常、フォルダーとメッセージのメッセージ ストア プロバイダーによって使用されます。 メッセージング ユーザーやプロファイル セクションなどの他のオブジェクトは、プロパティ識別子への名前の関連付けをサポートせず、 GetIDsFromNames からMAPI_E_NO_SUPPORTを返す場合があります。
特定の名前の識別子を返すエラーが発生した場合、 GetIDsFromNames はMAPI_W_ERRORS_RETURNEDを返し、名前に対応するプロパティ タグ配列エントリのプロパティ型を PT_ERROR に設定し、識別子を 0 に設定します。
名前から識別子へのマッピングは、オブジェクトの PR_MAPPING_SIGNATURE (PidTagMappingSignature) プロパティによって表されます。 PR_MAPPING_SIGNATURE には、オブジェクトを担当するサービス プロバイダーを示す MAPIUID 構造体が含まれています。 PR_MAPPING_SIGNATURE プロパティが 2 つのオブジェクトで同じ場合は、これらのオブジェクトが同じ名前から識別子へのマッピングを使用していると仮定します。
実装に関するメモ
lppPropNames パラメーターが指すプロパティ タグ配列で渡す識別子は、0xFFFE範囲の0x8000内にある必要があります。 この配列のエントリは、 lppPropNames が指すプロパティ名配列で渡される名前と同じ順序にする必要があります。
コンテナーで名前付きプロパティをサポートしている場合は、コンテナー内のすべてのオブジェクトに対して同じ名前から識別子へのマッピングを使用します (つまり、メッセージ ストア内の各フォルダーまたはフォルダー内の各メッセージに対して異なるマッピングを使用しないでください)。
呼び出し側への注意
lppPropTags が指すプロパティ タグ配列の返された識別子のプロパティ型はPT_UNSPECIFIEDに設定されているため、正確な型を取得するには IMAPIProp::SetProps メソッドを呼び出す必要があります。
名前付きプロパティを使用してオブジェクトを移動またはコピーする場合、ソース オブジェクトとコピー先オブジェクトのマッピングシグネチャが 、PR_MAPPING_SIGNATURE プロパティの値によって示されるように異なる場合は、これらの操作中に名前を保持する必要があります。 プロパティ名を保持するには、対応するプロパティ識別子を、コピー先オブジェクトの名前から識別子へのマッピングと一致するように調整します。
一部のオブジェクトには、名前を付けることができるプロパティ識別子の数に関する制限があります。 GetIDsFromNames の呼び出しによってこの制限を超えた場合、メソッドはMAPI_E_TOO_BIGを返します。 この場合は、識別子でクエリを実行します。
詳細については、「 MAPI の名前付きプロパティ」を参照してください。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| SingleMAPIPropListCtrl.cpp |
CSingleMAPIPropListCtrl::FindAllNamedPropsUsed |
MFCMAPI では、 IMAPIProp::GetIDsFromNames メソッドを使用して、マップされているすべての名前付きプロパティのプロパティ タグを取得します。 |