Logon Method (Session Object)
Logon Method (Session Object)
The Logon method logs on to the MAPI system.
Syntax
objSession.Logon( [profileName] [, profilePassword**] [, showDialog] [, newSession] [, parentWindow] [, NoMail] [, ProfileInfo] )**
objSession
Required. The Session object.
profileName
Optional. String. Specifies the profile name to use. To prompt the user to select a profile name, omit profileName and set showDialog to True. The default value is an empty string. The profileName parameter is ignored if the ProfileInfo parameter is supplied.
profilePassword
Optional. String. Specifies the profile password. To prompt the user to enter a profile password, omit profilePassword and set showDialog to True. The default value is an empty string. The profilePassword parameter is ignored on all Win32 platforms.
showDialog
Optional. Boolean. If True, displays a Choose Profile dialog box. The default value is True.
newSession
Optional. Boolean. Determines whether the application opens a new MAPI session or uses the current shared MAPI session. The default value is True. If a shared MAPI session does not exist, newSession is ignored and a new session is opened. If a shared MAPI session does exist, this parameter governs the following actions:
Value |
Action |
True |
Opens a new MAPI session (default). |
False |
Uses the current shared MAPI session. |
parentWindow
Optional. Long. Specifies the parent window handle for the logon dialog box. A value of zero (the default) specifies that the dialog box should be application-modal. A value of 1 specifies that the currently active window is to be used as the parent window. The parentWindow parameter is ignored unless showDialog is True.
NoMail
Optional. Boolean. Determines whether the session should be registered with the MAPI spooler. This parameter governs the following actions:
Value |
Action |
True |
The MAPI spooler is not informed of the sessions existence, and no messages can be sent or received except through a tightly coupled message store and transport. |
False |
The session is registered with the MAPI spooler and can send and receive messages through spooling (default). |
ProfileInfo
Optional. String. Contains the server and mailbox names that Logon should use to create a new profile for this session. The profile is deleted after logon is completed or terminated. The ProfileInfo parameter is only used by applications interfacing with Microsoft® Exchange Server. The profileName parameter is ignored if ProfileInfo is supplied.
Remarks
The user must log on before your application can use any MAPI object, any other CDO Library object, or even any other method or property of the Session object. An attempt to access any programming element prior to a successful Logon results in an CdoE_NOT_INITIALIZED error return. The only exception to this rule is the Session objects SetLocaleIDs method.
The Choose Profile dialog box is always modal, meaning the parent window is disabled while the dialog box is active. If the parentWindow parameter is set to zero or is not set, all windows belonging to the application are disabled while the dialog box is active. If the parentWindow parameter is supplied but is not valid, the call returns CdoE_INVALID_PARAMETER.
If your application cannot obtain the handle for the currently active window, for example if it is running in VBScript, you can pass 1 in the parentWindow parameter. CDO then retrieves the handle from the Microsoft Windows® GetActiveWindow function and uses it as the parent window handle.
The common MAPI dialog boxes automatically handle many of the error cases that can be encountered during logon. When you call Logon and do not supply the optional profile name parameter, the Choose Profile dialog box appears, asking the user to select a profile. When the profileName parameter is supplied but is not valid, common dialog boxes indicate the error and prompt the user to enter a valid name from the Choose Profile dialog box. When no profiles are defined, the Profile Wizard takes the user through the creation of a new profile.
The ProfileInfo parameter is used to create a temporary profile for the session. CDO generates a random name for the profile. For an authenticated profile, the format of the string is <server name> & vbLf & <mailbox name> where the server and mailbox names can be unresolved. Note that the mailbox name is not the messaging users display name, but rather the alias or account name used internally by the users organization. For example, john should be used instead of John Doe.
For an anonymous profile, the format is <server distinguished name> & vbLf & vbLf & "anon" where the distinguished name of the server takes the form /o=<enterprise>/ou=<site>/cn=Configuration/cn=Servers/cn=<server> and any text between the vbLf characters is ignored. At least the /cn=<server> entry is required; if it is not specified in the ProfileInfo parameter, Logon returns CdoE_INVALID_PARAMETER.
If you log on with an anonymous profile, the Name property of the AddressEntry object returned by the CurrentUser property contains "Unknown default".
If both profileName and ProfileInfo are supplied, profileName is ignored and the random profile name is used.
The Logon method does not verify the validity of either the server name or the mailbox name in the ProfileInfo parameter. You can get a successful return even if you specify one or both of these names incorrectly. In this case the CurrentUser property returns the value Unknown. If you log on using ProfileInfo, you should attempt to open the Inbox folder to verify that you can access the message store.
If your application calls the Logon method after the user has already successfully logged on to the same session, CDO generates the error CdoE_LOGON_FAILED. However, you can create multiple sessions and log on simultaneously each of them.
A session is terminated by the Logoff method.
For more information, see Starting a CDO Session.
The following methods can invoke dialog boxes:
- Details method (AddressEntry object)
- Options and Send methods (Message_olemsg_Message_object object)
- Resolve method (Recipient object)
- Resolve method (Recipients collection)
- AddressBook and Logon methods (Session object)
However, if your application is running as a Microsoft® Windows NT® service, for example from Active Server Pages (ASP) script on a Microsoft® Internet Information Server (IIS), no user interface is allowed.
For more information on running as a service, see "Windows NT Service Client Applications" in the MAPI Programmer's Reference under Guide, Introduction to MAPI Programming, Operating Environment Issues.
Example
The first part of this code fragment displays a Choose Profile dialog box that prompts the user to enter a profile password. The second part supplies the profileName parameter and does not display the dialog box:
Dim objSession As MAPI.Session
' (part 1) from the function Session_Logon
Set objSession = CreateObject("MAPI.Session")
If Not objSession Is Nothing Then
objSession.Logon showDialog:=True
End If
' (part 2) from the function Session_Logon_NoDialog
Function Session_Logon_NoDialog()
On Error GoTo error_actmsg
' can set strProfileName, strPassword from a custom form
' adjust these parameters for your configuration
' create a Session object if necessary here ...
If Not objSession Is Nothing Then
' configure these parameters for your needs ...
objSession.Logon profileName:=strProfileName, _
showDialog:=False
End If
Exit Function
error_actmsg:
If 1273 = Err Then ' VB4.0: If Err.Number = CdoE_LOGON_FAILED Then
MsgBox "Cannot log on: incorrect profile name or password; " _
& "change global variable strProfileName in Util_Initialize"
Exit Function
End If
MsgBox "Error " & Str(Err) & ": " & Error$(Err)
Resume Next
End Function