IMAPISupport：:D oCopyProps

發行項
03/15/2024

適用於：Outlook 2013 |Outlook 2016

將物件的一或多個屬性複製或移動到另一個物件。

HRESULT DoCopyProps(
  LPCIID lpSrcInterface,
  LPVOID lpSrcObj,
  LPSPropTagArray lpIncludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpDestInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

參數

lpSrcInterface

[in]介面識別碼的指標 (IID) ，表示要用來存取物件的介面與要複製或移動的屬性。

lpSrcObj

[in]物件的指標，其中包含要複製或移動的屬性。

lpIncludeProps

[in] SPropTagArray 結構的指標，其中包含屬性標記的計數陣列，指出要複製或移動的屬性。 lpIncludeProps 參數不能是 NULL。

ulUIParam

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

lpProgress

[in]進度指標實作的指標。如果在 lpProgress 參數中傳遞 NULL，則會使用 MAPI 實作來顯示進度指示器。除非在ulFlags參數中設定MAPI_DIALOG旗標，否則會忽略 lpProgress 參數。

lpDestInterface

[in]介面識別碼的指標，表示用來存取物件的介面，以接收複製或移動的屬性。

lpDestObj

[in]物件的指標，用來接收複製或移動的屬性。

ulFlags

[in]旗標的位掩碼，控制複製或移動作業的執行方式。您可以設定下列旗標：

MAPI_DIALOG

顯示進度指示器。

MAPI_MOVE

DoCopyProps 應該執行移動作業，而不是複製作業。未設定此旗標時， DoCopyProps 會執行複製作業。

MAPI_NOREPLACE

不應覆寫目的地物件中的現有屬性。未設定此旗標時， DoCopyProps 會覆寫現有的屬性。

lppProblems

[in， out]在輸入時，指向 SPropProblemArray 結構指標的指標;否則為 NULL，表示不需要錯誤資訊。如果 lppProblems 是輸入的有效指標， DoCopyProps 會 傳回有關複製一或多個屬性時發生錯誤的詳細資訊。

傳回值

S_OK

已成功複製或移動屬性。

MAPI_E_COLLISION

要複製或移動的屬性已經存在於目的地物件中，並已設定MAPI_NOREPLACE旗標。

MAPI_E_FOLDER_CYCLE

來源物件直接或間接包含目的地物件。在探索到此條件之前，可能已執行大量工作，因此來源和目的地物件可能會部分修改。

MAPI_E_INTERFACE_NOT_SUPPORTED

來源物件不支援 lpSrcInterface 參數所識別的介面，或目的地物件不支援 lpDestInterface 參數所識別的介面。

MAPI_E_NO_ACCESS

嘗試存取呼叫端許可權不足的物件。如果目的地物件與來源物件相同，則會傳回此錯誤。

下列值可以在 SPropProblemArray 結構中傳回，但不能作為 DoCopyProps 的傳回值。這些錯誤適用於單一屬性。

MAPI_E_BAD_CHARWIDTH

已設定MAPI_UNICODE旗標， 且 DoCopyProps 不支援 Unicode，或未設定MAPI_UNICODE， 且 DoCopyProps 僅支援 Unicode。

MAPI_E_COMPUTED

呼叫端無法修改屬性，因為它是只讀屬性，由目的地對象的擁有者計算。這個錯誤並不嚴重;呼叫端應該允許複製作業繼續。

MAPI_E_INVALID_TYPE

屬性類型無效。

MAPI_E_UNEXPECTED_TYPE

屬性類型不是呼叫端預期的類型。

註解

針對訊息存放區提供者支援對象實作 IMAPISupport：:D oCopyProps 方法。訊息存放區提供者可以呼叫 DoCopyProps ，為其資料夾和訊息實作 IMAPIProp：：CopyProps 方法。 DoCopyProps 會複製或移動 lpIncludeProps 所指向的屬性標籤列中所識別的屬性，以及存在於 lpSrcObj 所指向之物件中的屬性。

呼叫者注意事項

當您在相同類型的對象之間複製屬性時，例如兩個訊息， lpSrcInterface 和 lpDestInterface 參數必須包含相同的介面標識碼， 而 lpSrcObj 和 lpDestObj 參數必須指向相同類型的物件。如果 lpDestInterface 設定為 NULL，DoCopyProps 會傳回 MAPI_E_INVALID_PARAMETER。如果您將 lpDestInterface 設定為可接受的介面識別碼，但將 lpDestObj 設定為無效的指標，則結果會無法預測。很可能您的提供者會失敗。

如果您不想覆寫目的地物件中的任何屬性，請設定MAPI_NOREPLACE旗標。不刪除或修改來源物件中存在且未覆寫之目的地物件中的屬性。

若要複製郵件的收件者清單，請在 lpIncludeProps 參數所指向的屬性標記陣列中包含PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) 屬性。若要複製訊息的附件，請包含 PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) 屬性。

若要複製資料夾或通訊簿容器的階層或內容數據表，請在屬性卷標數位中包含 PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) 或 PR_CONTAINER_CONTENTS (PidTagContainerContents) 。若要包含資料夾的關聯內容表，請 在數位中 包含 PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) 屬性。

如果複製或移動子資料夾，則不論 使用 SPropTagArray 結構所指示的屬性為何，都會完整複製或行動其內容。

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

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

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