The Outlook Object Model

Although VBScript allows you only to program an Outlook form, it nevertheless gives you relatively complete access to the Outlook object model, which is shown in Figure 6-6. Since the object model is fairly large, we'll focus only on some of its highlights here, and in particular on those objects that you are most likely to use when programming an Outlook form.You can explore the Outlook object model by opening the object browser in the VBScript editor, or by using the Object Browser included with the VBA-integrated development environment.

Figure 6-6. The Outlook object model

Note that when you're attempting to access the Outlook object model using VBScript, the context of your script is the current item, which can be represented by the Item keyword. In other words, as your script is executing, the Item object is the current object; to access other objects in the object model, you have to navigate to them from the Item object.

This also means that a reference to the current item is assumed in any attempt to navigate the object model or access a particular object, property, or method. For example, the code:

MsgBox Item.Application.Version

is identical to the code:

MsgBox Application.Version

This second line of code is interpreted as an attempt to retrieve the value of the Application object of the current item, and to retrieve its Version property.

If you're making extensive use of the properties and methods of other objects, your script's performance can be enormously improved by establishing references to those objects. For example, if your script involves accessing the object representing the form's current page, rather than having to navigate downward through the object model each time you want to access it, you can define an object reference, as the following code does:

Dim objPage
Set objApp = Item.Application

You could then use the objApp object variable to access the controls on the page.

Although the Outlook Application object is a global object in VBA (that is, its properties and methods can be called without prefacing them with a reference to the Application object), this is not true of VBScript. In VBScript, you must explicitly reference the Application object in order to access its members.

6.5.1 The Current Item

The current item that the form displays is represented by one of the item object types listed in Table 6-1. You can determine the object type by passing a reference to it to the VBA TypeName function. For example:

strClass = TypeName(Me)

or:

strClass = TypeName(Item)

where Item is an Outlook/VBScript keyword representing the current item.

You can call the general properties and methods that are suitable for any item (see Tables Table 6-3 and Table 6-4, respectively), as well as the properties and methods appropriate for an item of that particular type. The latter, unfortunately, are too numerous to mention in this chapter.

Table 6-3. General item properties

Property	Description
Actions[1]	Returns the Actions collection, which consists of one Action object for each custom action defined for the item.
Application	Returns a reference to the Application object, Outlook's top-level object.
Attachments	Returns the Attachments collection, which consists of the Attachment objects stored to the item.
BillingInformation	A read-write string intended to hold billing information associated with the item.
Body	A read-write string containing the item's body text.
Categories	A read-write string containing the categories assigned to the item. If multiple categories are present, they are separated from one another by a comma and a space.
Class	A read-only value represented by a member of the OlObjectClass enumeration that indicates the item's class.
Companies	A read-write string designed to contain information about the company or companies associated with the item.
ConversationIndex	Returns the index of the item's conversation thread.
ConversationTopic	Returns the topic of the item's conversation thread.
CreationTime	Returns the date and time that the item was created.
EntryID	Returns the item's identifier, which is unique to the items in a particular folder.
FormDescription	Returns a FormDescription object that describes the form used to display the item.
GetInspector	Returns an Inspector object that represents the window pane that contains the item.
Importance	A read-write constant of the OlImportance enumeration; indicates the item's importance. Enumeration members: olImportanceHigh (2), olImportance Low (0), and olImportanceNormal (1).
LastModificationTime	Date and time the item was last modified.
Links	Returns the read-only collection of Link objects representing contacts to which the item is linked.
MessageClass	A read-write string indicating the item's message class, which links it to a particular Outlook form.
Mileage	A read-write string field designed to store the mileage associated with an item for purposes of reimbursement.
NoAging	A read-write Boolean that indicates whether the item should not be aged.
OutlookInternalVersion	A read-only Long containing the build number of Outlook associated with the item.
OutlookVersion	A read-only string containing the major and minor version of Outlook associated with the item.
Parent	Returns a reference to the item's parent object.
Saved	A read-only flag that indicates whether the item has not been modified since it was last saved.
Sensitivity	A constant of the OlSensitivity enumeration (olConfidential, olNormal, olPersonal, or olPrivate) that indicates the item's sensitivity.
Session	Returns the Namespace object for the current session.
Size	Returns the item's size in bytes.
Subject	A string containing the subject of the item. It is the default member of all item types. In the case of NoteItem objects, it is read-only and is calculated from the content of the NoteItem object's Body property.
Unread	A read-write flag indicating if the item hasn't been opened.
UserProperties	Returns the UserProperties collection representing all the item's user properties.

[1] Does not apply to the NoteItem object.

Table 6-4. General item methods

Method	Description
Close	Closes the item and its inspector and optionally saves changes. Its syntax is Item.Close(SaveMode) where SaveMode is a constant of the OlInspectorClose enumeration (olDiscard, olPromptForSave, olSave).
Copy	Creates a copy of the object. The new object is returned by the method call.
Delete	Deletes the item.
Display	Displays the item in a new Inspector object. Its syntax is Item.Display(Modal) where Modal is a Boolean that indicates whether the Inspector should be modal; its default value is False.
Move	Moves the item to a new folder. Its syntax is Item.Move DestFldr where DestFldr is a reference to the MAPIFolder object to which the item should be moved.
PrintOut	Prints the item using the default settings.
Save	Saves the item to the current folder or, in the case of a new item, to the default folder for that type of item.
SaveAs	Saves the item to a specified location in a specified format. Its syntax is Item.SaveAs Path, [Type] where Path is the path to the location in which the item should be saved, and the optional Type parameter is a constant of the OlSaveAsType enumeration: olDoc, olHTML, olMSG (the default), olRTF, olTemplate, olTXT, olVCal, or olVCard.

6.5.2 The Inspector Object

The Inspector object represents the window in which a particular Outlook item is displayed. A reference to the current item's Inspector object is returned by its GetInspector property. The Inspector object supports the properties shown in Table 6-5 and the methods shown in Table 6-6.

Table 6-5. Properties of the Inspector object

Property	Description
Application	Returns a reference to the Application object, Outlook's top-level object.
Caption	A read-only string that defines the caption in the inspector's titlebar.
Class	A read-only value that indicates the inspector's class. Its value is always olInspector, or 35.
CommandBars	Returns a reference to the CommandBars collection, which represents all the menus and toolbars available to the inspector.
CurrentItem	Returns the current item that the inspector is displaying.
EditorType	A read-only member of the OlEditorType enumeration: olEditorHTML (2), olEditorRTF (3), olEditorText (1), or olEditorWord (4).
Height	A read-write value that determines the height in pixels of the inspector window.
HTMLEditor	Returns the HTML Document Object Model of the displayed message. This property is valid only if the value of EditorType is olEditorHTML. In addition, since the object reference returned by this property is temporary, it should not be stored for later use.
Left	A read-write value that determines the distance in pixels between the left edge of the screen and the left edge of the inspector window.
ModifiedFormPages	Returns the Pages collection, which consists of the pages of the current form.
Parent	Returns a reference to the inspector's parent object, which is the Outlook Application object.
Session	Returns the NameSpace object for the current session.
Top	A read-write value that determines the distance in pixels between the top edge of the screen and the top edge of the inspector window.
Width	A read-write value that determines the width in pixels of the inspector window.
WindowState	A read-write constant of the OlWindowState enumeration (olMaximized, 1; olMinimized, 2; olNormal, 3) that determines the state of the inspector's window.
WordEditor	Returns the Word Document Object Model of the displayed message. This property is valid only if the value of EditorType is olEditorWord. In addition, since the object reference returned by this property is temporary, it should not be stored for later use.

Table 6-6. Methods of the Inspector object

Method	Description
Activate	Brings the inspector window to the foreground and gives it the focus.
Close	Closes the inspector window and optionally saves changes to the current item. Its syntax is oInspector.Close(SaveMode) where SaveMode is a constant of the OlInspectorClose enumeration (olDiscard, olPromptForSave, or olSave).
Display	Displays a new Inspector object for the item. Its syntax is Inspector.Display(Modal) where Modal is a Boolean that indicates whether the Inspector should be modal; its default value is False.
HideFormPage	Hides a page of the form displayed in the inspector. Its syntax is oInspector.HideFormPage PageName where PageName is a string that designates the name of the page to be hidden.
IsWordMail	Returns a Boolean that specifies whether the mail message associated with an inspector is displayed in an inspector or in Microsoft Word. If True, the value of the inspector's EditorType property is olEditorWord.
SetCurrentFormPage	Displays a particular page of the current form. Its syntax is oInspector.SetCurrentFormPage PageName where PageName is the name of the page to be displayed.
ShowFormPage	Shows a form page in the inspector. Its syntax is oInspector.ShowFormPage PageName where PageName is a string containing the name of the page to be shown.

6.5.3 The Pages Collection

The Pages collection represents the pages in the form that you want to access in order to customize. The Pages collection is returned by theModifiedFormPages property of the Inspector object. Initially, the Pages collection is empty. Individual form pages are added to the collection either explicitly, by calling the collection's Add method, or implicitly, by referencing a control on one of the forms.

The Pages collection supports the properties shown in Table 6-7 and the methods listed in Table 6-8.

Table 6-7. Properties of the Pages collection

Property	Description
Application	Returns a reference to the Application object, Outlook's top-level object.
Class	A read-only value that indicates the page's class. Its value is always olPages, or 36.
Count	A read-only value that indicates the number of pages in the Pages collection.
Parent	Returns a reference to the collection's parent object, which is the Inspector object in which the form is displayed.
Session	Returns the NameSpace object for the current session.

Table 6-8. Methods of the Pages collection

Method	Description
Add	Adds a new page to the Pages collection. Its syntax is oPages.Add Name where Name is the name of the page to be added. The method returns a reference to the added page. Initially, the pages collection is empty, and there is a limit of five customizable pages per form.
Item	Retrieves an individual page from the Pages collection. Its syntax is oPages.Item Index where Index is either the one-based ordinal position of the page in the Pages collection or the name of the page.
Remove	Removes a page from the collection. Its syntax is oPages.Remove Index where Index is the one-based ordinal position of the page in the Pages colletion.

6.5.4 The FormDescription Object

The FormDescription object represents the form used to display a particular item in an inspector. It is returned by the current item'sFormDescription property. The FormDescription object has 22 properties (shown in Table 6-9) and a single method (shown in Table 6-10).

Table 6-9. Properties of the FormDescription object

Property	Description
Application	Returns a reference to the Application object, Outlook's top-level object.
Category	The category assigned to the form description. It corresponds to the Category drop-down list box on the form's Properties page in design mode.
CategorySub	The subcategory assigned to the form description. It corresponds to the Sub-Category dropdown list box on the form's Properties page in design mode.
Class	A read-only value that indicates the form description's class. Its value is always olFormDescription, or 37.
Comment	Sets or returns the comment associated with the form description. It corresponds to the Description text box on the form's Properties page in design mode.
ContactName	Sets or returns the name of the person to contact for information regarding the custom form. It corresponds to the Contact text box on the form's Properties page in design mode.
DisplayName	Defines the text that will be used to name the form in the Choose Forms dialog. Setting the DisplayName property also sets the Name property if it is empty (and vice versa).
Hidden	Determines whether a custom form is hidden (i.e., it does not appear in the Choose Form dialog box and is used only if designated as the response form for another custom form). Its default value is False; custom forms are not hidden. This property corresponds to the "Use form only for responses" checkbox on the form's Properties page in design mode.
Icon	Contains the name of the icon file to be displayed for the form. By default, its value is a temporary icon file generated by Outlook and placed in the Windows temporary directory.
Locked	Determines whether the form is read-only. Its default value is False; the form is read-write. It corresponds to the "Protect form design" checkbox on the form's Properties page in design mode.
MessageClass	The form's message class, which links the form to the type of items it can display.
MiniIcon	Contains the name of the icon file to be displayed for the form. By default, its value is a temporary icon file generated by Outlook and placed in the Windows temporary directory.
Name	The name of the form. This property must be set before calling the PublishForm method.
Number	Defines the number for the form. It corresponds to the Form Number text box on the form's Properties page in design mode.
OneOff	Determines whether the form is discarded after one-time use (True) or retained as a custom form (False). Its default value is False.
Parent	Returns a reference to the form's parent object, which is the item that the form displays.
Password	Sets or returns the password needed to modify the form. It is retrievable programmatically as clear text.
ScriptText	Returns a string containing all the VBScript code attached to the form.
Session	Returns the NameSpace object for the current session.
Template	Sets or returns the name of the Word template (*.dot file) for use with the form.
UseWordMail	A Boolean that determines whether Microsoft Word is the default editor for the form.
Version	Returns or sets the version number. It corresponds to the Version text box on the form's Properties page in design mode.

Table 6-10. Method of the FormDescription object

Method

Description

PublishForm

Saves the form definition. Its syntax is oFormDescription.PublishForm(Registry,[Folder]) where Registry determines the location to which the form should be saved and can be olDefaultRegistry (0), olFolderRegistry (3), olOrganizationRegistry (4), or olPersonalRegistry (2). If Registry is olFolderRegistry, Folder is a reference to a MAPIFolder object that defines the folder to which the form will be published.

6.5.5 The NameSpace Object

The NameSpace object represents the root object for accessing Outlook data. In other words, from an Outlook form, the NameSpace object is important because it gives access to the MAPIFolder objects that comprise Outlook's folder system.

The NameSpace object is returned by theGetNameSpace ("MAPI") method of the Application object. It has the properties shown in Table 6-11 and the methods listed in Table 6-12.

Table 6-11. Properties of the NameSpace object

Property	Description
AddressLists	Returns a collection of address lists available for the session.
Application	Returns a reference to the Application object, Outlook's top-level object.
Class	A read-only value that indicates the NameSpace object's class. Its value is always olNamespace, or 1.
CurrentUser	Returns a Recipient object representing the currently logged in user.
Folders	Returns the Folders collection, which represents all the Folder objects contained in the NameSpace.
Parent	Returns a reference to the namespace's parent object, which is the Application object.
Session	Returns the NameSpace object for the current session.
SyncObjects	Returns a collection containing all synchronization profiles.
Type	Returns the string "MAPI" to indicate the type of the NameSpace object.

Table 6-12. Methods of the NameSpace object

Method	Description
AddStore	Adds a personal folder file (.pst) to the current profile. Its syntax is oNameSpace.AddStore Store where Store is the path and name of the .pst file.
CreateRecipient	Creates and returns a Recipient object. Its syntax is oNameSpace.CreateRecipient RecipientName where RecipientName is the display name of the recipient.
GetDefaultFolder	Returns a MAPIFolder object that represents the default folder of a particular type. Its syntax is oNameSpace.GetDefaultFolder FolderTypeEnum where FolderTypeEnum is a member of the OlDefaultFolders enumeration: olFolderCalendar (9). oFolderContacts (10), oFolderDeletedItems (3), oFolderDrafts (16), oFolderInbox (6), oFolderJournal (11), oFolderNotes (12), oFolderOutbox (4), oFolderSentMail (5), oFolderTasks (13).
GetFolderFromID	Returns the MAPIFolder object that has a particular ID. Its syntax is oNamespace.GetFolderFromID(EntryIDFolder, [StoreID]) where EntryIDFolder is a string containing the folder's entry ID, and StoreID is an optional string containing the folder's store ID. These values are accessible through MAPI and CDO.
GetItemFromID	Returns the item in a folder that has a particular ID. Its syntax is oNameSpace.GetItemFromID(EntryIDItem, [StoreID]) where EntryIDItem is a string containing the item's entry ID, and StoreID is an optional string containing the item's store ID. These values are readily accessible through MAPI and CDO.
GetRecipientFromID	Returns a Recipient object that has a particular ID. Its syntax is oNameSpace.GetRecipientFromID(EntryID) where EntryID is a string containing the recipient's entry ID. This value is readily accessible through MAPI and CDO.
GetSharedDefaultFolder	Returns the MAPIFolder object that represents a particular type of default folder for a specified user. This method is most useful when one user has given another user access to one or more default folders. Its syntax is: oNameSpace.GetSharedDefaultFolder(RecipientObject, FolderTypeEnum) where RecipientObject is a Recipient object representing the owner of the folder, and FolderTypeEnum is a constant from the OlDefaultFolder enumeration (see the GetDefaultFolder method for a list of its members).
Logoff	Logs the user off from the current MAPI session.
Logon	Logs the user onto MAPI and begins a MAPI session. Its syntax is oNameSpace.Logon [Profile] [Password], [ShowDialog], [NewSession] where Profile is the name of the profile to use for the session, Password is an optional (and usually omitted) string containing the password associated with the profile, ShowDialog is an optional Boolean that indicates whether the MAPI logon dialog should be displayed if Profile is incorrect or unavailable, and NewSession is an optional Boolean that determines whether a new session should be created even if there is an existing session. (Within Outlook, however, multiple sessions are not supported.)
PickFolder	Displays the Pick Folder dialog and returns the MAPIFolder object representing the folder selected by the user. If the user cancels the dialog, the method returns Nothing.

6.5.6 The MAPIFolder Object

Given a reference to a MAPIFolder object, you can begin to programmatically manipulate the items that the folder contains. MAPIFolder objects are returned by the NameSpace object's Folders property, as well as by itsGetDefaultFolder,GetSharedDefaultFolder, and PickFolder methods.

The properties of the MAPIFolder object are shown in Table 6-13, while its methods appear in Table 6-14.

Table 6-13. Properties of the MAPIFolder object

Property	Description
Application	Returns a reference to the Application object, Outlook's top-level object.
Class	A read-only value that indicates the NameSpace object's class. Its value is always olFolder, or 2.
DefaultItemType	Returns the default Outlook item type that the folder stores. It can be one of the following OlItemType constants: olAppointmentItem (1), olContactItem (2), olJournalItem (4), olMailItem (0), olNoteItem (5), olPostItem (6), or olTaskItem (3).
DefaultMessageClass	A read-only string containing the default message class of items in the folder.
Description	A read-write string containing the folder's description. It corresponds to the Description text box in the folder's Properties dialog.
EntryID	Returns the folder's unique entry ID that was assigned by MAPI when the folder was created.
Folders	Returns the Folders collection, which contains one Folder object for each subfolder in the current folder.
Items	Returns the collection of items in the folder.
Name	The name of the folder.
Parent	Returns a reference to the folder's parent object, which is either the MAPI NameSpace object or a MAPIFolder object.
Session	Returns the NameSpace object for the current session.
StoreID	Returns or sets the folder's StoreID.
UnReadItemCount	A read-only value; indicates the number of unread items.
WebViewAllowNavigation	A Boolean that determines whether the user can navigate using the Back and Forward buttons.
WebViewOn	A Boolean that determines whether Outlook displays the web page specified by the WebViewURL property.
WebViewURL	A string containing the web page assigned to the folder.

Table 6-14. Methods of the MAPIFolder object

Method	Description
CopyTo	Copies the current folder. Its syntax is oFolder.CopyTo(DestFldr) where DestFldr is a MAPIFolder object representing the destination folder.
Delete	Deletes the folder.
Display	Displays a new Explorer object for the folder.
GetExplorer	Returns a new inactive Explorer object in which the current folder is the folder whose GetExplorer method is called. The method is useful for creating a new Explorer object to display a folder rather than changing the folder displayed in the active Explorer. Its syntax is GetExplorer([DisplayMode])where DisplayMode is an optional constant of the OlFolderDisplayMode enumeration; its members are olFolderDisplayFolderOnly (1), olFolderNoNavigation (2), or olFolderDisplayNormal (0, the default).
MoveTo	Moves the current folder.

6.5.7 Outlook Constants

The object model for Outlook 2000 defines 275 constants in 49 different enumerations. Unfortunately, though they are available to Outlook VBA, they are not available to VBScript. If you want to use the constants defined in Outlook's type library, you'll need to define them yourself using the Const statement. In addition, however, VBScript does not support the Enum statement, which allows you to define a group of constants. So you'll have to define each constant separately, as in the following code, which makes the members of the OlInpectorClose enumeration available to a script:

Const olDiscard = 1
Const olPromptForSave = 2
Const olSave = 0

In general, it's best to define all constants with global scope, which makes them available everywhere in your script.