Platform SDK: CDO 1.2.1

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).

Dim objSession As MAPI.Session 
Dim objMessage As Message 
Dim objFolder As Folder 
 
Set objSession = CreateObject("MAPI.Session") 
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