IXPProvider::TransportLogon
Gilt für: Outlook 2013 | Outlook 2016
Richtet eine Sitzung ein, in der sich eine Clientanwendung bei einem Transportanbieter anmeldet.
HRESULT TransportLogon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG FAR * lpulFlags,
LPMAPIERROR FAR * lppMAPIError,
LPXPLOGON FAR * lppXPLogon
);
Parameter
lpMAPISup: [in] Zeiger auf das Supportobjekt des Transportanbieters für Rückruffunktionen in MAPI für diese Sitzung. Dieses Objekt bleibt gültig, bis es vom Transportanbieter freigegeben wird.
ulUIParam: [in] Handle to the parent window of any dialog boxes or windows this method displays. Der ulUIParam-Parameter kann nicht NULL sein, z. B. wenn das LOGON_SETUP-Flag im lpulFlags-Parameter festgelegt ist.
lpszProfileName: [in] Zeiger auf den Profilnamen des Benutzers. Der lpszProfileName-Parameter wird hauptsächlich verwendet, wenn ein Dialogfeld angezeigt werden muss.
lpulFlags: [in, out] Bitmaske von Flags, die steuert, wie die Anmeldesitzung eingerichtet wird. Die folgenden Flags können beim Eingeben durch den MAPI-Spooler festgelegt werden:
LOGON_NO_CONNECT: Das Benutzerkonto wird bei diesem Transportanbieter für andere Zwecke als die Übertragung und den Empfang von Nachrichten angemeldet. Der Transportanbieter sollte nicht versuchen, Verbindungen mit anderen Messagingsystemen herzustellen.
LOGON_NO_DIALOG: Es sollte kein Dialogfeld angezeigt werden, auch wenn die aktuell gespeicherten Benutzeranmeldeinformationen ungültig oder nicht für die Anmeldung geeignet sind.
LOGON_NO_INBOUND: Der Transportanbieter muss nicht für den Empfang von Nachrichten initialisieren und sollte keine eingehenden Nachrichten akzeptieren. Der MAPI-Spooler kann später die IXPLogon::TransportNotify-Methode verwenden, um dem Transportanbieter zu signalisieren, dass die Verarbeitung eingehender Nachrichten aktiviert wird.
LOGON_NO_OUTBOUND: Der Transportanbieter muss zum Senden von Nachrichten nicht initialisieren, da der MAPI-Spooler keine bereitstellt. Wenn eine Clientanwendung während der Zusammenstellung einer Nachricht eine Verbindung mit einem Remoteanbieter erfordert, damit sie IXPLogon::AddressTypes-Methodenaufrufe durchführen kann, sollte der Transportanbieter die Verbindung herstellen. Der MAPI-Spooler kann TransportNotify verwenden, um dem Transportanbieter zu signalisieren, wenn ausgehende Vorgänge beginnen können.
MAPI_UNICODE: Die übergebene Zeichenfolge für den Profilnamen weist das Unicode-Format auf. Wenn das MAPI_UNICODE-Flag nicht festgelegt ist, weist die Zeichenfolge das ANSI-Format auf.
Die folgenden Flags können bei der Ausgabe durch den Transportanbieter festgelegt werden:
LOGON_SP_IDLE: Fordert an, dass der MAPI-Spooler häufig die IXPLogon::Idle-Methode des Transportanbieters für die Leerlaufzeitverarbeitung aufruft.
LOGON_SP_POLL: Fordert an, dass der MAPI-Spooler häufig die IXPLogon::P oll-Methode für das zurückgegebene Anmeldeobjekt aufruft, um nach neuen Nachrichten zu suchen. Wenn dieses Flag nicht festgelegt ist, sucht der MAPI-Spooler nur nach neuen Nachrichten, wenn der Transportanbieter die IMAPISupport::SpoolerNotify-Methode verwendet, um den Spooler zu benachrichtigen, dass neue Nachrichten zu verarbeiten sind. Ein Transportanbieter wird effektiv nur senden, indem er dieses Flag nicht festlegt und den MAPI-Spooler nicht über den Nachrichtenempfang benachrichtigt.
LOGON_SP_RESOLVE: Fordert an, dass der MAPI-Spooler in vollständig aufgelöst wird, adressiert alle Nachrichtenadressen für Empfänger, die von diesem Transportanbieter nicht unterstützt werden. Daher kann der Transportanbieter einen Antwortpfad für alle Empfänger erstellen.
MAPI_UNICODE: Die zurückgegebenen Zeichenfolgen in der MAPIERROR-Struktur liegen ggf. im Unicode-Format vor. Wenn das MAPI_UNICODE-Flag nicht festgelegt ist, liegen die Zeichenfolgen im ANSI-Format vor.
lppMAPIError: [out] Zeiger auf einen Zeiger auf die zurückgegebene MAPIERROR-Struktur , falls vorhanden, die Versions-, Komponenten- und Kontextinformationen für den Fehler enthält. Der Parameter lppMAPIError kann auf NULL festgelegt werden, wenn keine MAPIERROR-Struktur zurückgegeben werden soll.
lppXPLogon: [out] Zeiger auf den Zeiger auf das zurückgegebene Transportanbieter-Anmeldeobjekt.
Rückgabewert
S_OK: Der Aufruf war erfolgreich und hat den erwarteten Wert oder die erwarteten Werte zurückgegeben.
MAPI_E_FAILONEPROVIDER: Dieser Anbieter kann sich nicht anmelden, aber dieser Fehler sollte den Dienst nicht deaktivieren.
MAPI_E_UNCONFIGURED: Das Profil enthält nicht genügend Informationen, damit die Anmeldung abgeschlossen werden kann. MAPI ruft die Einstiegspunktfunktion des Nachrichtendiensts des Anbieters auf.
MAPI_E_UNKNOWN_CPID: Der Anbieter kann die Codepage des Clients nicht unterstützen.
MAPI_E_UNKNOWN_LCID: Der Anbieter kann die Gebietsschemainformationen des Clients nicht unterstützen.
MAPI_E_USER_CANCEL: Der Benutzer hat den Vorgang abgebrochen, in der Regel durch Klicken auf die Schaltfläche Abbrechen in einem Dialogfeld.
Hinweise
Der MAPI-Spooler ruft die IXPProvider::TransportLogon-Methode auf, um eine Anmeldesitzung für einen Benutzer einzurichten.
Die meisten Transportanbieter verwenden die IMAPISupport::OpenProfileSection-Methode , die mit dem Supportobjekt bereitgestellt wird, auf das der lpMAPISup-Parameter verweist, um Benutzeridentitätsinformationen, Serveradressen und Anmeldeinformationen zu speichern und abzurufen. Mithilfe von OpenProfileSection kann ein Transportanbieter beliebige Informationen speichern und sie einer bestimmten Ressource zuordnen. Beispielsweise kann ein Anbieter OpenProfileSection verwenden, um den Kontonamen und das Kennwort zu speichern, die einer bestimmten Sitzung zugeordnet sind, sowie alle Servernamen oder anderen erforderlichen Informationen, die für den Zugriff auf Ressourcen für diese Sitzung erforderlich sind. MAPI blendet Informationen, die einer Ressource zugeordnet sind, vor externem Zugriff aus. Der profilabschnitt, der über lpMAPISup zur Verfügung gestellt wird, wird vom MAPI-Spooler verwaltet, sodass Daten, die sich auf diesen Benutzerkontext beziehen, von Daten für andere Kontexte getrennt werden.
Der Transportanbieter muss die IUnknown::AddRef-Methode für das Supportobjekt aufrufen und eine Kopie des Zeigers auf dieses Objekt als Teil des Anbieteranmeldeobjekts beibehalten.
Der Profilanzeigename in lpszProfileName wird bereitgestellt, damit der Transportanbieter ihn in Fehlermeldungen oder Anmeldedialogfeldern verwenden kann. Wenn der Anbieter diesen Namen beibehält, muss er in den vom Anbieter zugeordneten Speicher kopiert werden.
Transportanbieter, die eng mit anderen Dienstanbietern verbunden sind, müssen möglicherweise bei der Anmeldung zusätzliche Arbeit leisten, um die für Vorgänge zwischen Begleitanbietern erforderlichen guten Anmeldeinformationen zu ermitteln.
In der Regel werden Transportanbieter geöffnet, wenn sich der Benutzer zum ersten Mal bei einem Profil anmeldet. Da die erste Anmeldung bei einem Profil daher in der Regel vor der Anmeldung bei einem Nachrichtenspeicher erfolgt, ruft der MAPI-Spooler in der Regel TransportLogon auf, wobei sowohl die LOGON_NO_INBOUND- als auch LOGON_NO_OUTBOUND-Flags in lpulFlags festgelegt sind. Wenn später die entsprechenden Nachrichtenspeicher in der Profilsitzung verfügbar sind, ruft der MAPI-Spooler TransportNotify auf, um eingehende und ausgehende Vorgänge für den Transportanbieter zu initiieren.
Das Übergeben des LOGON_NO_CONNECT-Flags in lpulFlags signalisiert den Offlinebetrieb des Transportanbieters. Dieses Flag gibt an, dass keine externen Verbindungen hergestellt werden sollen. Wenn der Transportanbieter keine Sitzung ohne externe Verbindung einrichten kann, sollte er einen Fehlerwert für die Anmeldung zurückgeben.
Ein Transportanbieter sollte das LOGON_SP_IDLE-Flag in lpulFlags zum Zeitpunkt der Initialisierung festlegen, wenn er für die Verwendung von Zeit konzipiert ist, die das System andernfalls im Leerlauf verbringt. Diese Zeit wird häufig für die Verarbeitung automatischer Vorgänge verwendet, z. B. automatisches Herunterladen von Nachrichten, zeitbasiertes Herunterladen von Nachrichten oder übermittlung von Nachrichten mit Zeit. Wenn dieses Flag festgelegt ist, ruft der MAPI-Spooler den Leerlauf auf, wenn die Leerlaufzeit des Systems eintritt, um solche Vorgänge zu initiieren. Der MAPI-Spooler ruft den Leerlauf nicht in festgelegten Intervallen auf. stattdessen wird es nur während der tatsächlichen Leerlaufzeit aufgerufen. Daher sollten Anbieter nicht davon ausgehen, wie häufig ihre Idle-Methoden aufgerufen werden. Anbieter, die Leerlaufzeitvorgänge unterstützen, sollten eine Konfigurationsbenutzeroberfläche dafür in ihrem Anbietereigenschaftenblatt bereitstellen.
Wenn die Anmeldung des Transportanbieters erfolgreich ist, sollte der Anbieter im lppXPLogon-Parameter einen Zeiger auf ein Anmeldeobjekt zurückgeben. Der MAPI-Spooler verwendet dieses Objekt für zusätzlichen Anbieterzugriff. Wenn TransportLogon ein Anmeldedialogfeld anzeigt und der Benutzer die Anmeldung in der Regel durch Klicken auf die Schaltfläche Abbrechen im Dialogfeld abbricht, sollte der Anbieter MAPI_E_USER_CANCEL zurückgeben.
Für die meisten Fehlerwerte, die von TransportLogon zurückgegeben werden, deaktiviert MAPI die Nachrichtendienste, zu denen der Anbieter gehört. MAPI ruft für den Rest der MAPI-Sitzung keine Anbieter auf, die zu diesem Dienst gehören. Wenn TransportLogon hingegen den MAPI_E_FAILONEPROVIDER Fehlerwert aus der Anmeldung zurückgibt, deaktiviert MAPI nicht den Nachrichtendienst, zu dem der Anbieter gehört. TransportLogon sollte MAPI_E_FAILONEPROVIDER zurückgeben, wenn ein Fehler auftritt, der die Deaktivierung des Diensts für den Rest der Sitzung nicht rechtfertigen kann.
Wenn ein Anbieter MAPI_E_UNCONFIGURED von seiner Anmeldung zurückgibt, ruft MAPI die Eintragsfunktion des Nachrichtendiensts des Anbieters auf und wiederholt dann die Anmeldung. MAPI übergibt MSG_SERVICE_CONFIGURE als Kontext, um dem Dienst die Möglichkeit zu geben, sich selbst zu konfigurieren. Wenn der Client sich dafür entschieden hat, eine Benutzeroberfläche für die Anmeldung zuzulassen, kann der Dienst sein Konfigurationseigenschaftenblatt anzeigen, sodass der Benutzer Konfigurationsinformationen eingeben kann.
Wenn der Anbieter feststellt, dass sich nicht alle erforderlichen Informationen im Profil befinden, sollte er MAPI_E_UNCONFIGURED zurückgeben, damit MAPI die Einstiegspunktfunktion des Nachrichtendiensts des Anbieters aufruft.