IMAPIProp::CopyTo
適用対象: Outlook 2013 | Outlook 2016
特に除外されたプロパティを除くすべてのプロパティをコピーまたは移動します。
HRESULT CopyTo(
ULONG ciidExclude,
LPCIID rgiidExclude,
LPSPropTagArray lpExcludeProps,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
LPCIID lpInterface,
LPVOID lpDestObj,
ULONG ulFlags,
LPSPropProblemArray FAR * lppProblems
);
パラメーター
ciidExclude
[in]プロパティのコピーまたは移動時に除外するインターフェイスの数。
rgiidExclude
[in]補足情報をコピーまたはコピー先オブジェクトに移動するときに使用しないインターフェイスを指定するインターフェイス識別子 (IID) の配列。
lpExcludeProps
[in]コピーまたは移動操作から除外する必要があるプロパティ タグを識別するプロパティ タグ配列へのポインター。 lpExcludeProps パラメーターに null を渡すと、オブジェクトのすべてのプロパティをコピーまたは移動する必要があることを示します。 CopyTo は、lpExcludeProps が指す SPropProblemArray 構造体の cValues メンバーが 0 に設定されている場合に、MAPI_E_INVALID_PARAMETERを返します。
ulUIParam
[in]進行状況インジケーターの親ウィンドウへのハンドル。
lpProgress
[in]進行状況インジケーターの実装へのポインター。 lpProgress パラメーターに null が渡された場合、MAPI は進行状況の実装を提供します。 lpProgress パラメーターは、ulFlags パラメーターに MAPI_DIALOG フラグが設定されていない限り無視されます。
lpInterface
[in] lpDestObj パラメーターが指すオブジェクトへのアクセスに使用するインターフェイスを表すインターフェイス識別子 (IID) へのポインター。 lpInterface パラメーターは null にすることはできません。
lpDestObj
[in]コピーまたは移動されたプロパティを受け取るオブジェクトへのポインター。
ulFlags
[in]コピーまたは移動操作を制御するフラグのビットマスク。 次のフラグを設定できます。
MAPI_DECLINE_OK
CopyTo が IMAPISupport::D oCopyTo メソッドを呼び出してコピーまたは移動操作を処理する場合は、代わりにエラー値MAPI_E_DECLINE_COPYを使用して直ちにを返す必要があります。 MAPI_DECLINE_OK フラグは、再帰を制限するために MAPI によって設定されます。 クライアントはこのフラグを設定しません。
MAPI_DIALOG
進行状況インジケーターを表示します。
MAPI_MOVE
CopyTo では、コピー 操作ではなく移動操作を実行する必要があります。 このフラグが設定されていない場合、 CopyTo はコピー操作を実行します。
MAPI_NOREPLACE
コピー先オブジェクト内の既存のプロパティを上書きしないでください。 このフラグが設定されていない場合、 CopyTo は既存のプロパティを上書きします。
lppProblems
[in, out]入力時に、 SPropProblemArray 構造体へのポインターへのポインター。それ以外の場合は null。エラー情報の必要がないことを示します。 lppProblems が入力の有効なポインターである場合、CopyTo は 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 構造体では次の値を返すことができますが、CopyTo の戻り値としては返されません。 次のエラーは、1 つのプロパティに適用されます。
MAPI_E_BAD_CHARWIDTH
MAPI_UNICODE フラグが設定され、 CopyTo で Unicode がサポートされていないか、MAPI_UNICODEが設定されておらず、 CopyTo が Unicode のみをサポートしています。
MAPI_E_COMPUTED
プロパティは読み取り専用プロパティであり、変換先オブジェクトの所有者によって計算されるため、呼び出し元によって変更できません。 このエラーは重大ではありません。呼び出し元は、コピー操作を続行できるようにする必要があります。
MAPI_E_INVALID_TYPE
プロパティの種類が無効です。
MAPI_E_UNEXPECTED_TYPE
プロパティ型は、呼び出し元が予期する型ではありません。
注釈
既定では、 IMAPIProp::CopyTo メソッドは、現在のオブジェクトのすべてのプロパティをコピー先オブジェクトにコピーまたは移動します。 CopyTo は、オブジェクトのコピーまたは移動を正確に行う必要がある場合に使用され、そのプロパティのすべてまたは大部分はそのままです。
ソース オブジェクト内のサブオブジェクトはすべて自動的に操作に含まれ、コピーまたは全体の移動が行われます。 既定では、コピー先オブジェクトのプロパティのうち、ソース オブジェクトのプロパティと一致するプロパティは 、CopyTo によって上書きされます。 コピーまたは移動されたプロパティのいずれかがコピー先オブジェクトに既に存在する場合、 ulFlags パラメーターに MAPI_NOREPLACE フラグが設定されていない限り、既存のプロパティは新しいプロパティによって上書きされます。 上書きされないコピー先オブジェクト内の既存の情報は、そのまま残ります。
実装に関するメモ
CopyTo の完全な実装を提供することも、MAPI がサポート オブジェクトで提供する実装に依存することもできます。 MAPI 実装を使用する場合は、 IMAPISupport::D oCopyTo を呼び出します。 ただし、 DoCopyTo に委任処理を実行し、MAPI_DECLINE_OK フラグが渡された場合は、サポート呼び出しを避け、代わりにMAPI_E_DECLINE_COPYを返します。 MAPI は、このフラグを使用してを呼び出して、フォルダーのコピー時に発生する可能性のある再帰を回避します。
コピー操作は長い場合があるため、進行状況インジケーターを表示する必要があります。 lpProgress パラメーターで渡される IMAPIProgress 実装がある場合は、使用します。 lpProgress がnull の場合は、IMAPISupport::D oProgressDialog メソッドを呼び出して MAPI 実装を使用します。
変換先オブジェクトで既知の読み取り専用プロパティを設定しないでください。代わりにMAPI_E_NO_ACCESSを返します。
ソース オブジェクトと変換先オブジェクトでは、同じインターフェイスを使用する必要があります。 lpInterface が設定されていない場合は、MAPI_E_INVALID_PARAMETERを返します。
既知のすべてのインターフェイスが除外されている場合は、MAPI_E_INTERFACE_NOT_SUPPORTEDを返します。
呼び出し側への注意
MAPI_DECLINE_OK フラグは設定しないでください。MAPI は、メッセージ ストア プロバイダー CopyTo 実装の呼び出しでそれを使用します。
コピー操作と移動操作には時間がかかる場合があるため、MAPI_DIALOG フラグを設定して進行状況インジケーターの表示を要求する必要があります。 lpProgress パラメーターは、IMAPIProgress の実装 (ある場合) または null に設定できます。 lpProgress がnull の場合、CopyTo は MAPI が提供する既定の進行状況インジケーターを使用します。
MAPI_DIALOG フラグを設定しないことで、進行状況インジケーターの表示を抑制できます。 CopyTo は ulUIParam パラメーターと lpProgress パラメーターを 無視し、インジケーターを表示しません。
CopyTo では、グローバル エラーと個々のエラー、または 1 つ以上のプロパティで発生したエラーを報告できます。 これらの個々のエラーは 、SPropProblemArray 構造体に 配置されます。 プロパティの問題の配列構造パラメーターに対して有効なポインターではなく null を渡すことで、プロパティ レベルでのエラー報告を抑制できます。
エラーに関する情報を受け取る場合は、lppProblems パラメーターに有効な SPropProblemArray 構造体ポインター を 渡します。 CopyTo がS_OKを返すと、構造体内の個々のプロパティで発生する可能性のあるエラーをチェックします。 CopyTo がエラーを返すと、SPropProblemArray 構造体に情報は返されません。 代わりに、 IMAPIProp::GetLastError を呼び出して、詳細なエラー情報を取得します。
CopyTo がS_OKを返す場合は、MAPIFreeBuffer 関数を呼び出して、返された SPropProblemArray 構造体を解放します。
ソース オブジェクトの種類に固有のプロパティをコピーする場合は、コピー先オブジェクトが同じ型であることを確認する必要があります。 CopyTo では、通常、ある種類のオブジェクトに属するプロパティを別の種類のオブジェクトに関連付けないようにすることはできません。 コピー先オブジェクトに適したプロパティをコピーするのはユーザーの責任です。 たとえば、メッセージ のプロパティをアドレス帳コンテナーにコピーしないでください。
同じ型のオブジェクト間でコピーするようにするには、オブジェクト ポインターを比較するか、IUnknown::QueryInterface を呼び出すことによって、ソース オブジェクトとコピー先オブジェクトが同じ型であることをチェックします。 lpInterface が指すインターフェイス識別子を、ソース オブジェクトの標準インターフェイスに設定します。 また、オブジェクトの種類または PR_OBJECT_TYPE (PidTagObjectType) プロパティが 2 つのオブジェクトで同じであることを確認してください。 たとえば、メッセージからコピーする場合は、 lpInterface を IID_IMessage に設定し、両方のオブジェクトの PR_OBJECT_TYPE をMAPI_MESSAGEします。
lpDestObj パラメーターに無効なポインターが渡された場合、結果は予測できません。
CopyTo 呼び出しでプロパティを除外すると便利です。 たとえば、一部のオブジェクトには、メッセージ配信の日時など、オブジェクトの 1 つのインスタンスに固有のプロパティがあります。 メッセージを別のフォルダーにコピーするときにメッセージの配信時間をコピーしないようにするには、プロパティ タグ exclude 配列 に PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) を指定します。 メッセージの受信者リストを除外するには、 PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) プロパティを exclude 配列に追加します。 メッセージの添付ファイルを除外するには、 PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) プロパティを配列に追加します。
同様に、PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) または PR_CONTAINER_CONTENTS (PidTagContainerContents) をプロパティ タグ除外配列に含めることで、フォルダーまたはアドレス帳コンテナーの階層またはコンテンツ テーブルのコピーまたは移動を防ぎます。
コピーまたは移動操作からプロパティを除外するには、 lpExcludeProps パラメーターにプロパティ タグを含めます。 PROP_TAG マクロの結果を渡して、プロパティ タグ配列内の特定の識別子からプロパティ タグを構築すると、その識別子を持つすべてのプロパティが除外されます。 たとえば、プロパティ タグ配列の次のエントリを使用すると、型に関係なく、0x8002の識別子を持つすべてのプロパティが除外されます。
PROP_TAG(PT_LONG, 0x8002)
PR_NULL (PidTagNull) プロパティ タグを lpExcludeProps 配列に含めることはできません。
インターフェイスを除外するための CopyTo 機能の有用性は、おそらくプロパティを除外する有用性ほど明白ではありません。 プロパティのグループに関する知識がないオブジェクトにコピーする場合は、インターフェイスを除外できます。 たとえば、フォルダーから添付ファイルにプロパティをコピーする場合、添付ファイルで使用できるプロパティは、 IMAPIProp 実装で使用できる汎用プロパティのみです。 コピー操作から IMAPIFolder を除外すると、添付ファイルはより具体的なフォルダー プロパティを受け取りません。
rgiidExclude パラメーターを使用してインターフェイスを除外すると、そのインターフェイスから派生したすべてのインターフェイスも除外されます。 たとえば、 IMAPIContainer を 除外すると、プロバイダーの種類に応じてフォルダーまたはアドレス帳コンテナーが除外されます。 非常に多くのインターフェイスがそれらから派生するため、 IMAPIProp または IUnknown を除外しないでください。
lppProblems パラメーターの SPropProblemArray 構造体で返されるMAPI_E_COMPUTEDエラーを無視します。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| File.cpp |
LoadFromMSG |
MFCMAPI では、 IMAPIProp::CopyTo メソッドを使用して、.msg ファイルから IMAPIMessageSite オブジェクトにプロパティをコピーします。 |
| FolderDlg.cpp |
CFolderDlg::HandlePaste |
MFCMAPI では、 IMAPIProp::CopyTo メソッドを使用して、貼り付け操作中にソース メッセージからターゲット メッセージにプロパティをコピーします。 |
関連項目
IMAPISupport::DoProgressDialog
PidTagContainerContents 標準プロパティ
PidTagContainerHierarchy 標準プロパティ
PidTagMessageAttachments 標準プロパティ
PidTagMessageDeliveryTime 標準プロパティ