Starting a CDO Session
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:
Important Storing user names and passwords inside source code can lead to security vulnerabilities in your software. Do not store user names and passwords in your production code.
' 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 ' IMPORTANT: Storing user names and passwords inside source code ' can lead to security vulnerabilities in your software. Do not ' store user names and passwords in your production code. 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.