Starting a CDO Session

As described in CDO Library Object Design, all messaging objects are relative to the Session object. The first task of every application is to create a valid Session object and call its Logon method. No other method or property of the Session object can be accessed, and no other CDO Library object can be created, until the application has successfully logged on. The only exception to this rule is the Session object's SetLocaleIDs method.

The Session object is created using the Microsoft® Visual Basic® function CreateObject. The following code demonstrates how to perform this common startup task:

Function Util_CreateSessionAndLogon() As Boolean 
Dim objSession As MAPI.Session ' use early binding for type checking 
On Error GoTo err_CreateSessionAndLogon 
 
Set objSession = CreateObject("MAPI.Session") 
' call objSession.SetLocaleIDs here if you need to change your locale 
objSession.Logon 
Util_CreateSessionAndLogon = True 
Exit Function 
 
err_CreateSessionAndLogon: 
If (Err = 1275) Then ' VB4.0: If Err.Number = CdoE_USER_CANCEL Then 
    MsgBox "User pressed Cancel" 
Else 
    MsgBox "Unrecoverable Error:" & Err 
End If 
Util_CreateSessionAndLogon = False 
Exit Function 
 
End Function

The way you deal with errors depends on your version of Visual Basic. For more information, see Handling Errors.

When no parameters are supplied to the Logon method, as in the example above, the CDO Library displays an application-modal logon dialog box that prompts the application user to select a user profile. Based on the characteristics of the selected profile, the underlying MAPI system logs on the user or prompts for password information.

You can also choose to use your own application's dialog box to obtain the parameters needed to log on, rather than using the MAPI logon dialog box. The following example obtains the profile name and password information and directs the Logon method not to display a logon dialog box:

' Function: Session_Logon_NoDialog 
' Purpose: Call the Logon method, set parameter to show no dialog 
' See documentation topic: Logon Method (Session object) 
Function Session_Logon_NoDialog() 
Dim objSession As MAPI.Session 
On Error GoTo error_olemsg 
' can set strProfileName, strPassword from a custom form 
' adjust these parameters for your configuration 
If objSession Is Nothing Then 
    Set objSession = CreateObject("MAPI.Session") 
End If 
If Not objSession Is Nothing Then 
    objSession.Logon profileName:=strProfileName, _ 
                     showDialog:=False 
End If 
Exit Function 
 
error_olemsg: 
If 1273 = Err Then ' VB4.0: If Err.Number = CdoE_LOGON_FAILED Then 
    MsgBox "Cannot logon: incorrect profile name or password" 
    Exit Function 
End If 
MsgBox "Error " & Str(Err) & ": " & Error$(Err) 
Resume Next 
End Function

Note Your Visual Basic application should be able to handle cases that occur when a user provides incorrect profile or password information, or when a user cancels from the logon dialog box. For more information, see Handling Errors. For a listing of CDO Library and MAPI error values, see Error Codes.

After establishing a Session object and successfully logging on to the system, the user has access to several default objects provided by the Session object, including the Inbox and Outbox folders. For more information, see Reading a Message from the Inbox.

Starting a CDO Session

See Also