IMAPIProp::CopyTo

Artikel
04/04/2023

Gilt für: Outlook 2013 | Outlook 2016

Kopiert oder verschiebt alle Eigenschaften mit Ausnahme von speziell ausgeschlossenen Eigenschaften.

HRESULT CopyTo(
 ULONG ciidExclude,
 LPCIID rgiidExclude,
 LPSPropTagArray lpExcludeProps,
 ULONG_PTR ulUIParam,
 LPMAPIPROGRESS lpProgress,
 LPCIID lpInterface,
 LPVOID lpDestObj,
 ULONG ulFlags,
 LPSPropProblemArray FAR * lppProblems
);

Parameter

ciidExclude

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

rgiidExclude

[in] Ein Array von Schnittstellenbezeichnern (Interface Identifiers, IIDs), die Schnittstellen angeben, die nicht verwendet werden sollen, wenn zusätzliche Informationen in das Zielobjekt kopiert oder verschoben werden.

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. CopyTo gibt MAPI_E_INVALID_PARAMETER zurück, wenn das cValues-Element der SPropProblemArray-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.

lpInterface

[in] Ein Zeiger auf den Schnittstellenbezeichner (Interface Identifier, IID), der die Schnittstelle darstellt, die für den Zugriff auf das Objekt verwendet werden soll, auf das der lpDestObj-Parameter zeigt. Der lpInterface-Parameter darf nicht NULL sein.

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_DECLINE_OK

Wenn CopyTo die IMAPISupport::D oCopyTo-Methode aufruft, um den Kopier- oder Verschiebungsvorgang zu verarbeiten, sollte stattdessen sofort mit dem Fehlerwert MAPI_E_DECLINE_COPY zurückgegeben werden. Das MAPI_DECLINE_OK-Flag wird von MAPI festgelegt, um die Rekursion einzuschränken. Clients legen dieses Flag nicht fest.

MAPI_DIALOG

Zeigt eine Statusanzeige an.

MAPI_MOVE

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

MAPI_NOREPLACE

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

lppProblems

[in, 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 CopyTo 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

Ein Unterobjekt kann nicht kopiert werden, da ein Unterobjekt mit demselben Anzeigenamen – angegeben durch die eigenschaft PR_DISPLAY_NAME (PidTagDisplayName) – bereits im Zielobjekt vorhanden ist.

MAPI_E_DECLINE_COPY

Der Dienstanbieter implementiert den Kopiervorgang nicht.

MAPI_E_FOLDER_CYCLE

Das Quellobjekt, das den Kopier- oder Verschiebungsvorgang direkt oder indirekt ausführt, enthält 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 lpInterface-Parameter identifizierte Schnittstelle wird vom Zielobjekt 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.

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

MAPI_E_BAD_CHARWIDTH

Entweder wurde das MAPI_UNICODE-Flag festgelegt, und CopyTo unterstützt Unicode nicht, oder MAPI_UNICODE wurde nicht festgelegt und CopyTo 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

Standardmäßig kopiert oder verschiebt die IMAPIProp::CopyTo-Methode alle Eigenschaften des aktuellen Objekts in ein Zielobjekt. CopyTo wird verwendet, wenn ein Objekt genau kopiert oder verschoben werden soll, wobei alle oder die meisten Eigenschaften intakt sind.

Alle Unterobjekte im Quellobjekt werden automatisch in den Vorgang einbezogen und vollständig kopiert oder verschoben. Standardmäßig überschreibt CopyTo alle Eigenschaften im Zielobjekt, die mit Eigenschaften aus dem Quellobjekt übereinstimmen. 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 Implementierer

Sie können eine vollständige Implementierung von CopyTo bereitstellen oder sich auf die Implementierung verlassen, die MAPI im Supportobjekt bereitstellt. Wenn Sie die MAPI-Implementierung verwenden möchten, rufen Sie IMAPISupport::D oCopyTo auf. Wenn Sie jedoch die Verarbeitung an DoCopyTo delegieren und das MAPI_DECLINE_OK-Flag übergeben werden, vermeiden Sie den Supportaufruf, und geben Sie stattdessen MAPI_E_DECLINE_COPY zurück. MAPI ruft mit diesem Flag auf, um die mögliche Rekursion zu vermeiden, die beim Kopieren von Ordnern auftreten kann.

Da der Kopiervorgang lang sein kann, sollten Sie eine Statusanzeige anzeigen. Verwenden Sie die IMAPIProgress-Implementierung , die im lpProgress-Parameter übergeben wird, sofern vorhanden. Wenn lpProgressnull ist, rufen Sie die IMAPISupport::D oProgressDialog-Methode auf, um die MAPI-Implementierung zu verwenden.

Versuchen Sie nicht, bekannte schreibgeschützte Eigenschaften im Zielobjekt festzulegen. gibt stattdessen MAPI_E_NO_ACCESS zurück.

Die Quell- und Zielobjekte sollten die gleichen Schnittstellen verwenden. Gibt MAPI_E_INVALID_PARAMETER zurück, wenn lpInterface nicht festgelegt ist.

Gibt MAPI_E_INTERFACE_NOT_SUPPORTED zurück, wenn alle bekannten Schnittstellen ausgeschlossen sind.

Hinweise für Aufrufer

Legen Sie das MAPI_DECLINE_OK-Flag nicht fest. MAPI verwendet es in seinen Aufrufen von CopyTo-Implementierungen des Nachrichtenspeicheranbieters.

Da Kopier- und Verschiebevorgänge einige Zeit in Anspruch nehmen können, sollten Sie die Anzeige einer Statusanzeige anfordern, indem Sie das MAPI_DIALOG-Flag festlegen. Sie können den lpProgress-Parameter auf Ihre Implementierung von IMAPIProgress festlegen, sofern vorhanden, oder auf NULL. Wenn lpProgressnull ist, verwendet CopyTo die standardstatusanzeige, die MAPI bereitstellt.

Sie können die Anzeige einer Statusanzeige unterdrücken, indem Sie das MAPI_DIALOG-Flag nicht festlegen. CopyTo ignoriert die Parameter ulUIParam und lpProgress und zeigt den Indikator nicht an.

CopyTo kann globale und einzelne Fehler oder Fehler melden, die bei einer oder mehreren Eigenschaften auftreten. Diese einzelnen Fehler werden in einer SPropProblemArray-Struktur platziert. Sie können die Fehlerberichterstattung auf Eigenschaftenebene 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 CopyTo S_OK zurückgibt, suchen Sie nach möglichen Fehlern mit einzelnen Eigenschaften in der -Struktur. Wenn CopyTo einen Fehler zurückgibt, werden in der SPropProblemArray-Struktur keine Informationen zurückgegeben. Rufen Sie stattdessen IMAPIProp::GetLastError auf, um detaillierte Fehlerinformationen abzurufen.

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

Wenn Sie Eigenschaften kopieren, die für den Quellobjekttyp eindeutig sind, müssen Sie sicherstellen, dass das Zielobjekt denselben Typ aufweist. CopyTo hindert Sie nicht daran, Eigenschaften, die in der Regel zu einem Objekttyp gehören, einem anderen Objekttyp zuzuordnen. Es liegt an Ihnen, Eigenschaften zu kopieren, die für das Zielobjekt sinnvoll sind. Beispielsweise sollten Nachrichteneigenschaften nicht in einen Adressbuchcontainer kopiert werden.

Um sicherzustellen, dass Sie zwischen Objekten desselben Typs kopieren, überprüfen Sie, ob das Quell- und Zielobjekt denselben Typ haben, indem Sie entweder Objektzeiger vergleichen oder IUnknown::QueryInterface aufrufen. Legen Sie den Schnittstellenbezeichner, auf den lpInterface verweist, auf die Standardschnittstelle für das Quellobjekt fest. Stellen Sie außerdem sicher, dass der Objekttyp oder die PR_OBJECT_TYPE-Eigenschaft (PidTagObjectType) für die beiden Objekte identisch ist. Wenn Sie beispielsweise aus einer Nachricht kopieren, legen Sie lpInterface auf IID_IMessage und die PR_OBJECT_TYPE für beide Objekte auf MAPI_MESSAGE fest.

Wenn ein ungültiger Zeiger im lpDestObj-Parameter übergeben wird, sind die Ergebnisse unvorhersehbar.

Das Ausschließen von Eigenschaften für einen CopyTo-Aufruf kann nützlich sein. Einige Objekte verfügen beispielsweise über Eigenschaften, die für eine einzelne instance des Objekts spezifisch sind, z. B. Datum und Uhrzeit der Nachrichtenübermittlung. 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.

Ebenso können Sie das Kopieren oder Verschieben der Hierarchie oder Inhaltstabelle eines Ordner- oder Adressbuchcontainers verhindern, indem Sie PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) oder PR_CONTAINER_CONTENTS (PidTagContainerContents) in das Eigenschaftentag-Exclude-Array einschließen.

Um Eigenschaften aus dem Kopier- oder Verschiebungsvorgang auszuschließen, schließen Sie deren Eigenschaftstags in den lpExcludeProps-Parameter ein. Wenn Sie die Ergebnisse des makros PROP_TAG übergeben, um ein Eigenschaftstag 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)

Das eigenschaftstag PR_NULL (PidTagNull) kann nicht in das lpExcludeProps-Array eingeschlossen werden.

Die Nützlichkeit des CopyTo-Features für das Ausschließen von Schnittstellen ist vielleicht nicht so offensichtlich wie die Nützlichkeit des Ausschließens von Eigenschaften. Sie können eine Schnittstelle ausschließen, wenn Sie in ein Objekt kopieren, das keine Kenntnis von einer Gruppe von Eigenschaften hat. Wenn Sie z. B. Eigenschaften aus einem Ordner in eine Anlage kopieren, sind die einzigen Eigenschaften, mit denen die Anlage arbeiten kann, die generischen Eigenschaften, die mit jeder IMAPIProp-Implementierung verfügbar sind. Durch das Ausschließen von IMAPIFolder vom Kopiervorgang erhält die Anlage keine der spezifischeren Ordnereigenschaften.

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 von IMAPIContainer 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.

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

MFCMAPI-Referenz

Einen MFCMAP-Beispielcode finden Sie in der folgenden Tabelle.

Datei	Funktion	Kommentar
File.cpp	LoadFromMSG	MFCMAPI verwendet die IMAPIProp::CopyTo-Methode , um Eigenschaften aus einer .msg-Datei in ein IMAPIMessageSite-Objekt zu kopieren.
FolderDlg.cpp	CFolderDlg::HandlePaste	MFCMAPI verwendet die IMAPIProp::CopyTo-Methode , um Eigenschaften aus einer Quellnachricht während eines Einfügevorgangs in eine Zielnachricht zu kopieren.