RDOFolder object

 

RDOFolder object represents a MAPI folder with its messages and subfolders. For the search folders (Kind property is fkSearch), RDOFolder object can be cast to the RDOSearchFolder object, which provides methods and properties specific to the MAPI search folders.

 

Note that RDOSearchFolder object (representing search folders) is derived from RDOFolder object.

To represent functionality specific to the regular (not search) folders, RDO exposes RDOFolder2 interface, which is only implemented by the regular folders. To access RDOFolder2 properties and methods, cast RDOFolder object to RDOFolder2 object.

 

Returned by:

RDOSession.GetDefaultFolder, GetFolderFromID, GetSharedDefaultFolder

RDOStores.GetDefaultFolder, GetSharedDefaultFolder

RDOStore.RootFolder, IPMRootFolder, GetDefaultFolder, SearchRootFolder, GetFolderFromID

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

RDOMail.Parent (for messages that exist in folder, not for the embedded message attachments)

 

The example below logs to the default MAPI session and displays the number of messages in the Inbox folder:

set Session = CreateObject("Redemption.RDOSession")
Session.Logon
set Folder = Session.GetDefaultFolder(olFolderInbox)
MsgBox Folder.Items.Count

 

Properties

Methods

Events

 


Derived from: _MAPIProp -


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

 

CopyTo(DestObj)

Copies the folder to the target folder. RDOFolder overrides the behavior inherited from _MAPIProp to copy all messages and subfolders.

DestObj parameter must point to an instance of the RDOFolder object.

'copy the entire IPM subtree of the default store to a new PST file

set Session = CreateObject("Redemption.RDOSession")
Session.Logon
set SourceStore = Session.Stores.DefaultStore
set TargetStore = Session.Stores.AddPSTStore("c:\temp\copied.pst", 1, "Copied Store")
for each folder in SourceStore.IPMRootFolder.Folders
  folder.CopyTo TargetStore.IPMRootFolder
next


Properties


ACL

Returns RDOACL object representing the Access Control List for the folder.

Exchange specific, returns NULL for other store kinds.

 

Important note: if you set RDOSession.MAPIOBJECT property to Namespace.MAPIOBJECT property from the Outlook Object Model and your code is running outside of the outlook.exe address space (i.e. it is not a COM add-in) this property will return an error due to a MAPI marshalling bug.

 

'print out the names of all ACL entries

for each ACE in Folder.ACL
  Debug.Print ACE.Name & " - " & ACE.Rights
next

DefaultMessageClass

string, read-only. The default message class of the newly created messages, e.g. "IPM.Note"

 

 

Description

string, read-write. Folder description; corresponds to the PR_COMMENT Extended MAPI property.

 

 

EntryID

string, read-only. Hex representation of the folder entry id.

 

 

ExchangeSynchronizer

RDOFolderSynchronizer, read-only. Allows to synchronize the folder contents (both regular and associated items) and subfolders.

See RDOFolderSynchronizer for help.

 

 

FolderKind

Returns one of the rdoFolderKind enumeration constants indicating the folder type. Corresponds to the PR_FOLDER_TYPE Extended MAPI property.

If FolderKind is fkSearch, you can cast the folder to the RDOSearchFolder object. Otherwise you cab cast it to the RDOFolder2 object.

fkRoot (0)
fkGeneric (1)
fkSearch (2)

 

 

Name

string, read-write. Folder name; corresponds to the PR_DISPLAY_NAME Extended MAPI property.

 

 

Parent

RDOFolder, read-only. The parent folder of the given folder.

 

 

StoreID

string, read-only. Hex representation of the folder's parent store entry id.

 

 

UnReadItemCount

integer, read-only. The number of unread items in the folder

 

 

Items

RDOItems, read-only. Collection representing the folder's messages

 

set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set Inbox = Session.GetDefaultFolder(olFolderInbox)
for each Msg in Inbox.Items
  Debug.Print(Msg.Subject)
next

Folders

RDOFolders, read-only. Collection representing the folder's subfolders.

 

set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set IPMRoot = Session.Stores.DefaultStore.IPMRootFolder
for each Fld in IPMRoot.Folders
  Debug.Print(Fld.Name)
next

HiddenItems

RDOItems, read-only. Collection representing the folder's hidden (associated) messages

set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set Inbox = Session.GetDefaultFolder(olFolderInbox)
for each Msg in Inbox.HiddenItems
  Debug.Print(Msg.Subject)
next

Store

RDOStore, read-only. Folder's parent message store.

 

 

ShowAsOutlookAB

boolean, read-write. Returns or sets a Boolean variable that specifies whether the folder will be displayed as a Microsoft Outlook Address Book. Only applies to the folders containing contacts or distribution lists.

 

set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set Folder = Session.GetFolderFromID(MAPIFolder.EntryID)
Folder.ShowAsOutlookAB = false

DefaultItemType

OlItemType, read-only. Returns an OlItemType constant (olContactItem, olMailItem, etc) indicating the default Outlook item type contained in the folder.

 

 

WebViewAllowNavigation

boolean, read-write. Determines if navigation is allowed if the folder displays a web page (WebView is true and WebViewURL points to a valid HTML page)

 

 

WebViewOn

boolean, read-write. Returns or sets a Boolean indicating the Web view state for a folder. True to display the Web page specified by the WebViewURL property

 

Folder.WebViewURL = "http://www.cnn.com"
Folder.WebViewOn=true

WebViewURL

string, read-write. Returns or sets a String indicating the URL of the Web page that is assigned to a folder.

 

 

DeletedItems

RDODeletedItems, read-only. Collection representing the folder's deleted messages that can be restored.  Exchange only in the online mode, the retention policy must be set on the Server.

 

set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set Inbox = Session.GetDefaultFolder(olFolderInbox)

set DeletedItems = Inbox.DeletedItems
for i = DeletedItems.Count to 1 step -1

  Debug.Print "restoring " & DeletedItems(i).Subject
  DeletedItems.Restore(i)
next

AddressBookName

string, read-write. Returns or sets a String that indicates the Address Book name for the MAPIFolder object representing a contact items folder

 

Folder.ShowAsOutlookAB = true
Folder.AddressBookName = Folder.Name & " (AB)"


Methods


Delete

Deletes the folder and all of its messages and subfolders.

 

 

MoveTo(DestinationFolder)

Moves the folder to the specified destination folder.

DestinationFolder parameter must point to an instance of the RDOFolder object.

 

 


Events:


OnModified

Fires when the folder itself or one of its child messages is modified

 

 

OnDeleted

Fires when a message in the folder is deleted

 

 
OnFolderCreated(EntryID)
Fires when a new subfolder is created in the folder.
EntryID - entry id of the new subfolder.

Note: a of Outlook 2010, this event is only fired by the cached Exchange store. PST store does not raise this event.
 
OnFolderModified(EntryID)
Fires when one or more of the folder properties is modified.
Note that modifying a message only can also cause this event to fire, e.g. when a message is deleted, PR_CONENT_COUNT folder property is modified.

 
OnMessageCreated(EntryID)
Fires when a new message is created in the folder.
EntryID - entry id of the new message.

Note: a of Outlook 2010, this event is only fired by the cached Exchange store. PST store does not raise this event.
 
OnMessageDeleted(EntryID)
Fires when a message is deleted in the folder.
EntryID - entry id of the deleted message.

Note: a of Outlook 2010, this event is only fired by the cached Exchange store. PST store does not raise this event.
 
OnMessageModified(EntryID)
Fires when a message is modified in the folder.
EntryID - entry id of the modified message.

Note: a of Outlook 2010, this event is only fired by the cached Exchange store. PST store does not raise this event.
 

OnMoved

Fires when the folder is moved

 

 

OnMovedEx(OldParentEntryID, NewParentEntryID)

Fires when the folder is moved

OldParentEntryID - string, entry id (in hex) of the old parent folder.

NewParentEntryID - string, entry id (in hex) of the new parent folder.

 

 

OnProgress(Value, Min, Max, Count, Total)
Fires when RDOFolder.CopyTo is called and reflects the progress of the copy operation.

Value - the current progress value
Min -
the minimum value of the progress
Max - the maximum value of the progress
Count -
the current item count
Total -
total number of items
 

OnSearchComplete

Fires when an asynchronous search in a search folder is complete. Only applies if the folder is a Search Folder (see RDOSearchFolder object, derived from RDOFolder object)

 

 

 

RDOFolder2 object

 

RDOFolder2 object represents functionality specific to the regular MAPI folders, not available to the search folders. To access RDOFolder2 properties and methods, cast RDOFolder object to RDOFolder2 object.

RDOFolder2 is returned everywhere RDOFolder is returned if the folder is a regular folder (not a search folder).

 

The example below logs to the default MAPI profile, adds a new PST store, check whether a there is a default Calendar folder, and if not, creates one and sets it as default:

 

set Session = CreateObject("Redemption.RDOSession")
Session.Logon
set Store = Session.Stores.AddPstStore("c:\temp\NewStore.pst")
Err.Clear
on Error resume next
'does the store already have a default Calendar folder?
set Folder = Store.GetDefaultFolder(olFolderCalendar)
if Err.Number <> 0 Then
  'no default Calendar folder. Check if there is a folder named "Calendar"
  'and if not, create one

  Err.Clear
  set Folder = Store.IPMRootFolder.Folders("Calendar")
  if (Err.Number <> 0) or (Folder Is Nothing) Then
    'create a new folder
    Err.Clear
    set Folder = Store.IPMRootFolder.Folders.Add("Calendar")
  End If
  Folder.SetAsDefaultFolder(olFolderCalendar)
End If

 

 


Derived from: RDOFolder

 

Properties


CustomViewOnly

Boolean, read/write..

 

Determines which views are displayed on the View menu for a given folder.

 

 

DeletedFolders

Returns the deleted (but recoverable) folders collection (RDODeletedFolders) from a given folder.

Exchange only in the online mode, the retention policy must be set on the server.

set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set Folder = Session.GetFolderFromID(MAPIFolder.EntryID)
set DeletedFolders = Folder.DeletedFolders
for i = DeletedFolders.Count to 1 step -1
  set RestoredFolder = DeletedFolders.Restore(i)
  Debug.Print "Successfully restored folder: " & RestoredFolder.Name
next

 

ExchangeSynchronizer
RDOFolderSynchronizer, read-only. Allows to synchronize the folder contents (both regular and associated items) and subfolders.
See RDOFolderSynchronizerfor help.
 

FolderFields

RDOFolderFields, read-only. This property represents user properties defined in a particular folder. A folder-level user property is available in the "Field Chooser" in Outlook when you select "User-defined fields in folder" when customizing a view or designing a form. Note that adding a property to the folder fields does not automatically make it visible as one of the columns in the folder view nor does it add it to any of the Outlook objects (such as a message or the folder itself); FolderFields is merely a list of property definitions.

Internally, folder fields are stored in one of the hidden messages with the message class of "IPC.MS.REN.USERFIELDS" in the PR_USERFIELDS property.

 

set FolderFields = Folder.FolderFields
for each Field in FolderFields
  Debug.Print Field.Name
next

 

FolderPath

string, read-only.

Returns a string that indicates the path of the current folder.

 

 

IsInPFFavorites

boolean, read-only. TRUE if the given folder is in the Favorites folder in the Public Folder store.

 

 
Rules
Returns RDORules collection representing per folder rules, e.g. set on an Inbox folder or an arbitrary Public Folders store folder (where rules can be set on any mail enabled folder).
 

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


AddToPFFavorites

Adds a Microsoft Exchange public folder to the public folder's Favorites folder.

 

 

EmptyFolder(DeleteHiddenMessages)

Deletes all messages and subfolders from a folder without deleting the folder itself.

 

DeleteHiddenMessages - boolean, optional. If true, all hidden (associated) messages are also deleted. If the optional parameter is not specified, defaults to FALSE (hidden messages are not deleted).

 

 

FindPFFavoritesCopy

Returns the folder's counterpart (RDOFolder2 object) added to the PF Favorites. If the folder is not in the Public Folder store or if the folder has not been added to PF Favorites, returns NULL.

If called on a folder already in PF Favorites, the method returns itself.

 

Calling this method is more expensive than accessing the IsInPFFavorites property.

 

set FavFolder = Folder.FindPFFavoritesCopy
if not (FavFolder Is Nothing) Then
  MsgBox "The folder is in the PF Favorites"
Else
  MsgBox "There is no corresponding copy in the PF Favorites folder"
End If

 

GetActivitiesForTimeRange(StartTime, EndTime, SortAscending)

Returns a sorted list of activities in the given time range as RDOItems collection.

Recurring activities occurring within the specified range are expanded (i.e. only the matching instances but not the master activity are returned).

 

StartTime - start date/time of the range

EndTime - end date/time of the range

SortAscending - sort in the ascending order if true and descending order if false

 

set Session = CreateObject("Redemption.RDOSession")
Session.Logon
set Folder = Session.GetDefaultFolder(olFolderCalendar)
set Items = Folder.GetActivitiesForTimeRange(#2/1/2007#, #3/1/2007#, true)
for each Activity in items
  Debug.Print Activity.Start & " " & Activity.Subject
next

 

GetAllChildFolders

Returns RDOFolders collection with all (not just immediate) subfolders.

Note that only the Exchange provider in the online mode supports that. All other store providers would still return immediate child subfolders only.

 

 

GetAddressList
Returns RDOAddressList object corresponding to the given Contacts folder or null if the folder is not exposed by the OAB provider.
This method is the counterpart of the RDOAddressList.GetContactsFolder method.
set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set ABDialog = Session.GetSelectNamesDialog
ABDialog.ActiveRecipientSelector = olBCC
set Contacts = Session.GetDefaultFolder(olFolderSuggestedContacts)
if (not (Contacts Is Nothing)) and (Contacts.ShowAsOutlookAB) Then
    ABDialog.InitialAddressList = Contacts.GetAddressList
End If
ABDialog.ShowOnlyInitialAddressList = True
if ABDialog.Display Then
    for each recip in ABDialog.Recipients
        Debug.Print recip.Name & ": " & recip.Address
    next
End If
GetFolderFromID(EntryID, Flags)

EntryID - string representing the entry id of the message

Flags - (optional). integer flags to be used to call IMAPISession::OpenEntry. By default MAPI_BEST_ACCESS (0x10) is used. This parameter is most useful if you need to bypass the cached mode in Outlook 2003. E.g. passing MAPI_NO_CACHE (0x200) +  MAPI_BEST_ACCESS (0x10) will open the message in the best access mode bypassing the cached store.

Returns RDOMail object.

 

 
GetMessageFromID(EntryID, Flags)

EntryID - string representing the entry id of the folder

Flags - (optional). integer flags to be used to call IMAPISession::OpenEntry. By default MAPI_BEST_ACCESS (0x10) is used. This parameter is most useful if you need to bypass the cached mode in Outlook 2003. E.g. passing MAPI_NO_CACHE (0x200) +  MAPI_BEST_ACCESS (0x10) will open the folder in the best access mode bypassing the cached store.

Returns RDOFolder object.

 

 
Import(Source, Type, Flags)

Imports from the specified file, IStream COM interface, or from a variant array of byte or of variant)  One or more new items in the folder are created and returned as an RDOItems collection.

All import formats supported by RDOMail.Import are supported by this method.  The method allows to import iCal files with multiple events or vCard files with multiple contacts. For all other formats, a single new item is created.

Flags parameter allow to specify what gets imported and how the new items in the folder are created.

 

Source - string (file name), IStream COM interface, or a variant array (only variant array of byte or a variant array of variant are supported)

 

Type - one of the rdoSaveAsType constants. See RDOMail.Import for the list of supported file formats.

For the olICal and olVCard formats, this method supports multiple entities in a single file.

 

Flags - variant, optional.

A bitmask of the rdoImportFlags enum constants.

If not specified, all MIME parts are imported (for the olRfc822 import format). If neither ifCreateUnsent  nor ifCreateSent  is set, the RDOMail.Sent property value will be determined by the default value of the parent store or (in case of MIME import) X-Unsent MIME header.

 

//MIME import flags

ifPlainBody = 1
ifHTMLBody = 2
ifHeaders = 4
ifRecipients = 8
ifAttachments = 16
ifHtmlImages = 32

//How the item items are created
ifCreateUnsent = 64
ifCreateSent = 128

 

set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set Folder = Session.GetDefaultFolder(olFolderCalendar)
set items = Folder.Import("c:\temp\MultipleItems.ics", olICal)
for each item in items
   
debug.Print item.Subject
next

RemoveFromPFFavorites

Removes a Microsoft Exchange public folder from the public folder's Favorites folder.

 

 

SetAsDefaultFolder(FolderType)

Sets the folder as the default folder type in the parent message store.

FolderType - one of the rdoDefaultFolders enums:

 

olFolderDeletedItems = 3
olFolderOutbox = 4
olFolderSentMail = 5
olFolderInbox = 6
olFolderCalendar = 9
olFolderContacts =10
olFolderJournal = 11
olFolderNotes = 12
olFolderTasks = 13
olFolderDrafts = 16
 

Note that the following folder types are not valid for this method: olPublicFoldersAllPublicFolders, olFolderConflicts,
olFolderSyncIssues, olFolderLocalFailures, olFolderServerFailures, olFolderJunk

see the example above