IMAPIProp：：CopyTo

發行項
03/19/2024

適用於：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 表示應該複製或移動物件的所有屬性。當 lpExcludeProps 所指向之 SPropProblemArray 結構的 cValues 成員設定為 0 時，CopyTo 會傳回MAPI_E_INVALID_PARAMETER。

ulUIParam

[in]進度指示器之父視窗的句柄。

lpProgress

[in]進度指標實作的指標。如果在 lpProgress 參數中傳遞 null，MAPI 會提供進度實作。除非在ulFlags參數中設定MAPI_DIALOG旗標，否則會忽略 lpProgress 參數。

lpInterface

[in]介面識別碼的指標 (IID) ，表示要用來存取 lpDestObj 參數所指向之物件的介面。 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 會 傳回有關複製一或多個屬性錯誤的詳細資訊。

傳回值

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 的傳回值。下列錯誤適用於單一屬性：

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旗標來要求顯示進度指示器。如果您有 IMAPIProgress 的實作，則可以將 lpProgress 參數設定為，或設定為 null。如果 lpProgress 為 null，CopyTo 會使用 MAPI 提供的預設進度指示器。

您可以不設定MAPI_DIALOG旗標來隱藏進度指示器的顯示。 CopyTo 會忽略 ulUIParam 和 lpProgress 參數，而且不會顯示指標。

CopyTo 可以報告全域和個別錯誤，或是一或多個屬性所發生的錯誤。這些個別錯誤會放在 SPropProblemArray 結構中。您可以在屬性層級隱藏錯誤報告，方法是為屬性問題陣列結構參數傳遞 null，而不是有效的指標。

如果您想要接收錯誤的相關信息，請在 lppProblems 參數中傳遞有效的 SPropProblemArray 結構指標。當 CopyTo 傳回S_OK時，請檢查結構中個別屬性的可能錯誤。當 CopyTo 傳回錯誤時， SPropProblemArray 結構中不會傳回任何資訊。請改為呼叫 IMAPIProp：：GetLastError 來擷取詳細的錯誤資訊。

如果 CopyTo 傳回S_OK，請呼叫 MAPIFreeBuffer 函式來釋放傳回的 SPropProblemArray 結構。

如果您複製來源物件類型唯一的屬性，則必須確定目的地對象的類型相同。 CopyTo 不會防止您將通常屬於某個物件類型與另一種物件類型的屬性產生關聯。您必須複製對目的地物件有意義的屬性。例如，您不應該將訊息屬性複製到通訊簿容器。

若要確保您在相同類型的對象之間進行複製，請藉由比較物件指標或呼叫 IUnknown：：QueryInterface 來檢查來源和目的地物件是否相同。將 lpInterface 所指向的介面識別碼設定為來源對象的標準介面。此外，請確定物件類型或 PR_OBJECT_TYPE (PidTagObjectType) 屬性與這兩個物件相同。例如，如果您從訊息複製，請將 lpInterface 設定為 IID_IMessage，並將這兩個物件的 PR_OBJECT_TYPE 設定為 MAPI_MESSAGE。

如果在 lpDestObj 參數中傳遞了無效的指標，則結果會無法預測。

排除 CopyTo 呼叫上的屬性可能很有用。例如，某些物件具有物件單一實例特有的屬性，例如訊息傳遞的日期和時間。若要避免在將訊息複製到不同資料夾時複製訊息的傳遞時間，請在屬性標籤排除陣列中指定 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 範例程式代碼，請參閱下表。

檔案	Function	Comment
File.cpp	LoadFromMSG	MFCMAPI 使用 IMAPIProp：：CopyTo 方法，將屬性從.msg檔案複製到 IMAPIMessageSite 物件。
FolderDlg.cpp	CFolderDlg：：HandlePaste	MFCMAPI 會使用 IMAPIProp：：CopyTo 方法，在貼上作業期間，將屬性從來源訊息複製到目標訊息。