IMAPIProp::CopyProps

Artikel
04/04/2023

Gilt für: Outlook 2013 | Outlook 2016

Kopiert oder verschiebt ausgewählte Eigenschaften.

HRESULT CopyProps(
  LPSPropTagArray lpIncludeProps,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  LPCIID lpInterface,
  LPVOID lpDestObj,
  ULONG ulFlags,
  LPSPropProblemArray FAR * lppProblems
);

Parameter

lpIncludeProps

[in] Ein Zeiger auf ein Eigenschaftentagarray, das die zu kopierenden oder zu verschiebenden Eigenschaften angibt. PR_NULL (PidTagNull) kann nicht in das Array eingeschlossen werden. Der lpIncludeProps-Parameter darf nicht NULL sein.

ulUIParam

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

lpProgress

[in] Ein Zeiger auf eine Implementierung eines Statusindikators. Wenn null im lpProgress-Parameter übergeben wird, wird die Statusanzeige mithilfe der MAPI-Implementierung angezeigt. 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 muss, auf das der lpDestObj-Parameter verweist. 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 CopyProps die IMAPISupport::D oCopyProps-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

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

MAPI_NOREPLACE

Vorhandene Eigenschaften im Zielobjekt sollten nicht überschrieben werden. Wenn dieses Flag nicht festgelegt ist, überschreibt CopyProps 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 CopyProps ausführliche Informationen zu Fehlern beim Kopieren einer oder mehrerer Eigenschaften zurück.

Rückgabewert

S_OK

Eigenschaften wurden erfolgreich kopiert oder verschoben.

MAPI_E_COLLISION

Ein Unterobjekt kann nicht kopiert werden, da ein Unterobjekt mit demselben Anzeigenamen, das durch die eigenschaft PR_DISPLAY_NAME (PidTagDisplayName) definiert wird, 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 CopyProps. Diese Fehler gelten für eine einzelne Eigenschaft.

MAPI_E_BAD_CHARWIDTH

Entweder wurde das MAPI_UNICODE-Flag festgelegt, und CopyProps unterstützt Unicode nicht, oder MAPI_UNICODE wurde nicht festgelegt und CopyProps 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 IMAPIProp::CopyProps-Methode kopiert oder verschiebt ausgewählte Eigenschaften aus dem aktuellen Objekt in ein Zielobjekt. CopyProps wird hauptsächlich zum Beantworten und Weiterleiten von Nachrichten verwendet, wobei nur einige der Eigenschaften der ursprünglichen Nachricht mit der Antwort oder der weitergeleiteten Kopie übertragen werden.

Alle Unterobjekte im Quellobjekt werden automatisch in den Vorgang eingeschlossen und vollständig kopiert oder verschoben, unabhängig von der Verwendung von Eigenschaften, die durch die SPropTagArray-Struktur angegeben werden. Standardmäßig überschreibt CopyProps alle Eigenschaften im Zielobjekt, die den Eigenschaften des Quellobjekts entsprechen. 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 CopyProps bereitstellen oder sich auf die Implementierung verlassen, die MAPI im Supportobjekt bereitstellt. Wenn Sie die MAPI-Implementierung verwenden möchten, rufen Sie die IMAPISupport::D oCopyProps-Methode auf. Wenn Sie jedoch die Verarbeitung an DoCopyProps delegieren und das MAPI_DECLINE_OK-Flag übergeben werden, vermeiden Sie den Supportaufruf, und geben Sie stattdessen MAPI_E_DECLINE_COPY zurück. Sie werden von MAPI mit diesem Flag aufgerufen, 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.

Hinweise für Aufrufer

Legen Sie das MAPI_DECLINE_OK-Flag nicht fest. Sie wird von MAPI in ihren Aufrufen von CopyProps-Implementierungen des Nachrichtenspeicheranbieters verwendet.

Da Kopier- und Verschiebevorgänge einige Zeit in Anspruch nehmen können, empfiehlt es sich, die Anzeige einer Statusanzeige anzufordern, 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 CopyProps den von MAPI bereitgestellten Standardstatusindikator.

Sie können die Anzeige einer Statusanzeige unterdrücken, indem Sie das MAPI_DIALOG-Flag nicht festlegen. CopyProps ignoriert die Parameter ulUIParam und lpProgress und vermeidet die Anzeige des Indikators.

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

Wenn CopyProps 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. CopyProps 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 die IUnknown::QueryInterface-Methode 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.

Um die Empfängerliste einer Nachricht zu kopieren, rufen Sie die CopyProps-Methode der Nachricht auf, und schließen Sie die eigenschaft PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) in das Eigenschaftentagarray ein. Um die Anlagen der Nachricht zu kopieren, schließen Sie die eigenschaft PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) ein.

Um die Hierarchie oder Inhaltstabelle eines Ordner- oder Adressbuchcontainers zu kopieren, fügen Sie die Eigenschaften PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) oder PR_CONTAINER_CONTENTS (PidTagContainerContents) in das Eigenschaftentagarray ein. Um die zugeordnete Inhaltstabelle eines Ordners einzuschließen, schließen Sie die eigenschaft PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) in das Array ein.

MFCMAPI-Referenz

Einen MFCMAP-Beispielcode finden Sie in der folgenden Tabelle.

Datei	Funktion	Kommentar
MAPIFunctions.cpp	CopyNamedProps	MFCMAPI verwendet die IMAPIProp::CopyProps-Methode, um benannte Eigenschaften von einer Nachricht in eine andere zu kopieren.
SingleMAPIPropListCtrl.cpp	CSingleMAPIPropListCtrl::OnPasteProperty	MFCMAPI verwendet die IMAPIProp::CopyProps-Methode , um eine Eigenschaft einzufügen, die aus einem anderen Objekt kopiert wurde.