12.3 Accessing Outlook s contents | Microsoft Office Automation with Visual FoxPro

Accessing Outlook s contents

Look at the example in the previous section again. The first real line of code is fairly mysterious. It calls a method of the Application object named GetNameSpace, passing it a parameter called "MAPI." What s a NameSpace, and why does it want a "MAPI"?

This is one of those questions to which the correct answer is "because." If you look up the NameSpace object in the Outlook VBA Help file, the first sentence says, "Represents an abstract root object for any data source." Not very helpful, is it? Reading on, you find out that the only data source Outlook supports is "MAPI," which is the Mail Application Programming Interface and includes all the data stored in Outlook. Bottom line NameSpace is simply an object that provides a gateway to the rest of the Outlook data. Perhaps at some point, Outlook s designers imagined that they d support a variety of data stores.

We re not sure why you have to actively call GetNameSpace to load the data instead of having it loaded when Outlook starts up. But you do, so just get used to doing it automatically.

Once you get past that point, things get a little more interesting. The NameSpace object provides access to the Folder objects that are the heart of Outlook. There are a couple of ways into those Folders. You can simply climb down the hierarchy. NameSpace has a Folders collection that contains one or more items, depending on your configuration. For a stand-alone user, the only item in the collection is "Personal Folders." With Exchange Server available, the collection may also contain "Public Folders" and "Mailbox" items. Those folders each have their own Folders collections that contain a folder for each of the individual applets within Outlook. There are folders for Calendar, Tasks, Inbox, Outbox, Contacts, and so forth. You can access them, like this, if you ve saved the reference to the NameSpace object in oNameSpace, as shown previously:

oCalendar = oNameSpace.Folders[1].Folders["Calendar"]

oInbox = oNameSpace.Folders[1].Folders["Inbox"]

and so forth.

However, there s a simpler way to get to the individual folders. NameSpace has a method, GetDefaultFolder, to which you can pass an appropriate constant, and receive in return a reference to the specified folder. Table 1 shows the constants for the 10 types of folders that Outlook supports.

Table 1. Outlook folders. These constants represent the 10 primary folder types in Outlook. Pass them to GetDefaultFolder to access Outlook s data.

Constant	Value	Constant	Value
olFolderDeletedItems	3	olFolderContacts	10
olFolderOutbox	4	olFolderJournal	11
olFolderSentMail	5	olFolderNotes	12
olFolderInbox	6	olFolderTasks	13
olFolderCalendar	9	olFolderDrafts	16

To use this approach, call the method like this:

#DEFINE olFolderTasks 13

#DEFINE olFolderContacts 10

oTasks = oNameSpace.GetDefaultFolder( olFolderTasks )

oContacts = oNameSpace.GetDefaultFolder( olFolderContacts )

Once you have the folder for one of the Outlook applets, you can explore its contents. Each folder contains a collection of items, but the details vary significantly. We ll look at the ones we think you re most likely to want to automate here, but we won t explore all 10 in depth. If you need to work with the others, the Outlook VBA Help file should tell you what you need to know. (Actually, once you get the hang of it, looking up the specific properties isn t that big a deal.)

Once you reach the folder for a given Outlook applet, you still have to climb down through an Items collection to reach the actual contents. For example, to find out how many tasks are in the Tasks folder, you d check:

? oTasks.Items.Count

New items of each type are created using Application s CreateItem method. You pass it a constant (or the actual value) for the kind of item you want to create, and it adds a member to the appropriate folder. Table 2 shows the constants to pass to CreateItem.

Table 2. Creating new items. The CreateItem method adds data. Pass one of these constants to create an item of the specified type.

Constant	Value	Constant	Value
olMailItem	0	olJournalItem	4
olAppointmentItem	1	olNoteItem	5
olContactItem	2	olPostItem	6
olTaskItem	3	olDistributionListItem	7

For example, to create a new appointment, issue this call:

oAppt = oOutlook.CreateItem( olAppointmentItem )

Then, you can modify the properties of the new appointment such as Start, End, AllDayEvent, and so forth to properly enter it into the Calendar. Other types of items are handled similarly.

Once you ve filled in the properties of the item, call its Save method to save it in the appropriate collection. Anytime you change a property, you need to call Save again to have your changes saved.

You can remove an item by calling its Delete method. This method moves the item to the DeletedItems folder, from which it can be resurrected, if necessary, but will be cleaned up, in due course. (The DeletedItems folder can be set to be emptied automatically on exit or, like the Recycle Bin, can be emptied manually.)