IABProvider::Logon
Gilt für: Outlook 2013 | Outlook 2016
Stellt eine Verbindung mit einer aktiven Sitzung her.
HRESULT Logon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR lpszProfileName,
ULONG ulFlags,
ULONG FAR * lpulcbSecurity,
LPBYTE FAR * lppbSecurity,
LPMAPIERROR FAR * lppMAPIError,
LPABLOGON FAR * lppABLogon
);
Parameter
lpMAPISup
[in] Ein Zeiger auf das Supportobjekt des Adressbuchanbieters.
ulUIParam
[in] Ein Handle für das übergeordnete Fenster für das Anmeldedialogfeld, das von der Logon-Methode angezeigt wird, sofern dies zulässig ist. Der ulUIParam-Parameter enthält den Wert des Parameters mit demselben Namen, der im vorherigen Aufruf der MAPILogonEx-Funktion an MAPI übergeben wurde.
lpszProfileName
[in] Ein Zeiger auf den Namen des Sitzungsprofils.
ulFlags
[in] Eine Bitmaske von Flags, die steuert, wie die Anmeldung ausgeführt wird. Die folgenden Flags können festgelegt werden:
AB_NO_DIALOG
Der Anbieter sollte während der Anmeldung kein Dialogfeld anzeigen. Wenn dieses Flag nicht festgelegt ist, kann der Anbieter ein Dialogfeld anzeigen, in dem der Benutzer zur Eingabe fehlender Konfigurationsinformationen aufgefordert wird.
MAPI_DEFERRED_ERRORS
Ermöglicht die erfolgreiche Rückgabe der Anmeldung , möglicherweise bevor der Anmeldevorgang abgeschlossen ist.
MAPI_UNICODE
Alle Zeichenfolgen sollten im Unicode-Format vorliegen. Wenn das MAPI_UNICODE-Flag nicht festgelegt ist, sollten die Zeichenfolgen im ANSI-Format vorliegen.
lpulcbSecurity
[in, out] Ein Zeiger auf die Größe der Struktur der Sicherheitsanmeldeinformationen in Bytes, auf die der Parameter lppbSecurity verweist. Bei der Eingabe muss der Wert ungleich 0 (null) sein. bei der Ausgabe muss der Wert 0 (null) sein. In beiden Fällen müssen die Zeiger gültig sein.
lppbSecurity
[in, out] Ein Zeiger auf einen Zeiger auf Sicherheitsanmeldeinformationen. Bei der Eingabe muss der Wert ungleich 0 (null) sein. bei der Ausgabe muss der Wert 0 (null) sein. In beiden Fällen muss der Zeiger gültig sein.
lppMAPIError
[out] Ein Zeiger auf einen Zeiger auf eine MAPIERROR-Struktur . Der Parameter lppMAPIError kann auf NULL festgelegt werden, wenn keine MAPIERROR-Struktur zurückgegeben werden soll.
lppABLogon
[out] Ein Zeiger auf einen Zeiger auf das Anmeldeobjekt des Anbieters.
Rückgabewert
S_OK
Eine Verbindung mit einer aktiven Sitzung wurde erfolgreich hergestellt.
MAPI_E_FAILONEPROVIDER
Der Anbieter kann sich nicht anmelden, aber MAPI kann sich weiterhin bei den anderen Anbietern in dem Nachrichtendienst anmelden, zu dem der Anbieter gehört.
MAPI_E_UNCONFIGURED
Der Anbieter verfügt über unzureichende Informationen, um die Anmeldung abzuschließen. MAPI ruft die Eintragsfunktion des Nachrichtendiensts des Anbieters auf.
MAPI_E_UNKNOWN_CPID
Der Server ist nicht für die Unterstützung der Codepage des Clients konfiguriert.
MAPI_E_UNKNOWN_LCID
Der Server ist nicht für die Unterstützung der Gebietsschemainformationen des Clients konfiguriert.
MAPI_E_USER_CANCEL
Der Benutzer hat den Vorgang abgebrochen, in der Regel durch Klicken auf die Schaltfläche Abbrechen im Anmeldedialogfeld.
Hinweise
Connections werden mit jedem Adressbuchanbieter im Sitzungsprofil eingerichtet, wenn ein Client die IMAPISession::OpenAddressBook-Methode aufruft. OpenAddressBook ruft dann die Anmeldemethode jedes Anbieters auf.
Der Profilname, auf den der lpszProfileName-Parameter verweist, wird im Zeichensatz des Clients des Benutzers angezeigt, wie durch das Vorhandensein oder Fehlen des MAPI_UNICODE-Flags im ulFlags-Parameter angegeben.
Hinweise für Implementierer
Rufen Sie in Ihrer Implementierung der Logon-Methode die IMAPISupport::SetProviderUID-Methode auf, um einen eindeutigen Bezeichner oder eine MAPIUID-Struktur zu registrieren. Jedes Ihrer Objekte verfügt über einen Eintragsbezeichner, der diese MAPIUID enthält. MAPI verwendet die MAPIUID , um ein Objekt mit seinem Anbieter abzugleichen. Wenn beispielsweise ein Client die IMAPISession::OpenEntry-Methode aufruft, um einen Messagingbenutzer zu öffnen, untersucht OpenEntry den MAPIUID-Teil des übergebenen Eintragsbezeichners und gleicht ihn mit einer MAPIUID ab, die von einem Adressbuchanbieter registriert wurde.
Wenn sich ein Client mehrmals bei Ihrem Anbieter anmeldet, sollten Sie für jede Anmeldung eine andere MAPIUID registrieren. Durch das Registrieren eindeutiger MAPIUID-Strukturen kann MAPI Anforderungen ordnungsgemäß an den entsprechenden Anbieter instance weiterleiten. Möglicherweise möchten Sie jedoch, dass jedes Anmeldeobjekt eine MAPIUID gemeinsam verwendet. In diesem Fall müssen Sie in der Lage sein, das Routing selbst zu verarbeiten, anstatt sich auf MAPI zu verlassen. Weitere Informationen zum Erstellen einer MAPIUID finden Sie unter Registrieren eindeutiger Dienstanbieterbezeichner.
Das Unterstützungsobjekt, das MAPI an Ihre Logon-Methode im lpMAPISup-Parameter übergibt, bietet Zugriff auf viele der Methoden, die in der IMAPISupport: IUnknown-Schnittstelle enthalten sind. MAPI erstellt ein Unterstützungsobjekt, das an Ihren Anbietertyp angepasst ist. Wenn Sie sich beispielsweise beim Herstellen der Verbindung bei einem zugrunde liegenden Messagingsystem oder Verzeichnisdienst anmelden müssen, können Sie die IMAPISupport::OpenProfileSection-Methode aufrufen, um Sicherheitsanmeldeinformationen für diese bestimmte Anmeldesitzung abzurufen.
Wenn die Anmeldung erfolgreich ist, stellen Sie sicher, dass Sie die IUnknown::AddRef-Methode des Supportobjekts aufrufen, um die Verweisanzahl zu erhöhen. Dadurch kann Ihr Anbieter den Supportobjektzeiger für den Rest der Sitzung beibehalten. Wenn Sie diese AddRef-Methode nicht aufrufen, entlädt MAPI Ihren Anbieter.
Sie können den Profilnamen, der im lpszProfileName-Parameter übergeben wird, in Fehlerdialogfelder, Anmeldebildschirme oder andere Benutzeroberflächen einschließen. Um den Profilnamen zu verwenden, kopieren Sie ihn in den von Ihnen zugewiesenen Speicher.
Erstellen Sie ein Anmeldeobjekt, und geben Sie im Parameter lppABLogon einen Zeiger darauf zurück. MAPI verwendet dieses Anmeldeobjekt, um aufruft die Methoden in Ihrer IABLogon-Implementierung .
Wenn Sie während der Anmeldung ein Kennwort benötigen, zeigen Sie ein Anmeldedialogfeld nur an, wenn das flag AB_NO_DIALOG nicht festgelegt ist. Wenn der Benutzer den Anmeldevorgang abbricht, in der Regel durch Klicken auf die Schaltfläche Abbrechen im Dialogfeld, kehren Sie MAPI_E_USER_CANCEL von Anmeldung zurück.
Wenn sich ein Adressbuchanbieter nicht anmelden kann, deaktiviert MAPI in der Regel den Nachrichtendienst, zu dem der fehlerhafte Anbieter gehört. Das heißt, MAPI versucht für den Rest der Sitzungslebensdauer keine Verbindungen für andere Anbieter herzustellen, die zum Dienst gehören. Wenn Ihr Anbieter jedoch keine Verbindung herstellen kann und Sie nicht den gesamten Dienst deaktivieren möchten, geben Sie entweder MAPI_E_FAILONEPROVIDER oder MAPI_E_UNCONFIGURED zurück. MAPI deaktiviert nicht den Nachrichtendienst, zu dem der Anbieter gehört.
Geben Sie MAPI_E_FAILONEPROVIDER zurück, wenn ein Fehler auftritt, der nicht schwerwiegend genug ist, um zu verhindern, dass die anderen Anbieter im Nachrichtendienst Verbindungen herstellen. Geben Sie MAPI_E_UNCONFIGURED zurück, wenn die erforderlichen Konfigurationsinformationen im Profil fehlen und Sie kein Dialogfeld anzeigen können, um den Benutzer aufzufordern. MAPI antwortet, indem sie die Einstiegspunktfunktion Ihres Anbieters für den Nachrichtendienst aufruft, wobei MSG_SERVICE_CONFIGURE als ulContext-Parameter festgelegt ist, um dem Dienst die Möglichkeit zu geben, sich selbst zu konfigurieren, entweder programmgesteuert oder mithilfe eines Eigenschaftenblatts. Wenn die Einstiegspunktfunktion des Nachrichtendiensts abgeschlossen ist, wiederholt MAPI die Anmeldung.