IMAPIStatus::ValidateState
Gilt für: Outlook 2013 | Outlook 2016
Bestätigt die externen status Informationen, die für die MAPI-Ressource oder den Dienstanbieter verfügbar sind. Diese Methode wird in allen status-Objekten unterstützt.
HRESULT ValidateState(
ULONG_PTR ulUIParam,
ULONG ulFlags
);
Parameter
ulUIParam
[in] Ein Handle für das übergeordnete Fenster aller Dialogfelder oder Fenster, die von dieser Methode angezeigt werden.
ulFlags
[in] Eine Bitmaske von Flags, die die Überprüfung steuert. Die folgenden Flags können festgelegt werden:
ABORT_XP_HEADER_OPERATION
Der Benutzer hat den Vorgang abgebrochen, in der Regel durch Klicken auf die Schaltfläche Abbrechen im entsprechenden Dialogfeld. Das status-Objekt verfügt über zwei Optionen:
Arbeiten Sie mit dem Vorgang fort.
Beenden Sie den Vorgang, und geben Sie MAPI_E_USER_CANCELED zurück.
CONFIG_CHANGED
Mindestens eine der Konfigurationseigenschaften des status Objekts wurde geändert. Clients können dieses Flag festlegen, damit der MAPI-Spooler kritische Transportanbieterfehler dynamisch korrigieren kann.
FORCE_XP_CONNECT
Das status -Objekt sollte eine Verbindung herstellen. Wenn dieses Flag mit dem REFRESH_XP_HEADER_CACHE- oder PROCESS_XP_HEADER_CACHE-Flag verwendet wird, erfolgt die Verbindung ohne Zwischenspeicherung.
FORCE_XP_DISCONNECT
Das status-Objekt sollte eine Trennungsoperation ausführen. Wenn dieses Flag mit dem REFRESH_XP_HEADER_CACHE- oder PROCESS_XP_HEADER_CACHE-Flag verwendet wird, erfolgt die Trennung ohne Zwischenspeicherung.
PROCESS_XP_HEADER_CACHE
Einträge in der Headercachetabelle sollten verarbeitet werden, alle nachrichten, die mit dem MSGSTATUS_REMOTE_DOWNLOAD-Flag markiert sind, und alle nachrichten, die mit dem MSGSTATUS_REMOTE_DELETE-Flag gekennzeichnet sind, sollten gelöscht werden. Nachrichten, für die sowohl MSGSTATUS_REMOTE_DOWNLOAD als auch MSGSTATUS_REMOTE_DELETE festgelegt sind, sollten verschoben werden.
REFRESH_XP_HEADER_CACHE
Für einen Remotetransportanbieter sollte eine neue Liste von Nachrichtenheadern heruntergeladen werden, und alle Flags, die nachrichtenbasierte status markieren, sollten gelöscht werden.
SUPPRESS_UI
Verhindert, dass das status -Objekt im Rahmen des Vorgangs eine Benutzeroberfläche anzeigt.
Rückgabewert
S_OK
Die Überprüfung war erfolgreich.
MAPI_E_BUSY
Ein weiterer Vorgang wird ausgeführt. Er sollte vor dem Initiieren dieses Vorgangs abgeschlossen oder beendet werden können.
MAPI_E_NO_SUPPORT
Das status-Objekt unterstützt die Validierungsmethode nicht, wie durch das Fehlen des STATUS_VALIDATE_STATE-Flags in der eigenschaft PR_RESOURCE_METHODS (PidTagResourceMethods) angegeben.
MAPI_E_USER_CANCEL
Der Benutzer hat den Überprüfungsvorgang abgebrochen, in der Regel durch Klicken auf die Schaltfläche Abbrechen in einem Dialogfeld. Dieser Wert wird nur von Remotetransportanbietern zurückgegeben.
Hinweise
Die IMAPIStatus::ValidateState-Methode überprüft den Zustand einer Ressource, die einem status-Objekt zugeordnet ist. ValidateState ist die einzige Methode in der IMAPIStatus-Schnittstelle, die für alle status-Objekte erforderlich ist. Das genaue Verhalten dieser Methode hängt von der Implementierung ab. In der folgenden Tabelle wird die Implementierung der einzelnen Typen von status -Objekten beschrieben.
| Status-Objekt | ValidateState-Implementierung |
|---|---|
| MAPI-Subsystem |
Überprüft den Status aller Ressourcen, die den derzeit aktiven Dienstanbietern und dem Subsystem selbst gehören. |
| MAPI-Spooler |
Führt eine Anmeldung aller Transportanbieter aus, unabhängig davon, ob sie bereits angemeldet sind. |
| MAPI-Adressbuch |
Überprüft die Einträge im zugehörigen Profilabschnitt. |
| Dienstleister |
Die Implementierung hängt vom Typ des Anbieters und den im ulFlags-Parameter festgelegten Flags ab. |
Hinweise für Implementierer
Remoteclientanwendungen rufen die ValidateState-Methode auf, um die Remoteverarbeitung für verschiedene Aktionen zu starten. Diese Methode dient in erster Linie dazu, status Bits für die Kommunikation mit dem MAPI-Spooler festzulegen, anstatt tatsächlich arbeiten zu können. In der Regel legt der Transportanbieter Flags in seiner status Zeile fest, die dem MAPI-Spooler angeben, welche Aktionen initiiert werden müssen, um die Anforderung des Clients abzuschließen.
In diesem Modell der Client-Transport-Spooler-Interaktion sind die vom Client angeforderten Aktionen asynchron, da ValidateState zurückgibt, bevor die angeforderten Aktionen abgeschlossen sind. Aktionen, die nicht unbedingt das zugrunde liegende Messagingsystem betreffen oder eine transportspezifische Schnittstelle umfassen, können jedoch synchron sein. Die Clientanwendung übergibt eine Bitmaske der folgenden Flags, um anzugeben, welche Aktionen der Remotetransportanbieter ausführen soll.
ABORT_XP_HEADER_OPERATION
Wenn möglich, sollte der Remotetransportanbieter alle Vorgänge abbrechen, die das Herunterladen von Headern beinhalten. Dazu muss der Transportanbieter die folgenden Eigenschaftswerte in der status Zeile des Anmeldeobjekts festlegen:
Löschen Sie die STATUS_INBOUND_ENABLED und STATUS_INBOUND_ACTIVE Bits in der eigenschaft PR_STATUS_CODE (PidTagStatusCode), um den MAPI-Spooler anzuhalten, den eingehenden Leerungsprozess für diesen Transportanbieter anzuhalten.
Legen Sie das STATUS_OFFLINE Bit in der eigenschaft PR_STATUS_CODE fest.
Legen Sie die eigenschaft PR_REMOTE_VALIDATE_OK (PidTagRemoteValidateOk) auf TRUE fest.
Legen Sie die eigenschaft PR_STATUS_STRING (PidTagStatusString) auf eine Zeichenfolge fest, die die status des Transportanbieters für den Benutzer angibt.
Geben Sie S_OK zur�ck. Wenn der laufende Vorgang jedoch nicht abgebrochen werden kann, sollte ValidateState MAPI_E_BUSY zurückgeben.
FORCE_XP_CONNECT
Ein Remotetransportanbieter sollte niemals außerhalb des Kontexts der MAPI-Spooler-Transportinteraktion, die an der IXPLogon::FlushQueues-Methode beteiligt ist, eine Verbindung mit einer freigegebenen Ressource (z. B. einem Modem oder COM-Port) herstellen. Wenn ValidateState mit diesem Flag aufgerufen wird, sollte Ihr Transportanbieter die folgenden Schritte ausführen:
Legen Sie ein internes status-Flag fest, um anzugeben, dass die Remoteverbindung hergestellt werden muss, wenn die IXPLogon::FlushQueues-Methode aufgerufen wird.
Legen Sie die richtigen Werte in der status-Tabelle fest, damit der MAPI-Spooler den Warteschlangenleervorgang initiiert.
Wenn das Leeren von Warteschlangen abgeschlossen ist, geben Sie die freigegebene Ressource frei.
Löschen Sie das STATUS_OFFLINE Bit in der eigenschaft PR_STATUS_CODE .
Geben Sie S_OK zur�ck.
FORCE_XP_DISCONNECT
Der Remotetransportanbieter sollte seine Verbindung mit den Messagingsystemressourcen freigeben. Danach sollte das STATUS_OFFLINE Bit in der eigenschaft PR_STATUS_CODE festgelegt und S_OK zurückgegeben werden.
PROCESS_XP_HEADER_CACHE
Der Remotetransportanbieter sollte Remotenachrichten verarbeiten und alle verzögerten Nachrichten hochladen. Dazu muss der Transportanbieter die folgenden Eigenschaftswerte in der status Zeile des Anmeldeobjekts festlegen:
Legen Sie die eigenschaft PR_STATUS_STRING auf eine Zeichenfolge fest, die die status des Transportanbieters für den Benutzer angibt.
Legen Sie die STATUS_OUTBOUND_ENABLED und STATUS_OUTBOUND_ACTIVE Bits in der eigenschaft PR_STATUS_CODE fest.
Legen Sie die eigenschaft PR_REMOTE_VALIDATE_OK in der status Zeile des Transportanbieters auf FALSE fest.
Wenn ein anderer Vorgang ausgeführt wird (z. B. das Herunterladen von Headern), wenn ValidateState aufgerufen wird, sollte ValidateState MAPI_E_BUSY zurückgeben.
Führen Sie den Code zum Verarbeiten des REFRESH_XP_HEADER_CACHE-Flags aus, um die Anforderungen des Microsoft Exchange-Clients zu erfüllen.
REFRESH_XP_HEADER_CACHE
Der Remotetransportanbieter sollte alle neuen Nachrichtenheader aus dem Messagingsystem abrufen. Dazu muss der Transportanbieter folgendes tun:
Legen Sie die eigenschaft PR_STATUS_STRING auf eine Zeichenfolge fest, die die status des Transportanbieters für den Benutzer angibt.
Legen Sie die bits STATUS_INBOUND_ENABLED und STATUS_INBOUND_ACTIVE in der eigenschaft PR_STATUS_CODE fest.
Löschen Sie das STATUS_OFFLINE Bit in der eigenschaft PR_STATUS_CODE .
Legen Sie das STATUS_ONLINE Bit in der eigenschaft PR_STATUS_CODE fest.
Legen Sie die eigenschaft PR_REMOTE_VALIDATE_OK in der status Zeile des Transportanbieters auf FALSE fest.
SHOW_XP_SESSION_UI
Wenn Ihr Transportanbieter über eine Benutzeroberfläche zum Verarbeiten der Nachrichtenheader verfügt (z. B. ein Dialogfeld, das das Herunterladen von Nachrichten bestätigt), sollte dieses Dialogfeld angezeigt werden. Andernfalls kann ValidateState MAPI_E_NO_SUPPORT zurückgeben.
Wenn andere Flags als diese übergeben werden, sollte ValidateState MAPI_E_UNKNOWN_FLAGS zurückgeben.
Der Client ruft den Transportanbieter häufig an die IMAPIStatus::ValidateState-Methode auf. Während der Verarbeitung von ValidateState sollte der Transportanbieter keine Aktionen ausführen, die knappe Systemressourcen wie modem oder COM-Port zuordnen. Dies liegt daran, dass der MAPI-Spooler manchmal Warteschlangen bei mehreren Transportanbietern leeren muss. Der Client kann jedoch jederzeit die ValidateState-Methode eines beliebigen Transportanbieters aufrufen. Wenn Ihr Transportanbieter versucht, während der Verarbeitung von ValidateState eine knappe Ressource zuzuweisen, kann ein Fehler aufgrund eines Konflikts mit einem anderen Transportanbieter auftreten, den der MAPI-Spooler angewiesen hat, seine Warteschlangen zu leeren. Wenn Sie zulassen, dass alle knappen Ressourcenzuordnungen unter der Leitung des MAPI-Spoolers erfolgen, können Sie solche Konflikte vermeiden. Ihr Transportanbieter sollte die eigenschaft PR_REMOTE_VALIDATE_OK unterstützen, damit Clientanwendungen erkennen können, wenn Ihr Transportanbieter ausgelastet ist oder darauf wartet, dass der MAPI-Spooler eine Aktion initiiert.
Hinweise für Aufrufer
Da diese Methode andere potenziell langwierige Aufrufe verursachen kann, kann ValidateState MAPI_E_BUSY zurückgeben, um Sie darüber zu informieren, dass diese Methode auf den Abschluss eines anderen Vorgangs wartet. Warten Sie, bis der ausstehende Vorgang abgeschlossen ist, bevor Sie eine andere Aufgabe versuchen.
Sie haben die größte Kontrolle über Ihre Aufrufe von Transportanbietern status Objekten. Sie können ein oder mehrere Flags an ValidateState übergeben, die sich auf die Vorgänge des Transportanbieters auswirken. Beispielsweise gibt das ABORT_XP_HEADER_OPERATION-Flag an, dass der Benutzer die Überprüfung abgebrochen hat. Transportanbieter können entscheiden, MAPI_E_USER_CANCELED abbrechen oder fortsetzen.
Sie können das CONFIG_CHANGED-Flag bei einem Aufruf des status-Objekts eines Dienstanbieters oder des MAPI-Spoolers festlegen, um anzugeben, dass eine Konfigurationsoption geändert wurde. Sie können CONFIG_CHANGED verwenden, um einen Transportanbieter dynamisch neu zu konfigurieren. Wenn Sie CONFIG_CHANGED bei einem Aufruf des status-Objekts eines Dienstanbieters festlegen, antwortet der Anbieter mit einem Aufruf von IMAPISupport::SpoolerNotify, um den MAPI-Spooler über die Änderung zu benachrichtigen. Wenn Sie CONFIG_CHANGED für einen Aufruf des status Objekts des MAPI-Spoolers festlegen, ruft der Spooler IXPLogon::AddressTypes für jeden aktiven Transportanbieter auf. AddressTypes informiert den MAPI-Spooler über die unterstützten Adresstypen eines Transports. Einige Dienstanbieter zeigen auch eine Statusanzeige an, wenn die Überprüfung voraussichtlich lange dauern wird. Das Anzeigen einer Statusanzeige ist hilfreich, aber nicht erforderlich.
Wenn das SUPPRESS_UI-Flag festgelegt ist, kann keines der Konfigurationseigenschaftenblätter oder Statusdialogfelder angezeigt werden.