Microsoft KB Archive/290804

= Programming examples for referencing items and folders in Outlook 2002 =

Article ID: 290804

Article Last Modified on 11/23/2006

-

APPLIES TO


 * Microsoft Outlook 2002 Standard Edition

-



This article was previously published under Q290804







For a Microsoft Outlook 98 version of this article, see 182614.



For a Microsoft Outlook 2000 version of this article, see 208520.



SUMMARY
The Microsoft Outlook object model is commonly used to access various types of items in folders. This article provides an overview of the various methods, properties, and objects that can be used to refer to Outlook items and folders.

This article summarizes the following topics:

Referencing Existing Folders
 * GetDefaultFolder Method
 * Folders Object
 * Parent Property
 * GetSharedDefaultFolder Method
 * GetFolderFromID Method

Creating and Referencing New Folders
 * Folders.Add Method

Creating and Referencing New Items
 * CreateItem Method
 * Items.Add Method
 * CreateItemFromTemplate Method

Referencing Existing Items
 * Using Items(I) or For Each...Next
 * Using Items(&quot;This is the subject&quot;)
 * Find Method
 * Restrict Method
 * GetItemFromID Method



MORE INFORMATION
Microsoft provides programming examples for illustration only, without warranty either expressed or implied, including, but not limited to, the implied warranties of merchantability and/or fitness for a particular purpose. This article assumes that you are familiar with the programming language being demonstrated and the tools used to create and debug procedures. Microsoft support professionals can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific needs. If you have limited programming experience, you may want to contact a Microsoft Certified Partner or the Microsoft fee-based consulting line at (800) 936-5200. For more information about Microsoft Certified Partners, please visit the following Microsoft Web site:

https://partner.microsoft.com/global/30000104

For more information about the support options that are available and about how to contact Microsoft, visit the following Microsoft Web site:

http://support.microsoft.com/default.aspx?scid=fh;EN-US;CNTACTMS

NOTE: Visual Basic Scripting Edition (VBScript) code must use the numeric value of the constants that are defined in the Outlook object library. For additional information, click the article number below to view the article in the Microsoft Knowledge Base:

285202 OL2002: List of Outlook Object Model Constants

GetDefaultFolder Method:
Default folders are those that are at the same level as the Inbox that receives incoming mail. If you have more than one Inbox in your profile, pressing CTRL+SHIFT+I selects the default Inbox. The default folders are those that most users work with regularly, such as the Calendar, Contacts, and Tasks folders. You can easily refer to these folders using the GetDefaultFolder method. GetDefaultFolder takes one argument, which is the type of folder you want to refer to. The following examples assign the object variable  to the default Contacts folder:

' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) Set MyFolder = olns.GetDefaultFolder(olFolderContacts)

' VBScript code example. Set olns = Item.Application.GetNameSpace(&quot;MAPI&quot;) Set MyFolder = olns.GetDefaultFolder(10)

Folders Object
You can use the Folders object to refer to any folder that is visible in the Outlook folder list. This object is typically used to refer to an Exchange public folder or any other folder that is not a default Outlook folder.

The following examples illustrate how to refer to a public folder called &quot; .&quot; Note that you typically start at the top-most folder and work your way down to the folder you need to reference. Also note that the folder names are case-sensitive and must exactly match the names as they appear in the Outlook folder list.

' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) Set MyFolder1 = olns.Folders(&quot;Public Folders&quot;) Set MyFolder2 = MyFolder1.Folders(&quot;All Public Folders&quot;) Set MyFolder3 = MyFolder2.Folders(&quot;My Public Folder&quot;)

' VBScript code example. Set olns = Item.Application.GetNameSpace(&quot;MAPI&quot;) Set MyFolder1 = olns.Folders(&quot;Public Folders&quot;) Set MyFolder2 = MyFolder1.Folders(&quot;All Public Folders&quot;) Set MyFolder3 = MyFolder2.Folders(&quot;My Public Folder&quot;) The following examples illustrate how you can refer to a folder called &quot;Business Tasks,&quot; which is a subfolder of the default Tasks folder.

' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) Set MyTasksFolder = olns.GetDefaultFolder(olFolderTasks) Set MyFolder = MyTasksFolder.Folders(&quot;Business Tasks&quot;)

' VBScript code example. Set olns = Item.Application.GetNameSpace(&quot;MAPI&quot;) Set MyTasksFolder = olns.GetDefaultFolder(13) Set MyFolder = MyTasksFolder.Folders(&quot;Business Tasks&quot;)

Parent Property
If you already have a reference to an Outlook item or folder, then you can use its Parent property to create a reference to the folder the item or folder is located in.

The following examples return the name of a folder for a particular item:

' Automation code example. Set ol = New Outlook.Application Set MyItem = ol.CreateItem(olMailItem) ' Create new item. MyItem.Save                           ' Save it to Drafts. Set MyFolder = MyItem.Parent          ' MyFolder = Drafts.

' VBScript code example. ' Returns the folder of the current item. Set MyFolder = Item.Parent

GetSharedDefaultFolder
You can use this method if someone has given you delegate permissions to one of their default folders.

For additional information about accessing other people's folders, please see the following article in the Microsoft Knowledge Base:

290824 OL2002: How to Open Someone Else's Calendar or Other Folder

The GetSharedDefaultFolder method is used in the same fashion as GetDefaultFolder, except you specify one additional argument -- the name of the other person's folder you want to reference. This example first resolves the other person's name to verify that it is a valid name that can be used with the GetSharedDefaultFolder method.

' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) Set myRecipient = olns.CreateRecipient(&quot;John Smith&quot;) myRecipient.Resolve If myRecipient.Resolved Then Set JohnFolder=olns.GetSharedDefaultFolder _ (myRecipient, olFolderContacts) End If

' VBScript code example. Set olns = Item.Application.GetNameSpace(&quot;MAPI&quot;) Set myRecipient = olns.CreateRecipient(&quot;John Smith&quot;) myRecipient.Resolve If myRecipient.Resolved Then Set JohnFolder = olns.GetSharedDefaultFolder(myRecipient, 10) End If

GetFolderFromID
This method would typically be used only in more complex solutions where a solution keeps track of both the StoreID and EntryID of a folder so that it can be quickly referenced at a later time.

For additional information about using the GetFolderFromID method, click the following article number to view the article in the Microsoft Knowledge Base:

293152 OL2002: Programming with EntryIDs and StoreIDs

Folders.Add Method
Using the Add method on the Folders collection allows you to create a new folder. The first argument specifies the name of the folder and the second argument specifies the type of folder. The following example adds a  subfolder in your default Tasks folder. Because the folder type is not specified, it will inherit the type of the parent folder.

' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) Set MyTasksFolder = olns.GetDefaultFolder(olFolderTasks) Set MyNewFolder = MyTasksFolder.Folders.Add(&quot;Business Tasks&quot;)

' VBScript code example. Set olns = Item.Application.GetNameSpace(&quot;MAPI&quot;) Set MyTasksFolder = olns.GetDefaultFolder(13) Set MyNewFolder = MyTasksFolder.Folders.Add(&quot;Business Tasks&quot;)

CreateItem Method
The CreateItem method creates a new default Outlook item. If you need to create an item based on a custom form you have created, use the Items.Add method below. The CreateItem method is conveniently located off of the top-level application object in the Outlook object model. The method takes only one argument, a constant indicating the type of item to create.

' Automation code example. Set ol = New Outlook.Application Set MyTaskItem = ol.CreateItem(olTaskItem) MyTaskItem.Display

' VBScript code example. Set MyTasktem = Item.Application.CreateItem(3) MyTaskItem.Display

Items.Add Method
Using the Add method on the Items collection allows you to create a new item based on any message class, whether it is a default Outlook message class such as IPM.Contact, or a message class for a custom form, such as IPM.Contact.MyForm. In order to use the Items.Add method, you must first reference the folder where you want to create a new item.

For additional information about message classes, click the article number below to view the article in the Microsoft Knowledge Base:

290657 OL2002: Working with Form Definitions and One-Off Forms

290659 OL2002: How to Update Existing Items to Use a New Custom Form

The following examples use the Items.Add method to create a new item based on a custom contact form called :

' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) Set myFolder = olns.GetDefaultFolder(olFolderContacts) Set MyItem = MyFolder.Items.Add(&quot;IPM.Contact.MyForm&quot;) MyItem.Display

' VBScript code example. Set olns = Item.Application.GetNameSpace(&quot;MAPI&quot;) Set myFolder = olns.GetDefaultFolder(10) Set MyItem = MyFolder.Items.Add(&quot;IPM.Contact.MyForm&quot;) MyItem.Display

The following examples use the Items.Add method to create a new default contact item: ' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) Set myFolder = olns.GetDefaultFolder(olFolderContacts) Set MyItem = MyFolder.Items.Add MyItem.Display

' VBScript code example. Set olns = Item.Application.GetNameSpace(&quot;MAPI&quot;) Set myFolder = olns.GetDefaultFolder(10) Set MyItem = MyFolder.Items.Add MyItem.Display

NOTE: If you use the Items.Add method, it does not matter what the default form for the folder is. You can specify any valid message class as long as it has been published in the folder or has been published in the personal or organizational forms library.

CreateItemFromTemplate Method
Use the CreateItemFromTemplate method to create a new item based on an Outlook template file (.oft) or .msg file format. Because most forms are published in a folder or forms library, this method is not commonly used. Probably the most common reason to use this method would be if you were creating a Microsoft Visual Basic Setup program to install forms for an Outlook solution. This would typically be done for users who do not have network access or typically work offline in Outlook. The Visual Basic program would do the following:

 Automate Outlook. Use CreateItemFromTemplate to open a form from a network share or disk.  Using the Outlook object model, publish the form for later use. ' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) ' Set MyFolder to the default contacts folder. Set MyFolder = olns.GetDefaultFolder(olFolderContacts) ' Set MyItem to an .oft file on a floppy disk. Set MyItem = ol.CreateItemFromTemplate(&quot;A:\Contact.oft&quot;) ' Set MyForm to the item Form Description for publishing. Set MyForm = MyItem.FormDescription ' Name the form, which also sets its message class. MyForm.Name = &quot;My Contact&quot; ' Publish the folder to the Contacts folder. MyForm.PublishForm olFolderRegistry, MyFolder ' Close and do not save changes to the item. MyItem.Close olDiscard 

Using Items(I) or For Each...Next
Typically these approaches are used to loop through all of the items in a folder. The Items collection contains all of the items in a particular folder and you can specify which item to reference by using an index with the Items collection. This is typically used with the For I = 1 to n programming construct.

You can use the For Each...Next programming construct to loop through the items in the collection without specifying an index. Both approaches achieve the same result.

The following examples use the Items(I) approach to loop through all of the contacts in the Contacts folder and display their FullName field in a dialog box.

' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) ' Set MyFolder to the default contacts folder. Set MyFolder = olns.GetDefaultFolder(olFolderContacts) ' Get the number of items in the folder. NumItems = MyFolder.Items.Count ' Set MyItem to the collection of items in the folder. Set MyItems = MyFolder.Items ' Loop through all of the items in the folder. For I = 1 to NumItems MsgBox MyItems(I).FullName Next

' VBScript code example. Set olns = Item.Application.GetNameSpace(&quot;MAPI&quot;) ' Set MyFolder to the default contacts folder. Set MyFolder = olns.GetDefaultFolder(10) ' Get the number of items in the folder. NumItems = MyFolder.Items.Count ' Set MyItem to the collection of items in the folder. Set MyItems = MyFolder.Items ' Loop through all of the items in the folder. For I = 1 to NumItems MsgBox MyItems(I).FullName Next

The following examples use the For Each...Next construct to achieve the same result as the preceding examples:

' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) ' Set MyFolder to the default contacts folder. Set MyFolder = olns.GetDefaultFolder(olFolderContacts) ' Set MyItems to the collection of items in the folder. Set MyItems = MyFolder.Items For Each SpecificItem in MyItems MsgBox SpecificItem.FullName Next

' VBScript code example. Set olns = Item.Application.GetNameSpace(&quot;MAPI&quot;) ' Set MyFolder to the default contacts folder. Set MyFolder = olns.GetDefaultFolder(10) ' Set MyItem to the collection of items in the folder. Set MyItems = MyFolder.Items For Each SpecificItem in MyItems MsgBox SpecificItem.FullName Next

Using Items(&quot;This is the subject&quot;)
You can also use the Items collection and specify a text string that matches the Subject field of an item. This approach is not commonly used.

The following examples display an item in the Inbox whose subject contains &quot;Please help on Friday!&quot;

' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) ' Set MyFolder to the default Inbox. Set MyFolder = olns.GetDefaultFolder(olFolderInbox) Set MyItem = MyFolder.Items(&quot;Please help on Friday!&quot;) MyItem.Display

' VBScript code example. Set olns = Item.Application.GetNameSpace(&quot;MAPI&quot;) ' Set MyFolder to the default Inbox. Set MyFolder = olns.GetDefaultFolder(6) Set MyItem = MyFolder.Items(&quot;Please help on Friday!&quot;) MyItem.Display

Find Method
Use the Find method to search for an item in a folder based on the value of one of its fields. If the Find is successful, you can then use the FindNext method to check for additional items that meet the same search criteria.

The following examples search to see if you have any high priority appointments.

' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNamespace(&quot;MAPI&quot;) Set myFolder = olns.GetDefaultFolder(olFolderTasks) Set MyTasks = myFolder.Items ' Importance corresponds to Priority on the task form. Set MyTask = MyTasks.Find(&quot;[Importance] = &quot;&quot;High&quot;&quot;&quot;) If MyTask Is Nothing Then ' the Find failed MsgBox &quot;Nothing important. Go party!&quot; Else MsgBox &quot;You have something important to do!&quot; End If

' VBScript code example. Set olns = Item.Application.GetNamespace(&quot;MAPI&quot;) Set myFolder = olns.GetDefaultFolder(13) Set MyTasks = myFolder.Items ' Importance corresponds to Priority on the task form. Set MyTask = MyTasks.Find(&quot;[Importance] = &quot;&quot;High&quot;&quot;&quot;) If MyTask Is Nothing Then ' the Find failed MsgBox &quot;Nothing important. Go party!&quot; Else MsgBox &quot;You have something important to do!&quot; End If

Restrict Method
The Restrict method is similar to the Find method, but instead of returning a single item, it returns a collection of items that meet the search criteria. For example, you might use this method to find all contacts who work at the same company.

The following examples display all of the contacts who work at ACME Software:

' Automation code example. Set ol = New Outlook.Application Set olns = ol.GetNameSpace(&quot;MAPI&quot;) Set MyFolder = olns.GetDefaultFolder(olFolderContacts) Set MyItems = MyFolder.Items MyClause = &quot;[CompanyName] = &quot;&quot;ACME Software&quot;&quot;&quot; Set MyACMEItems = MyItems.Restrict(MyClause) For Each MyItem in MyACMEItems MyItem.Display Next

' VBScript code example. ' Requires VBScript version 2.0 or later. Set olns = Item.Application.GetNameSpace(&quot;MAPI&quot;) Set MyFolder = olns.GetDefaultFolder(10) Set MyItems = MyFolder.Items MyClause = &quot;[CompanyName] = &quot;&quot;ACME Software&quot;&quot;&quot; Set MyACMEItems = MyItems.Restrict(MyClause) For Each MyItem in MyACMEItems MyItem.Display Next For additional information about using the Restrict method, click the article number below to view the article in the Microsoft Knowledge Base:

291161 OL2002: Using Find and Restrict to Retrieve Items

GetItemFromID Method
This method would typically be used only in more complex solutions where a solution keeps track of both the StoreID and EntryID of an item so that it can be quickly retrieved at a later time.

For additional information about using the GetFolderFromID method, click the following article number to view the article in the Microsoft Knowledge Base:

293152 OL2002: Programming with EntryIDs and StoreIDs

