RDOItems object collection

 

RDOItems collection represents the child messages of a given RDOFolder object.

Returned by: RDOFolder.Items, HiddenItems.

DeletedItems returns an RDODeletedItems collection, which is derived from RDOItems

 

The example below logs to the default MAPI session and prints out the subjects of all the messages from the Inbox folder:

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

 

Note that the performance of the code enumerating through the RDOItems collection is significantly increased if the collection's columns are preset with RDOItems.MAPITable.Columns and only properties specified in the columns property are retrieved from the returned items.

In this case the messages are never opened and only the data from MAPI table is used. If a property not specified in columns is requested or if the message is modified, the item will be opened resulting in degraded performance.

 

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

'let Redemption know which properties we will be requesting later
Items.MAPITable.Columns = "Subject, SenderName"
Items.MAPITable.Sort "ReceivedTime", false
for each Item in Items

  'read the properties specified in the MAPITable.Columns property above
  Debug.Print Item.Subject & " - " & Item.SenderName
next

 

 

Properties

Methods

Events

 

Derived from: IDispatch

Properties

Count

integer, read-only. The number of messages in the RDOItems collection

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

MsgBox "There are " & Folder.Items.Count & " messages in " & Folder.Name

RawTable

IUnknown, read-only. Returns the IMAPITable Extended MAPI interface used internally by the RDOItems collection

 

 

Session

RDOSession, read-only. Returns the parent MAPI session represented by the RDOSession object

 

 

_Item(Index)

Index - variant: integer or a string. A default object property.

Retrieves a message with a given index (1 to Count) or a given subject

Returns RDOMail object

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

for i = 1 to Folder.Items.Count

  Debug.Print Folder.Items(i).Subject

next

 

MAPITable

MAPITable, read-only. Returns the MAPITable Redemption object which can be used to manipulate the collection (restrict, find, etc).

'sort all items in the Inbox by Subject and loop through them
PR_NORMALIZED_SUBJECT = &H0E1D001E
set Session = CreateObject("Redemption.RDOSession")
Session.Logon
set Folder = Session.GetDefaultFolder(olFolderInbox)
set Items = Folder.Items
Items.MAPITable.Sort PR_NORMALIZED_SUBJECT, false
for each item in Items
  Debug.Print(item.Subject)
next

'Print out the subject and entry id of all messages in the Inbox

'received in January 2007

set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
Set folder = Session.GetDefaultFolder(olFolderInbox)
set Items = folder.Items
set Recordset = Items.MAPITable.ExecSQL("SELECT Top 5 Subject, EntryID from Folder " & _
        "where (ReceivedTime >= '2007-01-01') and (ReceivedTime <= '2007-02-01') " & _
        "order by ReceivedTime desc")
while not Recordset.EOF
  Debug.Print(Recordset.Fields("Subject").Value & " - " & Recordset.Fields("EntryID").Value)
  Recordset.MoveNext
wend
 

Methods

Add(Type)

Adds a new message to the folder. Returns the newly added RDOMail object.

Type - variant, optional. either string specifying the message class (e.g. "IPM.Note") or one of the OlItemType values (integer), e.g. olPostItem.

set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set Inbox = Session.GetDefaultFolder(olFolderInbox)
set Msg = Inbox.Items.Add("IPM.Note")
Msg.BCC = "dmitry@dimastr.com; outspy@dimastr.com"
Msg.Subject = "test"
Msg.Save

 

Find(Filter)

Locates and returns the first item (RDOMail or an appropriate object derived from RDOMail, such as RDOContactItem) matching the specified SQL style query (see example).

If no item matches the query, null is returned.

To locate subsequent matching items, call FindNext repeatedly until null is returned.

See also Restrict method.

 

Filter - string. SQL style query specifying the condition. Can either be a WHERE part only (e.g. "LastName = 'Streblechenko' ") or a complete SQL expression with the SELECT, WHERE and ORDER BY clauses (see example).

The properties specified in the SQL query must either use the Outlook Object Model (or RDO) property name (e.g. Subject, Email1Address) or a DASL style property name (e.g. "http://schemas.microsoft.com/mapi/proptag/0x0037001E", "http://schemas.microsoft.com/mapi/id/{00062004-0000-0000-C000-000000000046}/8083001E")

When a DASL property name is used, it must be enclosed in double quotes.

Use OutlookSpy to figure out the DASL property names - select an item in Outlook, click IMessage button on the OutlookSpy toolbar, select the property, see the "DASL" edit box on he right hand side of the window.

 

Including the SELECT clause allows Redemption to pre-fetch the properties from the folder contents table without opening the item resulting in a significant performance gain (see example). If you later access a property not specified in the SELECT clause, Redemption will open the item.

 

Including the ORDER BY clause sorts the collection in the specified order.

 

set Session = CreateObject("Redemption.RDOSession")
Session.Logon
set Contacts = Session.GetDefaultFolder(olFolderContacts)
set Items = Contacts.Items
set Contact = Items.Find("SELECT Email1Address, FileAs from Folder " & _

                                       " WHERE LastName = 'Streblechenko' " & _

                                       " ORDER BY FirstName desc")
while Not (Contact Is Nothing)
    Debug.Print Contact.FileAs & ": " & Contact.Email1Address
    set Contact = Items.FindNext
wend

 

FindNext

Returns the next object matching the restriction specified in a previous call to Find. It returns null if no next object exists, for example, if already positioned at the end of the collection.

An error will be raised if the Find method was not previously called.

 

see example above

GetFirst

Returns the first message in the specified RDOItems collection. Returns Nothing if no first message exists, for example, if there are no messages.

 

 

GetLast

Returns the last message in the specified RDOItems collection. Returns Nothing if no last message exists, for example, if there are no messages.

 

 

GetNext

Returns the next message in the specified RDOItems collection. It returns Nothing if no next message exists, for example, if already positioned at the end of the collection.

 

 

GetPrevious

Returns the previous message in the specified RDOItems collection. It returns Nothing if no previous message exists, for example, if already positioned at the beginning of the collection.

 

 

Item(Index)

Index - variant: integer or a string.

Retrieves a message with a given index (1 to Count) or a given subject

Returns RDOMail object

 

 

Remove(Index, DeleteFlags)

Deletes a message with the specified index (1 to Count)

Index - integer, 1 through Count

DeleteFlags - integer, optional. One of the redDeleteFlags enumeration values:

dfSoftDelete (0) - default. Deletes the item. Can still be recoverable if retention policy is set on Exchange Server.

dfMoveToDeletedItems (1) - the item is moved to the Deleted Items folder

dfHardDelete (2) - Exchange only. Permanently deletes the item; will not be recoverable

 

 

RemoveMultiple(EntryIdsOrArrayOfMessages, DeleteFlags)

Deletes multiple messages in a single call.

See also RDOFolder.EmptyFolder method.

 

EntryIdsOrArrayOfMessages - either an array of messages, array of entry ids (strings), or a string with multiple entry ids separated by ";" or CR/LF.

 

DeleteFlags - integer, optional. One of the redDeleteFlags enumeration values:

dfSoftDelete (0) - default. Deletes the item. Can still be recoverable if retention policy is set on Exchange Server.

dfMoveToDeletedItems (1) - the item is moved to the Deleted Items folder

dfHardDelete (2) - Exchange only. Permanently deletes the item; will not be recoverable

 

  set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set Folder = Session.GetFolderFromID(Application.ActiveExplorer.CurrentFolder.EntryID)
Dim Messages()
Redim Messages(Application.ActiveExplorer.Selection.Count)
for i = 1 to Application.ActiveExplorer.Selection.Count
    Messages(i-1) = Application.ActiveExplorer.Selection(i).EntryID
next
Folder.Items.RemoveMultiple(Messages)

Restrict(Filter)

Applies a filter to the RDOItems collection, returning a new RDOItems collection containing all of the items from the original that match the filter. The original RDOItems collection is not affected.

 

This method is an alternative to using the Find method or FindNext method to iterate over specific items within a collection. The Find or FindNext methods are faster than filtering if there are a small number of items. The Restrict method is significantly faster if there is a large number of items in the collection, especially if only a few items in a large collection are expected to be found.

 

Note however that Exchange Server in the online mode caches the restriction (1 week by default) and recalculates it every time any item in the folder is modified.

If your restriction is constant, this can be lead to a significant performance boost. If however you apply different restrictions, this can significantly degrade the server performance.

 

Filter - string. SQL style query. See Find method help for more information

 

set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set Contacts = Session.GetDefaultFolder(olFolderContacts)
set Items = Contacts.Items
set RestrictedItems = Items.Restrict("SELECT Email1Address, FileAs from Folder " & _

                                                       " where LastName = 'Streblechenko' " & _

                                                       " ORDER BY FirstName desc")
for each Contact in RestrictedItems
    Debug.Print Contact.FileAs & ": " & Contact.Email1Address
next

Sort(Columns, Descending)

Sorts the collection of items by the specified property or properties.

 

Columns - can either be an integer property tag or a variant array of integer property tags or a comma separated string of the OOM or DASL property names (see example)

 

Descending - optional. Either a boolean or a variant array of boolean values corresponding to the Columns parameter.

set Session = CreateObject("Redemption.RDOSession")
Session.Logon
set Contacts = Session.GetDefaultFolder(olFolderInbox)
set Items = Contacts.Items
Items.Sort "Subject", false
for each Item in Items

    Debug.Print Item.Subject
next

 

Events:

ItemChange(Item)

Fires when a message in the contents or associated contents table is modified.

Item - RDOMail object

 

ItemAdd(Item)

Fires when a new message is added to the contents or associated contents table.

Item - RDOMail object

Dim WithEvents Items As Redemption.RDOItems
...

Set Session = New Redemption.RDOSession
Session.Logon
Set Store = Session.Stores.DefaultStore
Set Inbox = Store.GetDefaultFolder(olFolderInbox)
Set Items = Inbox.Items
...

Sub Items_ItemAdd(ByVal Mail As RDOMail)
  MsgBox "Item added: " & Mail.Subject
End Sub
 

ItemRemove(InstanceKey)

Fires when a message is removed from the contents or associated contents table.
By the time this asynchronous even is fired, the message is already deleted, hence no entry id is available.

InstanceKey - a hex value of the PR_INSTANCE_KEY property of the deleted table row. Note that PR_INSTANCE_KEY is not available from the message itself, only from the MAPI table (see MAPITable property). InstanceKey is only guaranteed to be the same for the same instance of the table, hence this event is useful only if the value of PR_INSTANCE_KEY was previously cached.

 

CollectionModified

Fires when the contents or associated contents table is modified and the underlying MAPI implementation cannot provide more detailed information about the change, e.g. when too many messages were modified at the same time.

When the event fires, it must be assumed that the entire contents of the collection are no longer valid.