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.
See Also
Creating and Sending a Message