| Platform SDK: CDO 1.2.1 |
The Logon method logs on to the MAPI system.
objSession.Logon( [profileName] [, profilePassword] [, showDialog] [, newSession] [, parentWindow] [, NoMail] [, ProfileInfo] )
| Value | Action |
|---|---|
| True | Opens a new MAPI session (default). |
| False | Uses the current shared MAPI session. |
| Value | Action |
|---|---|
| True | The MAPI spooler is not informed of the session’s 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). |
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 object’s 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 user’s display name, but rather the alias or account name used internally by the user’s organization. For example, “johnd” 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:
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.
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