IMAPISupport::DoCopyTo

  • [アーティクル]

適用対象: Outlook 2013 | Outlook 2016

特に除外されたプロパティを除く、1 つのオブジェクトのすべてのプロパティをコピーまたは移動します。

HRESULT DoCopyTo(
  LPCIID lpSrcInterface,
  LPVOID lpSrcObj,
  ULONG ciidExclude,
  LPCIID rgiidExclude,
  LPSPropTagArray lpExcludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpDestInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

パラメーター

lpSrcInterface

[in]コピーまたは移動するプロパティを持つオブジェクトへのアクセスに使用するインターフェイスを表すインターフェイス識別子 (IID) へのポインター。

lpSrcObj

[in]コピーまたは移動するプロパティを持つオブジェクトへのポインター。

ciidExclude

[in]プロパティをコピーまたは移動するときに除外するインターフェイスの数。

rgiidExclude

[in]コピー先オブジェクトに補足情報をコピーまたは移動するときに使用してはならないインターフェイスを示すインターフェイス識別子の配列。

lpExcludeProps

[in]コピーまたは移動操作から除外する必要があるプロパティ タグを識別するプロパティ タグ配列へのポインター。 lpExcludeProps パラメーターで NULL を渡すと、オブジェクトのすべてのプロパティをコピーまたは移動する必要があることを示します。 DoCopyTo は、lpExcludeProps が指す SPropTagArray 構造体の cValues メンバーが 0 に設定されている場合、MAPI_E_INVALID_PARAMETERを返します。

ulUIParam

[in]進行状況インジケーターの親ウィンドウへのハンドル。

lpProgress

[in]進行状況インジケーターの実装へのポインター。 lpProgress パラメーターに NULL が渡された場合、MAPI は進行状況の実装を提供します。 lpProgress パラメーターは、ulFlags パラメーターに MAPI_DIALOG フラグが設定されていない限り無視されます。

lpDestInterface

[in]コピーまたは移動されたプロパティを受け取るためにオブジェクトにアクセスするために使用するインターフェイスを表すインターフェイス識別子へのポインター。

lpDestObj

[in]コピーまたは移動されたプロパティを受け取るオブジェクトへのポインター。

ulFlags

[in]コピーまたは移動操作を制御するフラグのビットマスク。 次のフラグを設定できます。

MAPI_DIALOG

進行状況インジケーターを表示します。

MAPI_MOVE

DoCopyTo では 、コピー操作ではなく移動操作を実行する必要があります。 このフラグが設定されていない場合、 DoCopyTo は コピー操作を実行します。

MAPI_NOREPLACE

コピー先オブジェクト内の既存のプロパティを上書きしないでください。 このフラグが設定されていない場合、 DoCopyTo は既存のプロパティを上書きします。

lppProblems

[out]入力時に、 SPropProblemArray 構造体へのポインターへのポインター。それ以外の場合は、エラー情報の必要がないことを示す NULL。 lppProblems が入力の有効なポインターである場合、DoCopyTo は 1 つ以上のプロパティをコピーするときのエラーに関する詳細情報を返します。

戻り値

S_OK

プロパティが正常にコピーまたは移動されました。

MAPI_E_COLLISION

コピーまたは移動するプロパティは、コピー先オブジェクトに既に存在し、MAPI_NOREPLACE フラグが設定されています。

MAPI_E_FOLDER_CYCLE

ソース オブジェクトには、直接または間接的にターゲット オブジェクトが含まれています。 この条件が検出される前に重要な作業が実行された可能性があるため、ソース オブジェクトと変換先オブジェクトが部分的に変更される可能性があります。

MAPI_E_INTERFACE_NOT_SUPPORTED

lpSrcInterface パラメーターで識別されるインターフェイスは、lpSrcObj が指すオブジェクトではサポートされていません。また、lpDestInterface パラメーターで識別されるインターフェイスは、lpDestObj によって指されるオブジェクトではサポートされていません。

MAPI_E_NO_ACCESS

呼び出し元に十分なアクセス許可が与えられなかったオブジェクトへのアクセスが試行されました。 このエラーは、変換先オブジェクトがソース オブジェクトと同じ場合に返されます。

MAPI_E_INVALID_PARAMETER

lpSrcInterface パラメーターは NULL です。

SPropProblemArray 構造体では次の値を返すことができますが、DoCopyTo の戻り値としては返されません。 これらのエラーは、1 つのプロパティに適用されます。

MAPI_E_BAD_CHARWIDTH

MAPI_UNICODE フラグが設定され、 DoCopyTo で Unicode がサポートされていないか、MAPI_UNICODEが設定されておらず、 DoCopyTo で Unicode のみがサポートされています。

MAPI_E_COMPUTED

プロパティは読み取り専用プロパティであり、変換先オブジェクトの所有者によって計算されるため、呼び出し元によって変更できません。 このエラーは重大ではありません。呼び出し元は、コピー操作を続行できるようにする必要があります。

MAPI_E_INVALID_TYPE

プロパティの種類が無効です。

MAPI_E_UNEXPECTED_TYPE

プロパティ型は、呼び出し元が予期する型ではありません。

注釈

IMAPISupport::D oCopyTo メソッドは、メッセージ ストア プロバイダーサポート オブジェクトに実装されます。 メッセージ ストア プロバイダーは DoCopyTo を 呼び出して、フォルダーとメッセージの IMAPIProp::CopyTo メソッドを実装できます。

既定では、 DoCopyTo は 、あるオブジェクトのすべてのプロパティを別のオブジェクトにコピーまたは移動します。 ソース オブジェクト内のすべてのサブオブジェクトは、操作に自動的に含まれ、全体がコピーまたは移動されます。

コピーまたは移動されたプロパティのいずれかがコピー先オブジェクトに既に存在する場合、 ulFlags パラメーターに MAPI_NOREPLACE フラグが設定されていない限り、既存のプロパティは新しいプロパティによって上書きされます。 上書きされないコピー先オブジェクト内の既存の情報は、そのまま残ります。

呼び出し側への注意

コピーまたは移動操作からプロパティを除外するには、 lpExcludeProps パラメーターにプロパティ タグを含めます。 PROP_TAG マクロを使用してプロパティ タグ配列内の特定の識別子からプロパティ タグを構築した結果を渡すと、その識別子を持つすべてのプロパティが除外されます。 たとえば、プロパティ タグ配列の次のエントリを使用すると、型に関係なく、0x8002の識別子を持つすべてのプロパティが除外されます。

PROP_TAG(PT_LONG, 0x8002)

メッセージを別のフォルダーにコピーするときにメッセージの配信時間をコピーしないようにするには、プロパティ タグ exclude 配列 に PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) を指定します。 メッセージの受信者リストを除外するには、 PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) プロパティを exclude 配列に追加します。 メッセージの添付ファイルを除外するには、 PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) プロパティを配列に追加します。

同様に、フォルダーまたはアドレス帳コンテナーの階層テーブルまたはコンテンツ テーブルのコピーまたは移動を防ぐには、プロパティ タグの exclude 配列 に PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) または PR_CONTAINER_CONTENTS (PidTagContainerContents) を含めます。

lppProblems パラメーターの SPropProblemArray 構造体で返されるMAPI_E_COMPUTEDエラーを無視します。

lpSrcInterface が指すインターフェイス識別子は、通常、lpDestInterface が指すインターフェイス識別子と同じです。

lpDestInterface で許容可能なインターフェイス識別子を渡しても、lpDestObj に無効なポインターを渡した場合、結果は予測できません。 ほとんどの場合、プロバイダーが失敗する可能性があります。

逆に、コピーまたは移動してはならない補足情報を認識している場合は、 rgiidExclude パラメーターで渡される配列で除外するインターフェイスのインターフェイス識別子を追加します。 たとえば、メッセージをコピーしているが、メッセージの添付ファイルをコピーしていない場合は、 rgiidExclude 配列にIID_IMessageを渡します。 DoCopyTo は、 認識されない rgiidExclude に記載されているすべてのインターフェイスを無視します。

rgiidExclude パラメーターを使用してインターフェイスを除外すると、そのインターフェイスから派生したすべてのインターフェイスも除外されます。 たとえば、 IMAPIContainer インターフェイスを除外すると、プロバイダーの種類に応じてフォルダーまたはアドレス帳コンテナーが除外されます。 非常に多くのインターフェイスがそれらから派生するため、 IMAPIProp または IUnknown を除外しないでください。

DoCopyTo は 、操作全体に適用されるグローバル エラーと、個々のプロパティに適用される個々のエラーを報告します。 これらの個々のエラーは 、SPropProblemArray 構造体に 配置されます。 プロパティの問題の配列構造パラメーターに対して有効なポインターではなく NULL を渡すことで、プロパティ レベルでのエラー報告を抑制できます。

エラーに関する情報を受け取る場合は、lppProblems パラメーターに有効な SPropProblemArray 構造体ポインター を 渡します。 DoCopyTo がS_OKを返すと、構造体内の個々のプロパティで発生する可能性のあるエラーをチェックします。 DoCopyTo がエラーを返すと、SPropProblemArray 構造体に情報は返されません。 代わりに、 IMAPISupport::GetLastError メソッドを呼び出して、詳細なエラー情報を取得します。

DoCopyTo がS_OKを返す場合は、MAPIFreeBuffer 関数を呼び出して、返された SPropProblemArray 構造体を解放します。

DoCopyTo 呼び出しでグローバル エラーが発生した場合は、SPropProblemArray 構造体を使用したり解放したりしないでください。 プロバイダーは、DoCopyTo によって返される SPropProblemArray 構造体の ulIndex メンバーを無視する必要があります。

関連項目

IMAPIProp::CopyTo

IMAPISupport::CopyFolder

IMAPISupport::CopyMessages

IMAPISupport::GetLastError

PidTagContainerContents 標準プロパティ

PidTagContainerHierarchy 標準プロパティ

PidTagMessageAttachments 標準プロパティ

PidTagMessageDeliveryTime 標準プロパティ

PidTagMessageRecipients 標準プロパティ

SPropProblemArray

SPropTagArray

IMAPISupport: IUnknown