RDOSearchFolder object

 

RDOSearchFolder object represents a MAPI search folder. Search folder do not physically contain messages, they only contain links to the messages in the folders where the search is performed (SearchContainers collection property). The parameters of the search are specified by the SearchCriteria property. An example of a search folder is Reminders: Outlook creates this search folder (invisible to a user) that looks for the messages with the reminder property set in the Inbox, Calendar, Tasks and Contacts folders.

Normally, Outlook creates search folders as subfolders of the search root container (returned by RDOStore.SearchRootFolder). Most store providers however support creating search folders anywhere.

 

RDOSearchFolder object is derived from the RDOFolder object and implements all of its properties and methods in addition to the search folder related properties and methods (see below).

Since search folders do not physically contain messages, you cannot directly add messages (RDOSearchFolder.Items.Add will return an error) and they also do not have subfolders (RDOSearchFolder.Folder collection is *not* the same as RDOSearchFolder.SearchContainers).

 

When an asynchronous search is complete, the OnSearchComplete event is fired.

 

Returned by:

RDOSession.GetFolderFromID

RDOStore.GetFolderFromID

RDOFolders.AddSearchFolder, Item, GetFirst, GetLast, GetNext, GetPrevious

 

The example below logs to the default MAPI session and displays the names of the folders where the search is performed for all search folders in the default message store:

set Session = CreateObject("Redemption.RDOSession")
Session.Logon
set SearchRootFolder = Session.Stores.DefaultStore.SearchRootFolder
for each Folder in SearchRootFolder.Folders
  Debug.Print "Search containers for folder: " & Folder.Name
  for each ContainerFolder in Folder.SearchContainers
    Debug.Print ContainerFolder.Name
  next
  Debug.Print "------- "
next

 

The following example below logs to the default MAPI session and creates a new search folder that contains messages with the "test" substring in the subject property. The search is performed in the Inbox and Sent Items folders.

Note that you will need to wait until RDOSearchFolder.IsRebuild property (see below) becomes false, meaning that Outlook finished searching through the specified folders.

Also note that the newly created folder will not be displayed as one of the "Search Folders" subfolders in Outlook 2003. Use RDOSearches and RDOSearch objects for that. .

RES_CONTENT = 3
FL_SUBSTRING = 1
FL_IGNORECASE = &H10000
PR_SUBJECT = &H0037001E
'create new search folder
set Session = CreateObject("Redemption.RDOSession")
Session.Logon
set DefaultStore = Session.Stores.DefaultStore
set SearchRootFolder = DefaultStore.SearchRootFolder
set NewSearchFolder = SearchRootFolder.Folders.AddSearchFolder("Test Redemption Search Folder")
'set the restriction to search for message with the word "test" in the subject line
set Restriction = NewSearchFolder.SearchCriteria.SetKind(RES_CONTENT)
Restriction.ulFuzzyLevel = FL_SUBSTRING or FL_IGNORECASE
Restriction.ulPropTag = PR_SUBJECT
Restriction.lpProp = "test"
'specify that the search should be performed in the Inbox and Sent Items folders
NewSearchFolder.SearchContainers.Add(DefaultStore.GetDefaultFolder(olFolderInbox))
NewSearchFolder.SearchContainers.Add(DefaultStore.GetDefaultFolder(olFolderSentMail))
'specify the search flags
NewSearchFolder.IsRecursiveSearch = false
NewSearchFolder.IsForegroundSearch = false
'we are all set: set the search parameters and let the fun begin!
NewSearchFolder.Start

 

The example below creates the same search folder as the one above but uses SearchCriteria.AsSQL property instead of SearchCriteria.SetKind.

'create new search folder
set Session = CreateObject("Redemption.RDOSession")
Session.Logon
set DefaultStore = Session.Stores.DefaultStore
set SearchRootFolder = DefaultStore.SearchRootFolder
set NewSearchFolder = SearchRootFolder.Folders.AddSearchFolder("Test Redemption Search Folder")
'set the restriction to search for message with the word "test" in the subject line

 NewSearchFolder.SearchCriteria.AsSQL = "Subject LIKE '%test%' "
'specify that the search should be performed in the Inbox and Sent Items folders
NewSearchFolder.SearchContainers.Add(DefaultStore.GetDefaultFolder(olFolderInbox))
NewSearchFolder.SearchContainers.Add(DefaultStore.GetDefaultFolder(olFolderSentMail))
'specify the search flags
NewSearchFolder.IsRecursiveSearch = false
NewSearchFolder.IsForegroundSearch = false
'we are all set: set the search parameters and let the fun begin!
NewSearchFolder.Start

 

 

 

 

Derived from: RDOFolder - _MAPIProp

_MAPIProp methods and properties: GetIDsFromNames, Fields(), GetPropList, GetNamesFromIDs, CopyTo, Save, MAPIOBJECT, Session

 

RDOFolder methods and properties: DefaultMessageClass, Description, EntryID, Name, Kind, ACL, Parent, StoreID, UnReadItemCount, Items, Folders, HiddenItems, Store, ShowAsOutlookAB, DefaultItemType, WebViewAllowNavigation, WebViewOn, WebViewURL, DeletedItems, AddressBookName, Delete, MoveTo

Properties

SearchCriteria

Returns an RDOSearchCriteria object representing the search criteria used by the folder.

If the search criteria is modified, the changes will be applied only after the Start method (see below) is called.

 

see example above

SearchContainers

Returns an RDOSearchContainersList object representing the list of folders where the search is performed by the search folder.

If the search containers list is modified, the changes will be applied only after the Start method (see below) is called.

 

see example above

IsRecursiveSearch

Boolean, read-write. Specifies whether the search must also be performed in all subfolders of the folders listed in the SearchContainers collection.

Corresponds to the SEARCH_RECURSIVE bit returned by the IMAPIFolder::GetSearchCriteria or RECURSIVE_SEARCH bit when set by IMAPIFolder::SetSearchCriteria.

If the property is modified, the change will be applied only after the Start method (see below) is called.

 

 

IsForegroundSearch

Boolean, read-write. Specifies whether the search should run at high priority relative to other searches.

Corresponds to the SEARCH_FOREGROUND bit returned by the IMAPIFolder::GetSearchCriteria or FOREGROUND_SEARCH bit when set by IMAPIFolder::SetSearchCriteria.

If the property is modified, the change will be applied only after the Start method (see below) is called.

 

 

IsRunning

Boolean, read-only. If true, the search is active and the container's contents table is being updated to reflect changes in the message store or address book. If false, the search is inactive and the contents table is static..

Corresponds to the SEARCH_RUNNING bit returned by the IMAPIFolder::GetSearchCriteria

 

 

IsRebuild

Boolean, read-only. If true, the search is in the CPU-intensive mode of its operation, attempting to locate messages that match the criteria. If this flag is not set, the CPU-intensive part of the search's operation is over. This flag only has meaning if the search is active that is, if IsRunning is true.

 

 

ShowItemCount

Sets or returns a constant in the rdoShowItemCount enumeration that indicates whether to display the number of unread messages in the folder or the total number of items in the folder in the Navigation Pane. Read/write.

 

olNoItemCount = 0
olShowUnreadItemCount = 1
olShowTotalItemCount = 2

 

 

Methods

Start

Starts (or restarts) the search. On the Extended MAPI level, RDO calls IMAPIFolder::SetSearchCriteria with the START_SEARCH bit set. All changes to the SearchCriteria, SearchContainers, IsRecursiveSearch and IsForegroundSearch properties will be applied at this point.

 

see example above

Stop

Stops the search. On the Extended MAPI level, RDO calls IMAPIFolder::SetSearchCriteria with the STOP_SEARCH bit set.