IMAPISupport::DoCopyTo

Artikel
04/04/2023

Gilt für: Outlook 2013 | Outlook 2016

Kopiert oder verschiebt alle Eigenschaften eines Objekts mit Ausnahme von speziell ausgeschlossenen Eigenschaften in ein anderes Objekt.

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
);

Parameter

lpSrcInterface

[in] Ein Zeiger auf den Schnittstellenbezeichner (Interface Identifier, IID), der die Schnittstelle darstellt, die für den Zugriff auf das Objekt verwendet werden soll, das über die zu kopierenden oder zu verschiebenden Eigenschaften verfügt.

lpSrcObj

[in] Ein Zeiger auf das Objekt, das über die zu kopierenden oder zu verschiebenden Eigenschaften verfügt.

ciidExclude

[in] Die Anzahl der Schnittstellen, die beim Kopieren oder Verschieben von Eigenschaften ausgeschlossen werden sollen.

rgiidExclude

[in] Ein Array von Schnittstellenbezeichnern, das Schnittstellen angibt, die nicht verwendet werden sollen, wenn Sie zusätzliche Informationen in das Zielobjekt kopieren oder verschieben.

lpExcludeProps

[in] Ein Zeiger auf ein Eigenschaftentagarray, das die Eigenschaftstags identifiziert, die vom Kopier- oder Verschiebungsvorgang ausgeschlossen werden sollen. Die Übergabe von NULL im lpExcludeProps-Parameter gibt an, dass alle Eigenschaften des Objekts kopiert oder verschoben werden sollen. DoCopyTo gibt MAPI_E_INVALID_PARAMETER zurück, wenn das cValues-Element der SPropTagArray-Struktur , auf die von lpExcludeProps verwiesen wird, auf 0 festgelegt ist.

ulUIParam

[in] Ein Handle für das übergeordnete Fenster der Statusanzeige.

lpProgress

[in] Ein Zeiger auf die Implementierung einer Statusanzeige. Wenn NULL im lpProgress-Parameter übergeben wird, stellt MAPI die Fortschrittsimplementierung bereit. Der lpProgress-Parameter wird ignoriert, es sei denn, das MAPI_DIALOG-Flag ist im ulFlags-Parameter festgelegt.

lpDestInterface

[in] Ein Zeiger auf den Schnittstellenbezeichner, der die Schnittstelle darstellt, die für den Zugriff auf das Objekt verwendet werden soll, um die kopierten oder verschobenen Eigenschaften zu empfangen.

lpDestObj

[in] Ein Zeiger auf das -Objekt, um die kopierten oder verschobenen Eigenschaften zu empfangen.

ulFlags

[in] Eine Bitmaske von Flags, die den Kopier- oder Verschiebungsvorgang steuert. Die folgenden Flags können festgelegt werden:

MAPI_DIALOG

Zeigt eine Statusanzeige an.

MAPI_MOVE

DoCopyTo sollte anstelle eines Kopiervorgangs einen Verschiebungsvorgang ausführen. Wenn dieses Flag nicht festgelegt ist, führt DoCopyTo einen Kopiervorgang aus.

MAPI_NOREPLACE

Vorhandene Eigenschaften im Zielobjekt sollten nicht überschrieben werden. Wenn dieses Flag nicht festgelegt ist, überschreibt DoCopyTo vorhandene Eigenschaften.

lppProblems

[out] Bei der Eingabe ein Zeiger auf einen Zeiger auf eine SPropProblemArray-Struktur ; andernfalls NULL, was angibt, dass keine Fehlerinformationen erforderlich sind. Wenn lppProblems ein gültiger Zeiger für die Eingabe ist, gibt DoCopyTo ausführliche Informationen zu Fehlern beim Kopieren einer oder mehrerer Eigenschaften zurück.

Rückgabewert

S_OK

Die Eigenschaften wurden erfolgreich kopiert oder verschoben.

MAPI_E_COLLISION

Eine zu kopierende oder zu verschiebende Eigenschaft ist bereits im Zielobjekt vorhanden, und das MAPI_NOREPLACE-Flag ist festgelegt.

MAPI_E_FOLDER_CYCLE

Das Quellobjekt enthält direkt oder indirekt das Zielobjekt. Möglicherweise wurden erhebliche Arbeiten ausgeführt, bevor diese Bedingung erkannt wurde, sodass die Quell- und Zielobjekte möglicherweise teilweise geändert wurden.

MAPI_E_INTERFACE_NOT_SUPPORTED

Die durch den lpSrcInterface-Parameter identifizierte Schnittstelle wird von dem Objekt, auf das von lpSrcObj verwiesen wird, nicht unterstützt, oder die durch den lpDestInterface-Parameter identifizierte Schnittstelle wird von dem Objekt, auf das von lpDestObj verwiesen wird, nicht unterstützt.

MAPI_E_NO_ACCESS

Es wurde versucht, auf ein Objekt zuzugreifen, für das der Aufrufer über unzureichende Berechtigungen verfügt. Dieser Fehler wird zurückgegeben, wenn das Zielobjekt mit dem Quellobjekt identisch ist.

MAPI_E_INVALID_PARAMETER

Der lpSrcInterface-Parameter ist NULL.

Die folgenden Werte können in der SPropProblemArray-Struktur zurückgegeben werden, jedoch nicht als Rückgabewerte für DoCopyTo. Diese Fehler gelten für eine einzelne Eigenschaft.

MAPI_E_BAD_CHARWIDTH

Entweder wurde das flag MAPI_UNICODE festgelegt, und DoCopyTo unterstützt Unicode nicht, oder MAPI_UNICODE wurde nicht festgelegt und DoCopyTo unterstützt nur Unicode.

MAPI_E_COMPUTED

Die Eigenschaft kann vom Aufrufer nicht geändert werden, da es sich um eine schreibgeschützte Eigenschaft handelt, die vom Besitzer des Zielobjekts berechnet wird. Dieser Fehler ist nicht schwerwiegend. Der Aufrufer sollte zulassen, dass der Kopiervorgang fortgesetzt wird.

MAPI_E_INVALID_TYPE

Der Eigenschaftstyp ist ungültig.

MAPI_E_UNEXPECTED_TYPE

Der Eigenschaftstyp ist nicht der Typ, der vom Aufrufer erwartet wird.

Hinweise

Die IMAPISupport::D oCopyTo-Methode wird für Unterstützungsobjekte des Nachrichtenspeicheranbieters implementiert. Nachrichtenspeicheranbieter können DoCopyTo aufrufen, um die IMAPIProp::CopyTo-Methode für ihre Ordner und Nachrichten zu implementieren.

Standardmäßig kopiert DoCopyTo alle Eigenschaften eines Objekts in ein anderes Objekt oder verschiebt sie. Alle Unterobjekte im Quellobjekt werden automatisch in den Vorgang einbezogen und vollständig kopiert oder verschoben.

Wenn eine der kopierten oder verschobenen Eigenschaften bereits im Zielobjekt vorhanden ist, werden die vorhandenen Eigenschaften von den neuen Eigenschaften überschrieben, es sei denn, das MAPI_NOREPLACE-Flag ist im ulFlags-Parameter festgelegt. Vorhandene Informationen im Zielobjekt, die nicht überschrieben werden, bleiben unverändert.

Hinweise für Aufrufer

Um Eigenschaften aus dem Kopier- oder Verschiebungsvorgang auszuschließen, schließen Sie deren Eigenschaftstags in den lpExcludeProps-Parameter ein. Wenn Sie die Ergebnisse der Verwendung des makros PROP_TAG übergeben, um ein Eigenschaftentag aus einem bestimmten Bezeichner im Eigenschaftentagarray zu erstellen, werden alle Eigenschaften mit diesem Bezeichner ausgeschlossen. Der folgende Eintrag im Eigenschaftentagarray bewirkt beispielsweise, dass alle Eigenschaften mit dem Bezeichner 0x8002 ausgeschlossen werden, unabhängig vom Typ:

PROP_TAG(PT_LONG, 0x8002)

Um das Kopieren der Zustellungszeit einer Nachricht zu vermeiden, wenn Sie die Nachricht in einen anderen Ordner kopieren, geben Sie PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) im Eigenschaftentag-Exclude-Array an. Um die Empfängerliste einer Nachricht auszuschließen, fügen Sie dem Exclude-Array die Eigenschaft PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) hinzu. Um die Anlagen einer Nachricht auszuschließen, fügen Sie dem Array die Eigenschaft PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) hinzu.

Um das Kopieren oder Verschieben der Hierarchie- oder Inhaltstabelle eines Ordner- oder Adressbuchcontainers zu verhindern, schließen Sie PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) oder PR_CONTAINER_CONTENTS (PidTagContainerContents) in das Eigenschaftentag-Exclude-Array ein.

Ignorieren Sie MAPI_E_COMPUTED Fehler, die in der SPropProblemArray-Struktur im lppProblems-Parameter zurückgegeben werden.

Der Schnittstellenbezeichner, auf den lpSrcInterface verweist, ist in der Regel mit dem Schnittstellenbezeichner identisch, auf den lpDestInterface verweist.

Wenn Sie einen akzeptablen Schnittstellenbezeichner in lpDestInterface , aber einen ungültigen Zeiger in lpDestObj übergeben, sind die Ergebnisse unvorhersehbar. Dies führt höchstwahrscheinlich dazu, dass Ihr Anbieter ausfällt.

Wenn Sie jedoch zusätzliche Informationen kennen, die nicht kopiert oder verschoben werden sollten, fügen Sie die Schnittstellenbezeichner für die auszuschließenden Schnittstellen im Array hinzu, das im rgiidExclude-Parameter übergeben wird. Wenn Sie z. B. Nachrichten, aber keine der zugehörigen Nachrichtenanlagen kopieren, übergeben Sie IID_IMessage im rgiidExclude-Array . DoCopyTo ignoriert alle in rgiidExclude aufgeführten Schnittstellen, die nicht erkannt werden.

Wenn Sie den rgiidExclude-Parameter verwenden, um eine Schnittstelle auszuschließen, werden auch alle schnittstellen ausgeschlossen, die von dieser Schnittstelle abgeleitet wurden. Das Ausschließen der IMAPIContainer-Schnittstelle bewirkt beispielsweise, dass Ordner oder Adressbuchcontainer je nach Anbietertyp ausgeschlossen werden. Schließen Sie IMAPIProp oder IUnknown nicht aus, da so viele Schnittstellen von ihnen abgeleitet werden.

DoCopyTo meldet globale Fehler, die für den Vorgang als Ganzes gelten, sowie einzelne Fehler, die für einzelne Eigenschaften gelten. Diese einzelnen Fehler werden in eine SPropProblemArray-Struktur eingefügt. Sie können die Fehlerberichterstattung auf Eigenschaftsebene unterdrücken, indem Sie NULL anstelle eines gültigen Zeigers für den Strukturparameter des Eigenschaftenproblemarrays übergeben.

Wenn Sie Informationen zu Fehlern erhalten möchten, übergeben Sie einen gültigen SPropProblemArray-Strukturzeiger im lppProblems-Parameter . Wenn DoCopyTo S_OK zurückgibt, suchen Sie nach möglichen Fehlern mit einzelnen Eigenschaften in der -Struktur. Wenn DoCopyTo einen Fehler zurückgibt, werden keine Informationen in der SPropProblemArray-Struktur zurückgegeben. Rufen Sie stattdessen die IMAPISupport::GetLastError-Methode auf, um detaillierte Fehlerinformationen abzurufen.

Wenn DoCopyTo S_OK zurückgibt, geben Sie die zurückgegebene SPropProblemArray-Struktur frei, indem Sie die MAPIFreeBuffer-Funktion aufrufen.

Wenn beim DoCopyTo-Aufruf ein globaler Fehler auftritt, verwenden oder geben Sie die SPropProblemArray-Struktur nicht frei. Anbieter sollten den ulIndex-Member in SPropProblemArray-Strukturen ignorieren, die von DoCopyTo zurückgegeben werden.