Searching for a Folder

Two frequently used folders, the Inbox and the Outbox, are available through Session object properties. To access these folders, simply set a Folder object to the corresponding property.

To access other folders, search for the folder using one of the following techniques:

• Call the Session object's GetFolder method with a string parameter that specifies the FolderID, a unique identifier for the folder.
• Use the Get methods to navigate through the Folders collection. Search for a specific folder by comparing each folder's properties with the desired properties.

Using the Session Object's GetFolder Method

When you know the unique identifier for the folder you are looking for, you can call the Session object's GetFolder method.

The unique identifier for the folder, established at the time the folder is created, is stored in its ID property. The ID property is a string representation of the MAPI entry identifier and its value is determined by the service provider.

The following code fragment contains code that saves the identifier for the folder, then uses it in a subsequent GetFolder call:

' Function: Session_GetFolder 
' Purpose: Demonstrate how to set a folder object 
' See documentation topic: Session object GetFolder method 
Function Session_GetFolder() 
    On Error GoTo error_olemsg 
 
    If objSession Is Nothing Then 
        MsgBox "No active session, must log on" 
        Exit Function 
    End If 
    If strFolderID = "" Then 
        MsgBox ("Must first set folder ID variable; see Folder->ID") 
        Exit Function 
    End If 
    Set objFolder = objSession.GetFolder(strFolderID) 
    'equivalent to: 
    ' Set objFolder = objSession.GetFolder(folderID:=strFolderID) 
    If objFolder Is Nothing Then 
        Set objMessages = Nothing 
        MsgBox "Unable to retrieve folder with specified ID" 
        Exit Function 
    End If 
    MsgBox "Folder set to " & objFolder.Name 
    Set objMessages = objFolder.Messages 
    Exit Function 
 
error_olemsg: 
    MsgBox "Error " & Str(Err) & ": " & Error$(Err) 
    Set objFolder = Nothing 
    Set objMessages = Nothing 
    MsgBox "Folder is no longer available" 
    Exit Function 
End Function 
 

Using the Get Methods

When you are looking for a folder within a Folders collection, you can navigate through the collection, examining properties of each Folder object to determine whether it is the folder you want.

The CDO Library supports the GetFirst, GetNext, GetLast, and GetPrevious methods for the Folders collection object.

The following code fragment demonstrates how to use the Get methods to search for the specified folder:

' Function: TestDrv_Util_GetFolderByName 
' Purpose: Call the utility function Util_GetFolderByName 
' See documentation topic: Item property (Folder object) 
Function TestDrv_Util_GetFolderByName() 
Dim fFound As Boolean 
    fFound = Util_GetFolderByName("Junk mail") 
    If fFound Then 
        MsgBox "Folder named 'Junk mail' found" 
    Else 
        MsgBox "Folder named 'Junk mail' not found" 
    End If 
    Exit Function 
 
error_olemsg: 
    MsgBox "Error " & Str(Err) & ": " & Error$(Err) 
    Resume Next 
End Function 
 
' Function: Util_GetFolderByName 
' Purpose: Use Get* methods to search for a folder 
' See documentation topic:  Searching For a Folder 
Function Util_GetFolderByName(strSearchName As String) As Boolean 
Dim objOneFolder As Object   ' local; temp version of folder object 
 
    On Error GoTo error_olemsg 
    Util_GetFolderByName = False ' default; assume failure 
    If objFolder Is Nothing Then 
        MsgBox "Must first select a folder such as Session->Inbox" 
        Exit Function 
    End If 
    Set objFoldersColl = objFolder.Folders ' Folders collection 
    If objFoldersColl Is Nothing Then 
        MsgBox "no subfolders; not found" 
        Exit Function 
    End If 
    ' get the first folder in the collection 
    Set objOneFolder = objFoldersColl.GetFirst 
    ' loop through all the folders in the collection 
    Do While Not objOneFolder Is Nothing 
        If objOneFolder.Name = strSearchName Then 
            Exit Do ' found it, leave the loop 
        Else ' keep searching 
            Set objOneFolder = objFoldersColl.GetNext 
        End If 
    Loop 
    ' exit from the Do While loop comes here 
    ' if objOneFolder is valid, the folder is found 
    If Not objOneFolder Is Nothing Then ' went off end of loop 
        Util_GetFolderByName = True ' success 
    End If 
    Exit Function 
 
error_olemsg: 
    MsgBox "Error " & Str(Err) & ": " & Error$(Err) 
    Resume Next 
End Function 
 

You can also navigate upward through the folder hierarchy by using each Folder object's Parent property.

See Also

Searching for a Message