IMAPISupport：:D oCopyTo

發行項
03/16/2024

適用於：Outlook 2013 |Outlook 2016

複製或移動一個物件的所有屬性，但特別排除的屬性除外，移至另一個物件。

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

ulUIParam

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

lpProgress

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

lpDestInterface

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

lpDestObj

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

ulFlags

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

MAPI_DIALOG

顯示進度指示器。

MAPI_MOVE

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

MAPI_NOREPLACE

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

lppProblems

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

傳回值

S_OK

屬性已成功複製或移動。

MAPI_E_COLLISION

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

MAPI_E_FOLDER_CYCLE

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

MAPI_E_INTERFACE_NOT_SUPPORTED

lpSrcObj 所指向的物件不支援 lpSrcInterface 參數所識別的介面，或 lpDestObj 所指向的物件不支援 lpDestInterface 參數所識別的介面。

MAPI_E_NO_ACCESS

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

MAPI_E_INVALID_PARAMETER

lpSrcInterface 參數為 NULL。

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

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)

若要避免在將訊息複製到不同資料夾時複製訊息的傳遞時間，請在屬性標籤排除陣列中指定 PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) 。若要排除郵件的收件者清單，請將 PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) 屬性新增至 exclude 陣列。若要排除訊息的附件，請將 PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) 屬性新增至數位。

同樣地，若要防止複製或移動資料夾或通訊簿容器的階層或內容數據表，請在屬性標記排除陣列中包含 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 成員。