Outlook 2000 VBA Programmers Reference

Tuesday Nov 19th 2002 by Dwayne Gifford
Share:

Outlook 2000 VBA Programmers Reference Outlook automation guru Dwayne Gifford offers a complete guide to controlling the latest version of the Microsoft email client from within Visual Basic!

This information is based on Dwayne Gifford's book, Outlook 2000 VBA Programmers Reference

The Folders collection represents the available folders at any given level of the folder hierarchy. The concept of the Folders collection is recursive in nature, meaning that you can have as many levels of folders as you want. The screenshot below shows a typical folder hierarchy indicating the different folder levels.


Blow Up!

You can see that the Mailbox – Dwayne Gifford Folders collection contains a number of individual Folder objects, Calendar, Contacts, etc. Each folder can contain Outlook items and MAPIFolders.

The various properties, methods and events of the Folders collection and Folder object allow navigation to and manipulation of these folders and the items that they contain.

There are two ways to get a reference to a Folders collection. The first is through the NameSpace object. This will return the root Folders collection

Syntax:

Dim ofcFolders as Folders
Dim onMAPI as NameSpace

Set ofcFolders = onMAPI.Folders

The second is from a MAPIFolder object. This will return the Folders collection representing all folders contained by the specified MAPIFolder.

Dim ofcFolders as Folders
Dim ofFolder as MAPIFolder

Set ofcFolders = ofFolder.Folders

For example if we choose the Notes folder to be the MAPIFolder then the ofcFolders collection would contain all folders starting Level 2.

Add Method

The Add method will create and return a new MAPIFolder object in the current Folders collection.

Set MAPIFolderObject = FoldersCollection.Add(Name [, Type])
Name Data type Description
Name String Required, the name of the folder that you see in Outlook.
Type Long Optional, can be one of the OlDefaultFolder constants. If no type is supplied then the new MAPIFolder will inherit its Type from the parent MAPIFolder.

Valid OlDefaultFolder constants for this method are as follows:

Constant Value Description
olFolderCalendar 9 Creates a new Calendar folder
olFolderContacts 10 Creates a new Contacts folder
olFolderDrafts 16 Creates a new Drafts folder
olFolderInbox 6 Creates a new Inbox folder
olFolderJournal 11 Creates a new Journal folder
olFolderNotes 12 Creates a new Notes folder
olFolderTasks 13 Creates a new Tasks folder.

The following constants are not valid when trying to create a new folder:

Constant Value Description
olFolderDeletedItems 3 Represents a DeletedItems folder
olFolderOutbox 4 Represents a Outbox folder
olFolderSentMail 5 Represents a SentMail folder

Example:

Dim onMAPI As NameSpace
Dim ofChosenFolder As MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofChosenFolder = onMAPI.PickFolder
ofChosenFolder.Folders.Add "Inbox 2", olFolderInbox

In the above example, the user is prompted by the Pick Folder dialog to choose one of their folders. A new folder called "Inbox 2" is then created in the chosen. The figure below shows the newly created "Inbox 2" MAPIFolder in the original Inbox MAPIFolder.


Blow Up!

More details on the PickFolder method of the NameSpace object are given in chapter 6.

GetFirst Method

The GetFirst method allows you to navigate to the first MAPIFolder object in the referenced collection. If there is no MAPIfolder object in the collection then Nothing is returned.

Set MAPIFolderObject = FoldersCollection.GetFirst

It is always wise to first get a reference to the Folders collection before you use the Get methods on the collection.

Example:

Dim onMAPI As NameSpace
Dim ofRootFolder As Folders
Dim ofFirstFolder as MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofRootFolder = onMAPI.Folders
Set ofFirstFolder = ofRootFolder.GetFirst
MsgBox ofFirstFolder

This simple example first sets a reference to the root folders collection. It then uses the GetFirst method to get the first folder within this collection, having first declared it to be a MAPIFolder. Finally its name is displayed in a message box.

GetLast Method

The GetLast method works in a similar fashion to the GetFirst method except it will return the last MAPIFolder in the collection. If there are no folders in the collection it will return Nothing.

Set MAPIFolder = FoldersCollection.GetLast

GetNext Method

The GetNext method moves to the next MAPIFolder in the collection.

Set MAPIFolderObject = FoldersCollection.GetNext

Example:

Dim ofcPersonalFolders As Folders
Dim ofFolder As MAPIFolder
Set ofcPersonalFolders =
Application.GetNamespace("MAPI").Folders.GetFirst.Folders
Set ofFolder = ofcPersonalFolders.GetFirst
Do Until ofFolder Is Nothing
MsgBox ofFolder.Name
Set ofFolder = ofcPersonalFolders.GetNext
Loop

In the example above we walk through the folders of the first Folders collection within the Root folders collection for the current profile. For my profile the first collection within the root folder collection is my Personal Folder. A reference is first set to this folder and then the GetFirst and GetNext methods are used to move through each of the folders in this collection. A Do Until loop is employed to check when the end of the Folders collection is reached and the name of each folder is displayed in a message box.

GetPrevious Method

The GetPrevious method provides a way to move to a previous MAPIFolder object in the current collection

Set MAPIFolderObject = FoldersCollection.GetPrevious

Again, I hate to repeat myself but it is always wise to get a reference to the collection that you want to work with before you use any of the Get methods of the Folders collection.

Item Method

The Item method provides a way to reference a particular MAPIFolder. This can be achieved by using the index number of the MAPIFolder within the collection or by using the name of the MAPIfolder.

Set MAPIFolderObject = FoldersCollection.Item(Index)
Name Data type Description
Index Variant Required, either a long representing the position of the MAPIFolder object within the collection or its name as a string.

Example:

Dim onMAPI As NameSpace
Dim ofInbox As MAPIFolder
Dim ofFolder As MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofInbox = onMAPI.Folders.GetFirst.Folders.Item("Inbox")
Set ofFolder = onMAPI.Folders.GetFirst.Folders(2)

In this example we get references to two different folders. For the first variable, ofInbox, we pick the folder by its name. The second variable, ofFolder, is set to the second folder within the first folder in the root folders using the index of the folder. For my personal setup this gives me a reference to the Contacts folder, although this may differ for you. Because Item is the default method it is not necessary to type it explicitly, as shown in the last line of code.

Remove Method

The Remove method will take the MAPIFolder referenced by the index parameter and permanently remove it from the Folders collection.

FoldersCollection.Remove Index
Name Data type Description
Index Long Required, represents the position of the MAPIFolder object within the collection that you wish to remove.

Be aware that when a folder is removed with this method, it will remove ALL folders and items within that folder without providing a warning.

Example:

Dim onMAPI As NameSpace
Dim ofFolder As MAPIFolder
Dim iFor As Integer
Set onMAPI = Application.GetNamespace("MAPI")
Set ofFolder = onMAPI.GetDefaultFolder(olFolderInbox)
ofFolder.Folders.Add "Inbox 3", olFolderInbox
For iFor = 1 To ofFolder.Folders.count
If ofFolder.Folders.Item(iFor).Name = "Inbox 3" Then
ofFolder.Folders.Remove iFor
Exit For
End If
Next

In this example we first add a MAPIFolder to the ofFolder object. We then walk through the Folders collection to locate the MAPIFolder. Once we do locate it we use the Remove method to delete it from the collection and exit the For…Loop.

Application Property

The Application property returns the Application object for the Folders collection. This will be the Outlook Application object.

Set ApplicationObject = FoldersCollection.Application

Class Property

The Class property returns a unique value that identifies an object’s type. This will be one of the OlObjectClass constants and in this case will be olFolders or 15.

Long = FoldersCollection.Class

Count Property

The Count property returns a long integer representing the number of MAPIFolder objects in the collection.

Long = FoldersCollection.Count

Example:

Dim onMAPI As NameSpace
Dim ofcPersonalFolders As Folders
Dim ofFolder As MAPIFolder
Dim iFor As Integer
Set onMAPI = Application.GetNamespace("MAPI")
Set ofcPersonalFolders = onMAPI.Folders.Item("Mailbox – Dwayne
Gifford").Folders

For iFor = 1 To ofcPersonalFolders.Count Set ofFolder = ofcPersonalFolders.Item(iFor) MsgBox ofFolder.Name Next

In this example a reference is set to the Folders collection of the Mailbox – Dwayne Gifford folder. The Count property is then used to set the upper limit of the For…Next construct, which is used to display the name of each of the folders within the collection.

Parent Property

The Parent property returns the parent object of the Folders collection. This we either be the NameSpace object or a MAPIFolder object.

Set MAPIFolderObject= FoldersCollection.Parent

Session Property

The Session property returns the NameSpace object for the current collection. You should already have this object if you have a reference to a Folders collection.

Set NameSpaceObject = FoldersCollection.Session

For the Folders collection events to be fired it is necessary to use the WithEvents keyword and set a reference to a Folders collection within a sub that will be called before the event. For illustration purposes only I have set a reference to the Deleted Items folders collection.

Example:

Dim WithEvents ofcFolders As Folders
Private Sub Class_Initialize()
Set ofcFolders = Application.GetNamespace("MAPI"). _
GetDefaultFolder(olFolderDeletedItems).Folders
End Sub

FolderAdd Event

The FolderAdd event occurs when a new MAPIFolder object is added to a collection.

Sub FoldersCollection_FolderAdd(ByVal Folder As MAPIFolder)

Name Data type Description
Folder MAPIFolder The new MAPIFolder object that is being added to the Folders collection.

Example:

Private Sub ofcFolders_FolderAdd(ByVal Folder As MAPIFolder)
If Folder.UnReadItemCount <> 0 Then
MsgBox "This folder has unread items. You may _
want to reinstate it.", vbExclamation
End If
End Sub

In this example the user is warned if they delete a folder with unread items in it. Firstly ofcFolders is set to be the Deleted Items Folders collection. This will be called when an object based on this class is instantiated.

Within the FolderAdd event, a newly created folder is checked for unread items. If they exist, the user is warned.

FolderChange Event

The FolderChange event occurs when one of the MAPIFolder objects, in the chosen Folders collection, is changed.

Sub FoldersCollection_FolderChange(ByVal Folder As MAPIFolder)

Name Data type Description
Folder MAPIFolder The MAPIFolder object that is being changed to the Folders collection.

FolderRemove Event

The FolderRemove event occurs when one of the MAPIFolder objects is deleted from the chosen Folders collection.

Sub FoldersCollection_FolderRemove()

MAPIFolder Object

A MAPIFolder object is a container that can hold either folders or Outlook items, or more likely both. A reference to a MAPIFolder object can be set by using the:

GetDefaultFolder, GetFolderFromID and GetSharedDefaultFolder method s of the NameSpace object

Item, GetFirst, GetLast, GetNext and GetPrevious methods of a Folders collection

Syntax:

Set ofFolder = onMAPI.GetFolderFromID(sEntryID, sStoreID)

or

Set ofFolder = onMAPI.GetDefaultFolder(olFolderInbox)

or

Set ofFolder = onMAPI.GetSharedDefaultFolder(orRecipient, olFolderInbox)

or

Ser ofFolder = onMAPI.Folders.Item("Inbox")

or

set ofFolder = onMAPI.Folders.GetFirst

These methods are covered fully in chapter 6 and earlier in this chapter.

CopyTo Method

The CopyTo method takes the currently referenced MAPIFolder and makes a copy of it and its contents in the specified destination MAPIFolder.

MAPIFolderObject.CopyTo(DestinationFolderObject)

Name Data type Description
DestinationFolderObject MAPIFolder Required, the Folder object that you wish to hold the copy in

Example:

Dim onMAPI As NameSpace
Dim ofStart As MAPIFolder
Dim ofDestination As MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofStart = onMAPI.GetDefaultFolder(olFolderInbox)
Set ofDestination = onMAPI.GetDefaultFolder(olFolderOutbox)
ofStart.CopyTo ofDestination

In this example we are creating a copy of the Inbox folder in the Outbox folder. If there is already a folder called Inbox here then the method will add a sequence number to the end of the new object. The CopyTo method is likely to be used to create back-ups of important folders.

Delete Method

The Delete method provides a way to remove a MAPIFolder object. It will delete this MAPIFolder object from its parent Folders collection.

MAPIFolderObject.Delete

This method works in the same way as the delete option on the GUI. However, if the folder is located within the Deleted Items folder, there is no warning massage or option to cancel the delete.

Display Method

The Display method displays a new Explorer for the MAPIFolder with the current object as the active MAPIFolder. An Explorer is an Outlook window that shows the contents of a folder. So if you already have an Outlook window open for the user, this method will open a new Outlook window in front of the user with the contents of the specified MAPIFolder visible. It will not make any changes to the old Explorer. The Explorer object is fully covered in chapter 7.

MAPIFolderObject.Display

Example:

Dim onMAPI As NameSpace
Dim ofFolder As MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofFolder = onMAPI.GetDefaultFolder(olFolderInbox)
ofFolder.Display

In the above example the ofFolder variable is set to the default Inbox folder. Then a new Explorer object is opened with this MAPIFolder object as the active folder.

GetExplorer Method

The GetExplorer method returns an invisible Explorer object that has the specified MAPIFolder object as its active folder. Once you have this Explorer object you can use the Activate method of the Explorer object to show it.

MAPIFolderObject.GetExplorer([DisplayMode])

Name Data type Description
DisplayMode Long Optional, one of the OlFolderDisplayMode constants. If omitted olFolderDisplayNormal is use by default.

The result of using each of the OlFolderDisplayMode constants is shown below.

OlFolderDisplayFolderOnly (1) displays, next to the Folder name, a drop-down list of folders available. All navigation buttons are also available. Notice the figure below has all navigation buttons on the toolbar.


Blow Up!

olFolderDisplayNoNavigation (2) displays the current MAPIFolder and the user is unable to navigate to any other MAPIFolder object. Notice that the navigational buttons on the toolbar are invisible.


Blow Up!

olFolderDisplayNormal (0) displays the Explorer just as it appears when you open Outlook.


Blow Up!

Example:

Dim onMAPI As NameSpace
Dim ofFolder As MAPIFolder
Dim oeExplorer As explorer
Set onMAPI = Application.GetNamespace("MAPI")
Set ofFolder = onMAPI.GetDefaultFolder(olFolderDrafts)
Set oeExplorer = ofFolder.GetExplorer(olFolderDisplayNoNavigation)
oeExplorer.Activate

This code was used to show the second Explorer object in the set of three above, displaying the default Drafts folder with no folder navigation available. The Activate method of the Explorer object is used to show the MAPIFolder to the user. Note that the optional display mode parameter only comes into play when the Explorer object methods are used to show it and not the Display method of the MAPIFolder.

MoveTo Method

The MoveTo method moves a MAPIFolder to a specified MAPIFolder object.

MAPIFolderObject.CopyTo(DestinationFolderObject)

Name Data type Description
DestinationFolderObject MAPIFolder Required, the destination Folder object that you wish to move the FolderObject to.

Application Property

The Application property will return the parent application object of the MAPIFolder object. This will be the Outlook Application object.

Set ApplicationObject = MAPIFolderObject.Application

Class Property

The Class property returns a unique value that identifies the object’s type. This will be one of the OlObjectClass constants and in this case will be olFolder or 2.

Long = MAPIFolderObject.Class

DefaultItemType Property

The DefaultItem property returns the default item type for the MAPIFolder. This property specifies what type of Outlook item a folder possesses by default, i.e. if you create a new item without supplying the Type then its type will be set according to the DefaultItemType of the folder it is added to.

Long = MAPIFolderObject.DefaultItemType

The value returned will be one of the following OlItemType contants:

Constant Value Description
olAppointmentItem 1 An Appointment item
olContactItem 2 A Contact item
olJournalItem 4 A Journal item
olMailItem 0 A Mail item. This is the default item for Outlook and the default type for all MAPIFolder objects that hold Mail type Items.
olNoteItem 5 A Note item
olPostItem 6 A Post item
olTaskItem 3 A Task Item

DefaultMessageClass Property

The DefaultMessageClass property returns, as a string, the Message Class, or type of message, for the MAPIFolder. This is the MessageClass property that, if not otherwise explicitly set, is assigned to an Outlook item by default when added to a folder. This value identifies the default Inspector object in which an item will be shown.

String = MAPIFolderObject.DefaultMessageClass

The possible values that will be returned are as follows:

IPM.Activity IPM.Appointment IPM.Contact
IPM.Note IPM.StickyNote IPM.Task

There is a one to one relationship between this property and the DefaultItemType property

Example:

Dim onMAPI As NameSpace
Dim ofcRoot As Folders
Dim ofPersonalFolder As MAPIFolder
Dim ofcPFolders As Folders
Dim ofFolder As MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofcRoot = onMAPI.Folders
Set ofPersonalFolder = ofcRoot.Item("Mailbox – Dwayne Gifford")
Set ofcPFolders = ofPersonalFolder.Folders

For Each ofFolder In ofcPFolders
Debug.Print ofFolder.Name, ofFolder.DefaultMessageClass, ofFolder.DefaultItemType
Next

This example walks through my Personal folders and displays both the DefaultMessageClass and DefaultItemType properties in the Immediate Window. The results are shown below.

Folder Name DefaultMessageClass DefaultItemType
Calendar IPM.Appointment

1

Contacts IPM.Contact

2

Deleted Items IPM.Note

0

Drafts IPM.Note

0

Inbox IPM.Note

0

Journal IPM.Activity

4

Notes IPM.StickyNote

5

Outbox IPM.Note

0

Sent Items IPM.Note

0

Tasks IPM.Task

3

Description Property

The Description property sets or returns a string value that provides information about the MAPIFolder. This property can be viewed in the Description box that you see in the Properties box for the MAPIFolder. For compatibility it corresponds to the PR_COMMENT property used in MAPI.


Blow Up!

String = MAPIFolderObject.Description

MAPIFolderObject.Description = String

I would suggest that if you are creating important MAPIFolders through code on a user’s machine then it is worth using this Description property to tell the user the purpose of the folder and that it should not be deleted.

EntryID Property

The EntryID property returns a unique ID for the MAPIFolder. It is created when the MAPIFolder is created or moved to a different folder. It may be used in conjunction with the GetFolderFromID method of the NameSpace object.

String = MAPIFolderObject.EntryID

This property is here for backwards compatibility with MAPI.

Folders Property

The Folders property returns the collection of folders that belong to the specified MAPIFolder, i.e. the sub-folders of the current object.

Set FoldersCollection = MAPIFolderObject.Folders

These Folders collections are recursive in nature, i.e. any one of the MAPIFolder objects in the Folders collection can contain its own Folders collection. The only way to ensure that you are at the bottom of a hierarchy of folders is to check that the Count property of the Folders collection equals 0.

Items Property

The Items property returns the collection of items within the specified MAPIFolder object.

Set ItemsCollection = MAPIFolderObject.Items

From this collection we have the ability to navigate around and work with the various Outlook Items. The Items collection and each of the Outlook items are covered fully in chapters 12 to 18.

Name Property

The Name property returns a string that represents the name of the MAPIFolder object. You can also set the name value using this property. The Name property of the folders is shown when you view the Outlook folders hierarchy.

String = MAPIFolderObject.Name

MAPIFolderObject.Name = String

If, within a particular Folders collection, you try to set the Name property of a MAPIFolder to the name of an already existing MAPIFolder an error will be raised.

Parent Property

The Parent property returns the parent object for the current object. In this case since we are looking at a MAPIFolder object the parent will the MAPIFolder object directly above it in the folders hierarchy.

Set MAPIFolderObject = MAPIFolderObject.Parent

UnReadItemCount Property

The UnReadItemCount property returns a long integer representing the number of messages within the current MAPIFolder that have not been read.

Long = MAPIFolderObject.UnReadItemCount

StoreID Property

The StoreID property returns a unique ID of the MAPIFolder object. This value is set when the object is created or moved to a new Folders collection. It is not clear why two unique ID’s, i.e. the EntryID and the StoreID are required.

String = MAPIFolderObject.StoreID

Session Property

The Session property returns the NameSpace object for the current session. This will be the MAPI.

Set NameSpaceObject = MAPIFolderObject.Session

WebViewAllowNavigation Property

The WebViewAllowNavigation property returns or sets a Boolean value indicating the "navigation mode" for the Web view.

Boolean = MAPIFolderObject.WebViewAllowNavigation

MAPIFolderObject.WebViewAllowNavigation = Boolean

By setting this to True the user has ability to use the Back and Forward buttons for Web navigation.

WebViewOn Property

The WebViewOn property returns or sets a Boolean value indicating the Web "view state" for the current MAPIFolder object. If set to True then Outlook is told to display the Web page specified in the WebViewURL property.

Boolean = MAPIFolderObject.WebViewOn

MAPIFolderObject.WebViewOn = Boolean

WebViewURL Property

The WebViewURL property returns or sets a string value indicating the URL of the web page assigned to this MAPIFolder object.

String = MAPIFolderObject.WebViewURL

MAPIFolderObject.WebViewURL = String


This information is based on Dwayne Gifford's book, Outlook 2000 VBA Programmers Reference

Share:
Home
Mobile Site | Full Site
Copyright 2017 © QuinStreet Inc. All Rights Reserved