IMAPIProp：：CopyProps

發行項
03/19/2024

適用於：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 實作來顯示進度指示器。除非在ulFlags參數中設定MAPI_DIALOG旗標，否則會忽略 lpProgress 參數。

lpInterface

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

傳回值

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

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 參數，請使用在 lpProgress 參數中傳遞的 IMAPIProgress 實作。如果 lpProgress 為 null，請呼叫 IMAPISupport：:D oProgressDialog 方法以使用 MAPI 實作。

呼叫者注意事項

請勿設定MAPI_DECLINE_OK旗標;MAPI 會在呼叫訊息存放區提供者 CopyProps 實作時使用它。

因為複製和移動作業可能需要一些時間，所以最好藉由設定 MAPI_DIALOG 旗標來要求顯示進度指示器。如果您有 IMAPIProgress 的實作，則可以將 lpProgress 參數設定為，或設定為 null。如果 lpProgress 為 null，CopyProps 將會使用 MAPI 提供的默認進度指示器。

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

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

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

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

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

若要確保您要在相同類型的對象之間複製，請藉由比較物件指標或呼叫 IUnknown：：QueryInterface 方法，檢查來源和目的地物件是否屬於相同類型。將 lpInterface 所指向的介面識別碼設定為來源對象的標準介面。此外，請確定物件類型或 PR_OBJECT_TYPE (PidTagObjectType) 屬性與這兩個物件的類型或PR_OBJECT_TYPE相同。例如，如果您要從訊息複製，請將 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 範例程式代碼，請參閱下表。

檔案	Function	Comment
MAPIFunctions.cpp	CopyNamedProps	MFCMAPI 使用 IMAPIProp：：CopyProps 方法，將具名屬性從一個訊息複製到另一個訊息。
SingleMAPIPropListCtrl.cpp	CSingleMAPIPropListCtrl：：OnPasteProperty	MFCMAPI 會使用 IMAPIProp：：CopyProps 方法來貼上已從另一個物件複製的屬性。