A Quick Start to Interfacing with Outlook

This is an article and demo application that show how to setup for Outlook integration using the COMSDK and VO2Outlook for VO 2.7b-1. The application will show Mail, Appointments, and Tasks and will have a DLL version of VO2Outlook and the COMSDK. You will be sending emails from your VO applications through Outlook in 15 minutes or less.

Some history and motivation

Frans de Wit and I started our COM-project a long time ago, back when the trigger was the poor support for COM and OLE in VO and some things we wanted to do with Outlook that VO did not support. This mainly had to do with events and data types that were not supported such as the Date-time values Outlook needs to set things like reminders. As it turned out Frans got very interested in the COM-concepts and ended up writing a very complete COM Class-library called the COMSDK. On top of that VO2Outlook was born allowing us to do what we needed, but admittedly also was very technical. Although we did provide some Getting Started documentation and Samples, because of the complexity of the COM libraries, it was not real easy to get started.

The goal was to make VO2Outlook a lot easier to incorporate into existing applications

Also VO 2.7 came along, requiring some changes, so there were a few good reasons to re-think VO2Outlook a bit to see if we could change it to support a larger audience. This is why I decided to write a new sample application and this article as well as work with Frans to create a COMSDK version that would be easy to use. It is also the next incarnation of the COMSDK, not only based on VO 2.7 but also with support for writing COM-servers (out of proc (.exe) and in proc (.dll)) with optionally multiple interfaces. The goal was to make VO2Outlook a lot easier to incorporate into existing applications.

This was not an easy task, because a lot of additional functionality for things like memory management, error handling and debugging is built into the library, but it can get in the way of existing functionality like your own error handler. I won’t go into details here, but Frans has added functions to turn off the error handler, not show warnings or errors and control how the error logging takes place.

Getting Started

So now for the good news: it is very easy to start using VO2Outlook now. You need only two DLL’s and their prototypes. I’ve taken the liberty to rename them for the sake of simplicity. The COMSDK, which used to be several libraries, is now compacted into one (SOCOMSDK.DLL) with the accompanying prototype. So copy the DLL into you bin-directory and import SOCOMSDK DLL.Aef. The same for VO2Outlook: copy the DLL into the bin-directory and import VO2Outlook DLL.AEF. Add both to your list of libraries and you are good to go. This way it is also much easier when we update our DLL’s … you should be able to just replace them.

I have not bothered about a setup or install. I figure every VO developer knows how to handle two DLL’s and three AEF-files. Three AEF’s you say? Yes three! The third AEF, VO2OutlookDemo.aef, is a demo application that shows how to send or display emails, create appointment items and create task items or task requests.

The DLL’s have been compiled using VO 2.7 build 2741 (=2.7b1). If you are using an earlier version of 2.7 (not recommended!) I have included SOCOMSDK.AEF and VO2Outlook.AEF, so you can import and compile the DLL’s yourself.

VO2Outlook Demo

The demo application assumes Outlook is installed and setup properly. This means that you have verified you can use Outlook to receive and send mail and you have a default Task folder and Calendar.

The app is just one single dialog that hosts a tab control with several tab pages for the different tasks that are demonstrated. The most obvious use for VO2Outlook is sending mail messages, but it goes without saying that you actually have access to the full object-model Outlook exposes which can actually do a lot more than just sending mail.

The first thing an application needs to do is create a reference to the Outlook application-object. You can do this yourself, or use the one provided for you in VO2Outlook. Of course this is what the demo-app does. Here’s the Compose method for the Mail page, responsible for the actual creation of the Mail Item using that method:

METHOD ComposeMail() CLASS MailPage

LOCAL oOutlook    AS TS_UIOutlook
// Reference to outlook automation object
LOCAL oMailItem   AS TS_OutlookMailItem
// VO2Outlook class for MaitItems

BEGIN SEQUENCE
oOutLook:=TS_UIOutlook{}                                     

IF oOutlook <> NULL_OBJECT
// Create a new Item in default 'Outbox' (Calling
// CMSave on it will store it in Drafts folder)
  oMailItem := oOutlook:Application:CreateMailItem()
  IF oMailItem<>NULL_OBJECT
    oMailItem:CABody := SELF:oDCBody:Textvalue
    oMailItem:CASubject := SELF:oDCSubject:Textvalue
    IF ! Empty( SELF:oDCToAddresses:TextValue )
      oMailItem:CARecipients:CMAdd(;
        SELF:oDCToAddresses:TextValue)
    ENDIF    
  ENDIF
ENDIF
END SEQUENCE
RETURN oMailItem

The code “oOutLook:=TS_UIOutlook{}” is the piece that creates our object and has a reference to Outlook. The property called Application is the actual reference to the Outlook Application class as documented in the Outlook VBA-documentation. It is the top-level class in the Outlook object model.

In VO2Outlook we have added a method that creates a new Mail item, CreateMailItem. This returns a reference to an Outlook mailitem-object, again documented in the Outlook VBA-helpfile (for Outlook 2003 this is VBAOL11.CHM). There is only one difference: the methods in VO2Outlook are prefixed by “CM”, and the accesses and assigns by “CA”. So assigning the Body property becomes

     oMailItem:CABody := “TEXT”

and calling the Add method, for example on the Recipients collection is

    oMailItem:CARecipients:CMAdd(  SELF:oDCToAddresses:TextValue).
This is the way how you add a TO-email address to an Outlook mailitem. Adding CC’s or BCC’s requires a reference to the just added object and setting the appropriate properties:

oRec := oMailItem:CARecipients:CMAdd(Ed@comsdk.com)
oRec:CAType := 2 // (olCC)

I have copied all Outlook constants into a separate module in the demo-app, but you can also look them up in the before mentioned helpfile.

If you are not sure of the validity of the entered email addresses, you can also call Resolve (so CMResolve in VO2Outlook) to check if Outlook thinks they are ok. When ok, the property  (CA)Resolved will return true.

After resolving all recipients and composing the email by setting the other properties you are ready to either send or display the item. You can also save the item without sending, which will store the item in the draft folder. Below are the Display and Send methods.                      

METHOD Display( ) CLASS MailPage
// VO2Outlook class for MaitItems
LOCAL oMailItem AS TS_OutlookMailItem
oMailItem := SELF:ComposeMail()
IF oMailItem # NULL_OBJECT
  oMailItem:CMDisplay()
ENDIF
RETURN SELF  
      
METHOD SendMail( ) CLASS MailPage
// VO2Outlook class for MaitItems
LOCAL oMailItem AS TS_OutlookMailItem
oMailItem := SELF:ComposeMail()
IF oMailItem # NULL_OBJECT
  oMailItem:CMSend()
ENDIF
RETURN SELF

This is how easy it is to start sending emails from your VO application using Outlook. The other options demonstrated in the app are creating a calendar item and creating tasks.

I’m sure the code for that will be self explanatory

I’m sure the code for that will be self explanatory.

Calendar items are included because of the special handling of date-time values.

Tasks are part of the demo because of the dual nature tasks can have in Outlook. You can create a simple task for yourself, to keep track and set reminders for example, but you can also send a task request to someone else. This will create the task in your task-folder, but sends an email to the recipient putting it in their task-list when they accept and automatically sending the sender updates when this task gets updated. This way you will automatically receive messages indicating progress or completion. This is a very nice and useful feature that can also be very interesting to integrate into your application.

I hope this article triggers you to go and try the COMSDK and VO2Outlook and remember that www.comsdk.com provides you with a full blown version, including all of the sourcecode.

Have fun!