IXPLogon::SubmitMessage
Gilt für: Outlook 2013 | Outlook 2016
Gibt an, dass der MAPI-Spooler über eine Nachricht verfügt, die der Transportanbieter übermitteln soll.
HRESULT SubmitMessage(
ULONG ulFlags,
LPMESSAGE lpMessage,
ULONG FAR * lpulMsgRef,
ULONG FAR * lpulReturnParm
);
Parameter
ulFlags
[in] Eine Bitmaske von Flags, die steuert, wie die Nachricht übermittelt wird. Das folgende Flag kann festgelegt werden:
BEGIN_DEFERRED
Der MAPI-Spooler ruft einen Transportanbieter mit einer Nachricht auf, die zuvor zurückgestellt wurde. Der Eintragsbezeichner der Nachricht ist identisch mit dem Zeitpunkt, zu dem sie zurückgestellt wurde. Die Nachricht wurde verzögert, indem der Eintragsbezeichner mithilfe der IMAPISupport::SpoolerNotify-Methode mit dem NOTIFY_SENTDEFERRED-Flag an den MAPI-Spooler zurückübergibt.
lpMessage
[in] Ein Zeiger auf ein Nachrichtenobjekt (das die zu übermittelnde Nachricht darstellt), das über Lese-/Schreibberechtigungen verfügt, die der Transportanbieter verwendet, um auf diese Nachricht zuzugreifen und sie zu bearbeiten. Dieses Objekt bleibt gültig, bis der Transportanbieter von einem nachfolgenden Aufruf der IXPLogon::EndMessage-Methode zurückgegeben wird.
lpulMsgRef
[out] Ein Zeiger auf eine Variable, in der der Transportanbieter den Dieser Nachricht zugewiesenen Verweiswert zurückgibt. Der MAPI-Spooler übergibt diesen Verweiswert in nachfolgenden Aufrufen für diese Nachricht. Der MAPI-Spooler initialisiert den Wert auf 0, bevor er an den Transportanbieter zurückgegeben wird.
lpulReturnParm
[out] Ein Zeiger auf eine Variable, die dem von SubmitMessage zurückgegebenen MAPI_E_WAIT oder MAPI_E_NETWORK_ERROR Fehlerwert entspricht.
Rückgabewert
S_OK
Der Aufruf war erfolgreich und hat den erwarteten Wert oder die erwarteten Werte zurückgegeben.
MAPI_E_BUSY
Der Transportanbieter kann die Nachricht nicht verarbeiten, da er einen anderen Vorgang ausführt. Ein Anbieter sollte diesen Rückgabewert verwenden, um anzugeben, dass keine Verarbeitung stattgefunden hat und dass der MAPI-Spooler nicht EndMessage aufrufen soll. Der MAPI-Spooler versucht den SubmitMessage-Aufruf später erneut.
MAPI_E_CANCEL
Obwohl der Transportanbieter angefordert hat, dass der MAPI-Spooler die Nachricht bei einem vorherigen SpoolerNotify-Aufruf erneut übermittelt, haben sich die Bedingungen seitdem geändert, und die Nachricht sollte nicht erneut gesendet werden. Der MAPI-Spooler behandelt weiter etwas anderes.
MAPI_E_NETWORK_ERROR
Ein Netzwerkfehler verhinderte den erfolgreichen Abschluss des Vorgangs. Der lpulReturnParm-Parameter sollte auf die Anzahl der Sekunden festgelegt werden, die verstreichen, bevor der MAPI-Spooler die Nachricht erneut übermittelt.
MAPI_E_NOT_ME
Der Transportanbieter kann diese Nachricht nicht verarbeiten. Der MAPI-Spooler sollte versuchen, einen anderen Transportanbieter dafür zu finden. Ein Anbieter sollte diesen Rückgabewert verwenden, um anzugeben, dass keine Verarbeitung stattgefunden hat und dass der MAPI-Spooler nicht EndMessage aufrufen soll.
MAPI_E_WAIT
Ein temporäres Problem verhindert, dass der Transportanbieter die Nachricht verarbeitet. Der lpulReturnParm-Parameter sollte auf die Anzahl der Sekunden festgelegt werden, die verstreichen, bevor der MAPI-Spooler die Nachricht erneut übermittelt.
Hinweise
Der MAPI-Spooler ruft die IXPLogon::SubmitMessage-Methode auf, wenn eine Nachricht für den Transportanbieter bereitgestellt wird. Die Nachricht wird mithilfe des lpMessage-Parameters an den Transportanbieter übergeben.
Wenn der Anbieter bereit ist, die Nachricht zu akzeptieren, sollte er mithilfe des lpulMsgRef-Parameters einen Verweiswert zurückgeben, das übergebene Objekt verarbeiten und den entsprechenden Wert zurückgeben (in der Regel S_OK). Wenn der Anbieter nicht bereit ist, die Übertragung zu verarbeiten, sollte er einen Fehlerwert und optional einen weiteren MAPI-Rückgabewert in lpulReturnParm zurückgeben, um anzugeben, wie lange der MAPI-Spooler warten soll, bevor die Nachricht erneut übermittelt wird.
Die Implementierung dieser Methode durch einen Transportanbieter kann folgende Aktionen ausführen:
Legen Sie die Nachricht in eine interne Warteschlange, um auf die Übertragung zu warten, und kopieren Sie die Nachricht möglicherweise in den lokalen Speicher, und kehren Sie zurück.
Versuchen Sie, die tatsächliche Übertragung durchzuführen und zurückzugeben, wenn die Übertragung abgeschlossen ist, entweder erfolgreich oder erfolglos.
Bestimmen Sie, ob die Nachricht gesendet werden soll, nachdem Sie die betroffene Ressource überprüft haben. Wenn die Ressource in diesem Fall frei ist, kann der Anbieter die Ressource sperren, die Nachricht vorbereiten und übermitteln. Wenn die Ressource ausgelastet ist, kann der Anbieter die Nachricht vorbereiten und das Senden auf einen späteren Zeitpunkt verschieben.
Die bevorzugte Technik für die Nachrichtenübertragung hängt vom Transportanbieter und der erwarteten Anzahl von Prozessen ab, die um Systemressourcen konkurrieren.
Während eines SubmitMessage-Aufrufs steuert der Transportanbieter die Übertragung von Nachrichtendaten aus dem Nachrichtenobjekt. Der Transportanbieter sollte der Nachricht jedoch einen Verweiswert zuweisen, auf den er einen Zeiger in lpulMsgRef zurückgibt, bevor Daten übertragen werden. Dies geschieht, da der MAPI-Spooler jederzeit während des Prozesses die IXPLogon::TransportNotify-Methode mit dem NOTIFY_CANCEL_MESSAGE-Flag aufrufen kann, um dem Anbieter zu signalisieren, dass er alle geöffneten Objekte freigeben und die Nachrichtenübertragung beenden soll.
Der Transportanbieter sollte keine nicht übersetzbaren Eigenschaften der Nachricht senden. Wenn eine solche Eigenschaft gefunden wird, sollte die nächste Eigenschaft verarbeitet werden. Der Anbieter sollte alles daran setzen, MAPI_P1 Empfängerinformationen nicht als Teil des übermittelten Nachrichteninhalts anzuzeigen; Der Anbieter sollte diese Empfängerinformationen nur zu Adressierungszwecken verwenden. MAPI_P1 Empfänger sind intern generierte Empfänger, die zum erneuten Senden von Nachrichten verwendet werden; sie sollten nicht übertragen werden. Verwenden Sie stattdessen die anderen Empfänger zum Übertragen von Empfängerinformationen. Der Zweck dieser Anordnung besteht darin, empfängern erneut zu senden, dass genau dieselbe Empfängertabelle wie die ursprünglichen Empfänger angezeigt wird.
Während eines SubmitMessage-Aufrufs verarbeitet der MAPI-Spooler Methoden für Objekte, die während der Übertragung der Nachricht geöffnet werden, und verarbeitet alle Anlagen. Diese Verarbeitung kann sehr lange dauern. Transportanbieter können die IMAPISupport::SpoolerYield-Methode für den MAPI-Spooler während dieser Verarbeitung häufig aufrufen, um CPU-Zeit für andere Systemaufgaben freizugeben.
Alle Nachrichtenempfänger sind in der Empfängertabelle der Nachricht sichtbar, die der MAPI-Spooler ursprünglich übergeben hat. Der Transportanbieter sollte nur die Empfänger verarbeiten, die er verarbeiten kann – basierend auf der Eingabe-ID, dem Adresstyp oder beidem – und für die die eigenschaft PR_RESPONSIBILITY (PidTagResponsibility) noch nicht auf TRUE festgelegt ist. Wenn PR_RESPONSIBILITY bereits auf TRUE festgelegt ist, hat ein anderer Transportanbieter diesen Empfänger verarbeitet. Wenn der Anbieter eine ausreichende Verarbeitung eines Empfängers abschließt, um zu bestimmen, ob er Nachrichten für diesen Empfänger verarbeiten kann, sollte er die PR_RESPONSIBILITY Eigenschaft dieses Empfängers in der übergebenen Nachricht auf TRUE festlegen. In der Regel trifft der Anbieter diese Bestimmung, nachdem die Nachrichtenübermittlung abgeschlossen ist.
In der Regel kehrt der Transportanbieter erst nach abschluss der Übertragung von Nachrichtendaten von einem SubmitMessage-Aufruf zurück. Wenn kein Fehler zurückgegeben wird, ist der nächste Aufruf des MAPI-Spoolers an den Anbieter ein Aufruf der IXPLogon::EndMessage-Methode .
Wenn SubmitMessage einen Fehler zurückgibt, gibt der MAPI-Spooler die Nachricht im Prozess frei, ohne Änderungen zu speichern. Wenn der Transportanbieter das Speichern von Nachrichtenänderungen erfordert, muss er die IMAPIProp::SaveChanges-Methode für die Nachricht aufrufen, bevor er zurückgibt.
Bei Fehlern, die aufgrund von Transportproblemen auftreten, behält der MAPI-Spooler die Nachricht bei, verzögert jedoch die erneute Übermittlung der Nachricht an den Transportanbieter basierend auf dem in lpulReturnParm zurückgegebenen Wert. Der Transportanbieter muss diesen Wert eingeben, wenn sein Rückgabewert von SubmitMessage MAPI_E_WAIT oder MAPI_E_NETWORK_ERROR ist. Wenn ein schwerwiegender Fehler auftritt, muss der Transportanbieter die IMAPISupport::SpoolerNotify-Methode mit dem flag NOTIFY_CRITICAL_ERROR aufrufen.