Folders Collection Object

Article
08/21/2009

Folders Collection Object

The Folders collection object contains one or more Folder objects.

At a Glance

Specified in type library:	CDO.DLL
First available in:	CDO Library version 1.0.a
Parent objects:	Folder
Child objects:	Folder
Default property:	Item

A Folders collection is considered a large collection, which means that the Count property has limited validity, and the best way to access an individual Folder object within the collection is to use either its unique identifier or the Get methods. For more information on collections, see Object Collections.

Properties

Name	Available since version	Type	Access
Application	1.0.a	String	Read-only
Class	1.0.a	Long	Read-only
Count	1.1	Long	Read-only
Item	1.1	Folder object	Read-only
Parent	1.0.a	Folder object	Read-only
RawTable	1.1	IUnknown object	Read/write (Note: Not available to Visual Basic applications)
Session	1.0.a	Session object	Read-only

Methods

Name	Available since version	Parameters
Add	1.1	name as String
Delete	1.1	(none)
GetFirst	1.0.a	(none)
GetLast	1.0.a	(none)
GetNext	1.0.a	(none)
GetPrevious	1.0.a	(none)
Sort	1.1	(optional) SortOrder as Long, (optional) PropTag as Long, (optional) PropID as String

Remarks

Large collections, such as the Folders collection, cannot always maintain an accurate count of the number of objects in the collection. It is strongly recommended that you use the GetFirst, GetLast, GetNext, and GetPrevious methods to access individual items in the collection. You can access one specific folder by using the Session object's GetFolder method, and you can access all the items in the collection with the Microsoft® Visual Basic® For Each construction.

The order that items are returned by GetFirst, GetLast, GetNext, and GetPrevious depends on whether the folders are sorted or not. The Folder objects within a collection can be sorted on a MAPI property of your choice, either ascending or descending, using the Sort method. When the items are not sorted, you should not rely on these methods to return the items in any specified order. The best programming approach to use with unsorted collections is to assume that the access functions are able to access all items within the collection, but that the order of the objects is not defined.

Example

To refer to a unique Folder object within the Folders collection, use the collection's GetFirst and GetNext methods or use the folder's ID value as an index.

The following code sample demonstrates the Get methods. The sample assumes that you have exactly three subfolders within your Inbox and exactly three subfolders within your Outbox. After this code runs, the three folders in the Inbox are named Blue, Red, and Orange (in that order), and the three folders in the Outbox are named Gold, Purple, and Yellow (in that order).

Important Storing user names and passwords inside source code can lead to security vulnerabilities in your software. Do not store user names and passwords in your production code.

Dim objSession As MAPI.Session
Dim objMessage As Message
Dim objFolder As Folder

Set objSession = CreateObject("MAPI.Session")

' IMPORTANT: Storing user names and passwords inside source code
' can lead to security vulnerabilities in your software. Do not
' store user names and passwords in your production code.
objSession.Logon "User", "", True

With objSession.Inbox.Folders
    Set objFolder = .GetFirst
    objFolder.Name = "Blue"
    Set objFolder = .GetNext
    objFolder.Name = "Red"
    Set objFolder = .GetLast
    objFolder.Name = "Orange"
End With
With objSession.Outbox.Folders
    Set objFolder = .GetFirst
    objFolder.Name = "Gold"
    Set objFolder = .GetNext
    objFolder.Name = "Purple"
    Set objFolder = .GetLast
    objFolder.Name = "Yellow"
End With
objSession.Logoff

Folders Collection Object