IMAPIFolder::CopyMessages

Gilt für: Outlook 2013 | Outlook 2016

Kopiert oder verschiebt eine oder mehrere Nachrichten.

HRESULT CopyMessages(
  LPENTRYLIST lpMsgList,
  LPCIID lpInterface,
  LPVOID lpDestFolder,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameter

lpMsgList

[in] Ein Zeiger auf ein Array von ENTRYLIST-Strukturen, die die zu kopierenden oder zu verschiebenden Nachrichten identifizieren.

lpInterface

[in] Ein Zeiger auf die Schnittstellenkennung (IID), die die Schnittstelle darstellt, die für den Zugriff auf den Zielordner verwendet werden soll, auf den der Parameter lpDestFolder verweist. Die Übergabe von NULL führt dazu, dass der Dienstanbieter die Standardordnerschnittstelle IMAPIFolder : IMAPIContainer zurückgibt. Clients müssen NULL übergeben. Andere Aufrufer können den Parameter lpInterface auf „IID_IUnknown“, „IID_IMAPIProp“, „IID_IMAPIContainer“ oder „IID_IMAPIFolder“ setzen.

lpDestFolder

[in] Ein Zeiger auf den geöffneten Ordner, in dem die kopierten oder verschobenen Nachrichten empfangen werden sollen.

ulUIParam

[in] Ein Handle für das übergeordnete Fenster aller Dialogfelder oder Fenster, die mit dieser Methode angezeigt werden. Der Parameter ulUIParam wird ignoriert, es sei denn, der Client setzt das Kennzeichen MESSAGE_DIALOG im ParameterulFlags und übergibt NULL im Parameter lpProgress.

lpProgress

[in] Ein Zeiger auf ein Statusobjekt, das eine Statusanzeige anzeigt. Wenn NULL in lpProgress übergeben wird, zeigt der Anbieter des Nachrichtenspeichers eine Statusanzeige mithilfe der MAPI-Statusobjektimplementierung an. Der Parameter lpProgress wird ignoriert, es sei denn, das Kennzeichen MESSAGE_DIALOG ist in ulFlags gesetzt.

ulFlags

[in] Eine Bitmaske aus Kennzeichen, die steuert, wie der Kopier- oder Verschiebevorgang ausgeführt wird. Die folgenden Kennzeichen können festgelegt werden:

MAPI_DECLINE_OK

Weist den Nachrichtenspeicheranbieter an, sofort MAPI_E_DECLINE_COPY zurückzugeben, wenn er IMAPIFolder::CopyMessages implementiert, indem er die Methode IMAPISupport::DoCopyTo oder IMAPISupport::DoCopyProps des Unterstützungsobjekts aufruft.

MESSAGE_DIALOG

Zeigt eine Statusanzeige an, während der Vorgang ausgeführt wird.

MESSAGE_MOVE

Die Nachricht bzw. die Nachrichten sollen verschoben statt kopiert werden. Wenn MESSAGE_MOVE nicht gesetzt ist, werden die Nachrichten kopiert.

Rückgabewert

S_OK

Die Nachricht bzw. Nachrichten wurden erfolgreich kopiert oder verschoben.

MAPI_E_DECLINE_COPY

Der Anbieter implementiert diese Methode durch Aufrufen einer Unterstützungsobjektmethode, und der Aufrufer hat das Kennzeichen MAPI_DECLINE_OK übergeben.

MAPI_W_PARTIAL_COMPLETION

Der Aufruf war erfolgreich, jedoch wurden nicht alle Einträge erfolgreich kopiert oder verschoben. Wenn diese Warnung zurückgegeben wird, sollte der Aufruf als erfolgreich behandelt werden. Verwenden Sie zum Testen auf diese Warnung das Makro HR_FAILED. Weitere Informationen finden Sie unter Verwendung von Makros zur Fehlerbehandlung.

Hinweise

Die Methode IMAPIFolder::CopyMessages kopiert oder verschiebt Nachrichten in einen anderen Ordner.

Nachrichten, die mit Lese-/Schreibberechtigung geöffnet werden, können verschoben oder kopiert werden.

Hinweise für Implementierer

Wenn Sie Nachrichten in einen anderen Nachrichtenspeicher kopieren, ohne die Methode IMAPISupport::CopyMessages zu verwenden, müssen Sie zunächst IMAPIFolder::SetReadFlags mit dem Kennzeichen GENERATE_RECEIPT_ONLY aufrufen. Der empfangende Nachrichtenspeicher ist nicht für die Erstellung von Lesebestätigungen für die kopierten oder verschobenen Nachrichten verantwortlich. Wenn Sie IMAPISupport::CopyMessages aufrufen, um IMAPIFolder::CopyMessages zu implementieren, rufen Sie SetReadFlags nicht auf; MAPI ruft diese Funktion auf.

Ihre Implementierung kann die Nachrichten in beliebiger Reihenfolge verschieben oder kopieren und Lesestatusberichte in beliebiger Reihenfolge erstellen. Das heißt, Sie können das Kopieren von Nachrichten fertigstellen, bevor Sie einen der Lesestatusberichte erstellen, oder die Berichte senden, bevor Ihre Implementierung den Kopiervorgang startet. Leseberichte sollten jedoch für alle zu kopierenden Nachrichten gesendet werden, unabhängig davon, ob die Kopie erfolgreich war.

Wenn der Vorgang zum Kopieren oder Verschieben mehr als eine Nachricht umfasst, führen Sie den Vorgang so vollständig wie möglich aus. Beenden Sie den Vorgang nicht vorzeitig, es sei denn, es tritt ein Fehler auf, der außerhalb Ihrer Kontrolle liegt, z. B. nicht genügend Arbeitsspeicher, nicht genügend Datenträgerfläche oder eine Beschädigung des Nachrichtenspeichers.

Versuchen Sie, Eingabebezeichner während der Verschiebungs- oder Kopiervorgänge beizubehalten. Sie sollten auch Eintragsbezeichner beibehalten, obwohl dies nicht erforderlich ist.

Senden Sie Benachrichtigungen, wenn Sie Nachrichten verschieben oder kopieren, damit Clients vorab darüber informiert werden, dass ihre Aufrufe der IMAPIProp::SaveChanges-Methoden der Nachrichten möglicherweise fehlschlagen.

Schließen Sie den Status einer Nachricht nicht in den Kopier- oder Verschiebungsvorgang ein. Das Verschieben oder Kopieren eines Nachrichtenstatus wirkt sich erheblich auf die Leistung aus.

Hinweise für Aufrufer

Verwenden Sie IMAPIFolder::CopyMessages, um Suchergebnisordner zu füllen, in denen Nachrichten häufig nach übergeordneten Ordnern gruppiert sind.

Erwarten Sie diese Rückgabewerte unter den folgenden Bedingungen.

Bedingung	Rückgabewert
IMAPIFolder::CopyMessages hat alle Nachrichten erfolgreich kopiert oder verschoben.	S_OK
IMAPIFolder::CopyMessages konnte nicht alle Nachrichten erfolgreich kopieren oder verschieben.	MAPI_W_PARTIAL_COMPLETION
IMAPIFolder::CopyMessages konnte nicht abgeschlossen werden.	Beliebiger Fehlerwert

Wenn IMAPIFolder::CopyMessages nicht abgeschlossen werden kann, sollten Sie nicht davon ausgehen, dass keine Arbeit ausgeführt wurde. IMAPIFolder::CopyMessages konnte möglicherweise eine oder mehrere Nachrichten kopieren oder verschieben, bevor der Fehler aufgetreten ist.

Siehe auch

IMAPIFolder : IMAPIContainer