IMAPIProp::CopyProps
適用対象: Outlook 2013 | Outlook 2016
選択したプロパティをコピーまたは移動します。
HRESULT CopyProps(
LPSPropTagArray lpIncludeProps,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
LPCIID lpInterface,
LPVOID lpDestObj,
ULONG ulFlags,
LPSPropProblemArray FAR * lppProblems
);
パラメーター
lpIncludeProps
[in]コピーまたは移動するプロパティを指定するプロパティ タグ配列へのポインター。 PR_NULL (PidTagNull) を配列に含めることはできません。 lpIncludeProps パラメーターをnull にすることはできません。
ulUIParam
[in]進行状況インジケーターの親ウィンドウへのハンドル。
lpProgress
[in]進行状況インジケーターの実装へのポインター。 lpProgress パラメーターに null が渡された場合、MAPI 実装を使用して進行状況インジケーターが表示されます。 lpProgress パラメーターは、ulFlags パラメーターに MAPI_DIALOG フラグが設定されていない限り無視されます。
lpInterface
[in] lpDestObj パラメーターが指すオブジェクトへのアクセスに使用する必要があるインターフェイスを表すインターフェイス識別子 (IID) へのポインター。 lpInterface パラメーターは null にすることはできません。
lpDestObj
[in]コピーまたは移動されたプロパティを受け取るオブジェクトへのポインター。
ulFlags
[in]コピーまたは移動操作を制御するフラグのビットマスク。 次のフラグを設定できます。
MAPI_DECLINE_OK
CopyProps がIMAPISupport::D oCopyProps メソッドを呼び出してコピー操作または移動操作を処理する場合は、代わりにエラー値をMAPI_E_DECLINE_COPYで直ちに返す必要があります。 MAPI_DECLINE_OK フラグは、再帰を制限するために MAPI によって設定されます。 クライアントはこのフラグを設定しません。
MAPI_DIALOG
進行状況インジケーターを表示します。
MAPI_MOVE
CopyProps では、 コピー操作ではなく移動操作を実行する必要があります。 このフラグが設定されていない場合、 CopyProps は コピー操作を実行します。
MAPI_NOREPLACE
コピー先オブジェクト内の既存のプロパティを上書きしないでください。 このフラグが設定されていない場合、 CopyProps は既存の プロパティを上書きします。
lppProblems
[in, out]入力時に、 SPropProblemArray 構造体へのポインターへのポインター。それ以外の場合は null。エラー情報の必要がないことを示します。 lppProblems が入力の有効なポインターである場合、CopyProps は 1 つ以上のプロパティをコピーするときのエラーに関する詳細情報を返します。
戻り値
S_OK
プロパティが正常にコピーまたは移動されました。
MAPI_E_COLLISION
PR_DISPLAY_NAME (PidTagDisplayName) プロパティによって定義された同じ表示名のサブオブジェクトが、コピー先オブジェクトに既に存在するため、サブオブジェクトをコピーできません。
MAPI_E_DECLINE_COPY
サービス プロバイダーは、コピー操作を実装しません。
MAPI_E_FOLDER_CYCLE
コピー操作または移動操作を直接または間接的に実行するソース オブジェクトには、コピー先オブジェクトが含まれています。 この条件が検出される前に重要な作業が実行された可能性があるため、ソース オブジェクトと変換先オブジェクトが部分的に変更される可能性があります。
MAPI_E_INTERFACE_NOT_SUPPORTED
lpInterface パラメーターで識別されるインターフェイスは、変換先オブジェクトではサポートされていません。
MAPI_E_NO_ACCESS
呼び出し元に十分なアクセス許可が与えられなかったオブジェクトへのアクセスが試行されました。 このエラーは、変換先オブジェクトがソース オブジェクトと同じ場合に返されます。
SPropProblemArray 構造体では次の値を返すことができますが、CopyProps の戻り値としては返されません。 これらのエラーは、1 つのプロパティに適用されます。
MAPI_E_BAD_CHARWIDTH
MAPI_UNICODE フラグが設定され、 CopyProps で Unicode がサポートされていないか、MAPI_UNICODEが設定されておらず、 CopyProps が Unicode のみをサポートしています。
MAPI_E_COMPUTED
プロパティは読み取り専用プロパティであり、変換先オブジェクトの所有者によって計算されるため、呼び出し元によって変更できません。 このエラーは重大ではありません。呼び出し元は、コピー操作を続行できるようにする必要があります。
MAPI_E_INVALID_TYPE
プロパティの種類が無効です。
MAPI_E_UNEXPECTED_TYPE
プロパティ型は、呼び出し元が予期する型ではありません。
注釈
IMAPIProp::CopyProps メソッドは、選択したプロパティを現在のオブジェクトからコピー先オブジェクトにコピーまたは移動します。 CopyProps は、主にメッセージへの返信と転送に使用されます。元のメッセージのプロパティの一部のみが、返信または転送されたコピーと共に移動します。
ソース オブジェクト内のすべてのサブオブジェクトは、 SPropTagArray 構造体によって示されるプロパティの使用に関係なく、操作に自動的に含まれ、全体でコピーまたは移動されます。 既定では、コピー元オブジェクトのプロパティと一致するコピー先オブジェクト内のプロパティは 、CopyProps によって上書きされます。 コピーまたは移動されたプロパティのいずれかがコピー先オブジェクトに既に存在する場合、 ulFlags パラメーターに MAPI_NOREPLACE フラグが設定されていない限り、既存のプロパティは新しいプロパティによって上書きされます。 上書きされないコピー先オブジェクト内の既存の情報は、そのまま残ります。
実装に関するメモ
CopyProps の完全な実装を提供することも、MAPI がそのサポート オブジェクトで提供する実装に依存することもできます。 MAPI 実装を使用する場合は、 IMAPISupport::D oCopyProps メソッドを 呼び出します。 ただし、 DoCopyProps に委任処理を行い、MAPI_DECLINE_OK フラグを渡した場合は、サポート呼び出しを避け、代わりにMAPI_E_DECLINE_COPYを返します。 このフラグを MAPI で呼び出して、フォルダーをコピーするときに発生する可能性のある再帰を回避します。
コピー操作は長い場合があるため、進行状況インジケーターを表示する必要があります。 lpProgress パラメーターで渡される IMAPIProgress 実装 (存在する場合) を使用します。 lpProgress がnull の場合は、IMAPISupport::D oProgressDialog メソッドを呼び出して MAPI 実装を使用します。
呼び出し側への注意
MAPI_DECLINE_OK フラグは設定しないでください。これは、メッセージ ストア プロバイダー CopyProps 実装の呼び出しで MAPI によって使用されます。
コピー操作と移動操作には時間がかかる可能性があるため、MAPI_DIALOG フラグを設定して進行状況インジケーターの表示を要求することをお勧めしています。 lpProgress パラメーターは、IMAPIProgress の実装 (ある場合) または null に設定できます。 lpProgress がnull の場合、CopyProps は MAPI によって提供される既定の進行状況インジケーターを使用します。
MAPI_DIALOG フラグを設定しないことで、進行状況インジケーターの表示を抑制できます。 CopyProps は ulUIParam パラメーターと lpProgress パラメーターを無視し、インジケーターの表示を回避します。
CopyProps では、 グローバル エラーと個々のエラー、または 1 つ以上のプロパティで発生したエラーを報告できます。 これらの個々のエラーは 、SPropProblemArray 構造体に 配置されます。 プロパティの問題の配列構造パラメーターに対して有効なポインターではなく null を渡すことで、プロパティ レベルでのエラー報告を抑制できます。
エラーに関する情報を受け取る場合は、lppProblems パラメーターに有効な SPropProblemArray 構造体ポインター を 渡します。 CopyProps がS_OKを返すと、構造体内の個々のプロパティで発生する可能性のあるエラーがチェックされます。 CopyProps がエラーを返すと、SPropProblemArray 構造体に情報は返されません。 代わりに、 IMAPIProp::GetLastError メソッドを呼び出して、詳細なエラー情報を取得します。
CopyProps がS_OKを返す場合は、MAPIFreeBuffer 関数を呼び出して、返された SPropProblemArray 構造体を解放します。
ソース オブジェクトの種類に固有のプロパティをコピーする場合は、コピー先オブジェクトが同じ型であることを確認する必要があります。 CopyProps では、通常、ある種類のオブジェクトに属するプロパティを別の種類のオブジェクトに関連付けないようにすることはできません。 コピー先オブジェクトに適したプロパティをコピーするのはユーザーの責任です。 たとえば、メッセージ のプロパティをアドレス帳コンテナーにコピーしないでください。
同じ型のオブジェクト間でコピーすることを確認するには、オブジェクト ポインターを比較するか、IUnknown::QueryInterface メソッドを呼び出すことによって、ソース オブジェクトとコピー先オブジェクトが同じ型であることをチェックします。 lpInterface が指すインターフェイス識別子を、ソース オブジェクトの標準インターフェイスに設定します。 また、オブジェクトの種類または PR_OBJECT_TYPE (PidTagObjectType) プロパティが 2 つのオブジェクトで同じであることを確認します。 たとえば、メッセージからコピーする場合は、 lpInterface を IID_IMessage に設定し、両方のオブジェクトの PR_OBJECT_TYPE をMAPI_MESSAGEに設定します。
lpDestObj パラメーターに無効なポインターが渡された場合、結果は予測できません。
メッセージの受信者リストをコピーするには、メッセージの CopyProps メソッドを呼び出し、プロパティ タグ配列に PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) プロパティを含めます。 メッセージの添付ファイルをコピーするには、 PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) プロパティを含めます。
フォルダーまたはアドレス帳コンテナーの階層テーブルまたはコンテンツ テーブルをコピーするには、プロパティ タグ配列に PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) または PR_CONTAINER_CONTENTS (PidTagContainerContents) プロパティを含めます。 フォルダーの関連コンテンツ テーブルを含めるには、配列に PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) プロパティを含めます。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| MAPIFunctions.cpp |
CopyNamedProps |
MFCMAPI では、 IMAPIProp::CopyProps メソッドを使用して、名前付きプロパティを 1 つのメッセージから別のメッセージにコピーします。 |
| SingleMAPIPropListCtrl.cpp |
CSingleMAPIPropListCtrl::OnPasteProperty |
MFCMAPI では、 IMAPIProp::CopyProps メソッドを使用して、別のオブジェクトからコピーされたプロパティを貼り付けます。 |
関連項目
IMAPISupport::DoProgressDialog
PidTagContainerContents 標準プロパティ
PidTagContainerHierarchy 標準プロパティ
PidTagFolderAssociatedContents 標準プロパティ
PidTagMessageAttachments 標準プロパティ