RDOSession object

RDOSession object is the top level object in the RDO
object hierarchy from which all
other objects are retrieved. To be able to use RDOSession object properties and
methods, log on to a MAPI session first by either setting the MAPIOBJECT
property or calling Logon, LogonExchangeMailbox or LogonPstStore methods.

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

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

The example below connects to the
MAPI session used by Outlook (Application object below refers to an instance of
the Outlook.Application object) and prints out the subjects
of all messages in the Inbox folder:

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

returns
RDOCategories collection representing categories from the local machine

RDOCategories collection first attempts to read the category list
from the default store in the profiles (where Outlook 2007 stores it).
If no categories are present in the default store, Redemption tries to
read the categories list from the registry if Outlook 2003 or older is
installed.

set Session =
CreateObject("Redemption.RDOSession")
Session.Logon
set Categories = Session.Categories
for each Category in Categories
Debug.Print Category.Name
next

ConnectEncryptData

Boolean, read/write.

Setting this property to true forces LogonExchangeMailbox
method to set the PR_PROFILE_UI_STATE property to 0x4100 to force MAPI to
encrypt the data.

Setting this property to true forces LogonExchangeMailbox
method to set the CONNECT_IGNORE_NO_PF bit in the PR_PROFILE_CONNECT_FLAGS
property to tell MAPI that it is Ok to connect even if the PF store is not
available.

Note that only Outlook 2010 and the standalone version of MAPI understand this
property.

CurrentUser

RDOAddressEntry, read-only.
Returns the address entry representing the default user identity in the
current MAPI session

set Session =
CreateObject("Redemption.RDOSession")
Session.Logon

MsgBox "Current user's name:
" & Session.CurrentUser.Name

CurrentWindowsUser

RDOAddressEntry, read-only. Returns
the address entry representing the identity of the current Windows user.

Accessing this property does
not require an active MAPI session, i.e. it can be accessed even if
Logon method had not been called.

Note that the properties of
the current Windows user are retrieved directly from the Active
Directory, which means the parent process must be running under an
identity of a domain user and the AD server must be accessible.

Note: the following
RDOAddressEntry properties will return
null in the current version: Delegates, IsDelegateFor,
IsMemberOfDL, Reports

Returns an
rdoExchangeConnectionMode constant that indicates the current
connection mode the user is using. Read-only.

rdoExchangeConnectionMode can be one of the following constants:

olCachedConnectedDrizzle

600

The account is using
cached Exchange mode such that headers are downloaded first,
followed by the bodies and attachments of full items.

olCachedConnectedFull

700

The account is using
cached Exchange mode on a Local Area Network or a fast
connection with the Exchange server. The user can also select
this state manually, disabling auto-detect logic and always
downloading full items regardless of connection speed.

olCachedConnectedHeaders

500

The account is using
cached Exchange mode on a dial-up or slow connection with the
Exchange server, such that only headers are downloaded. Full
item bodies and attachments remain on the server. The user can
also select this state manually regardless of connection speed.

olCachedDisconnected

400

The account is using
cached Exchange mode with a disconnected connection to the
Exchange server.

olCachedOffline

200

The account is using
cached Exchange mode and the user has selected
Work Offline from the File menu.

olDisconnected

300

The account has a
disconnected connection to the Exchange server.

olNoExchange

0

The account does not
use an Exchange server.

olOffline

100

The account is not
connected to an Exchange server and is in the classic offline
mode. This also occurs when the user selects Work
Offline from the File menu.

olOnline

800

The account is
connected to an Exchange server and is in the classic online
mode.

ExchangeMailboxServerName

Returns a String value that
represents the name of the Exchange server on which the active mailbox
is hosted. Read-only.

ExchangeMailboxServerVersion

Returns a String value that
represents the full version of the Exchange server on which the active
mailbox is hosted.

If Exchange is not used by
the current profile, an empty string is returned.

Read-only.

FastShutdownSupported

Boolean, read-only. Returns
true if the current version of Outlook and all providers in the profile
support fast shutdown.

set Session =
CreateObject("Redemption.RDOSession")
Session.Logon
Debug.Print "Stores in the profile: " & Session.Stores.Count
if Session.FastShutdownSupported Then
Session.DoFastShutdown
Else
Session.Logoff
End If

JunkEmailOptions

Returns
RDOJunkEmailOptions object
representing profile-wide Junk E-mail options, which are saved in the
profile data (registry) as well as the primary message store in case of
an Exchange mailbox.

Profile and mailbox options
are reconciled based on the last modification time.

set Session =
CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set JunkOptions = Session.JunkEmailOptions
for each address in JunkOptions.BlockedSenders
Debug.Print address
next

LoggedOn

boolean, read-only. Returns
true if logged on, false otherwise.

if not Session.LoggedOn Then

Session.Logon

End If

MAPIOBJECT

IMAPISession Extended MAPI
object, read-write.
Allows to set the MAPI session to be used without explicitly logging to
a MAPI profile. Useful if RDO is used in an environment where a MAPI
session is already available (e.g. a COM add-in).

If you set the MAPIOBJECT property, do not call RDOSession.Logoff as
that will render the original session invalid as well.

Important note: if you set this property to Namespace.MAPIOBJECT property from the Outlook Object Model and your
code is running outside the outlook.exe address space (i.e. it is not
a COM add-in) some RDO features (RDOFolder.ACL,
RDOPSTStore.PstPath, GetSharedDefaultFolder, GetSharedMailbox, etc) will not function properly
due to bugs in the MAPI COM marshaling support.

'use the same MAPI object
as Outlook

'Namespace is returned
from Application.GetNamespace("MAPI") in OOM

set Session =
CreateObject("Redemption.RDOSession")

Session.MAPIOBJECT =
Namespace.MAPIOBJECT

MAPITimeoutShort

Boolean, read/write.
By default this property is true, which causes Redemption to use the
MAPI_TIMEOUT_SHORT flag when logging to a MAPI profile (Logon,
LogonExchangeMailbox, LogonPstStore). If one of the MAPI providers does
not finish initialization within 5 seconds or so, the call will return
MAPI_E_TIME_OUT error.

Reset this property to false if you are accessing Exchange over a slow
or high latency network.

Offline

Boolean. read/write. Sets the "Work Offline" option in the current
session.
Note that to affect the Offline state in Outlook, you must use the MAPI
session returned from Namespace.MAPIOBJECT property in OOM and run in
the outlook.exe address space (which means your code must be in an
Outlook COM add-in or a VBA script).

Methods

Logoff

Logs off from the current
MAPI session.

Note:
If you are setting the RDOSession.MAPIOBJECT property to
Namespace.MAPIOBJECT from the Outlook Object Model or another RDOSession,
do not call Logoff as it will render the original session invalid.

LogonPstStore method,
in addition to the Logon and LogonExchangeMailbox methods
and setting the MAPIOBJECT property, allows to log to MAPI.

LogonPstStore, similar
to the LogonExchangeMailbox method, creates a temporary profile,
adds the specified PST store (new or existing) to that temporary
profile, and log to the profile. The temporary profile is immediately
deleted, so it will never be visible to an end user. LogonPstStore
is useful if you need to process a PST file without explicitly creating
a new profile using ProfMan and/or without
adding the temporary PST store to an existing profile using
RDOSession.Stores.AddPstStore:

Path - string,
required, path to
the PST file. If the file does not exist, a new PST store will be
created.

Format - integer,
optional. The format of the PST file if a new store is to be created.
Can be one of the rdoStoreType enums: olStoreDefault (1), olStoreUnicode (2), olStoreANSI (3).

DisplayName - string,
optional. The display name of the store if one is to be created.

Password - string, optional. The PST file pssword.

Encryption - one of
the rdoPstEncryption enums, optional. Specifies the encryption level to
be used when creating a new PST file.

Returns
RDOPstStore object. The same
store can be retrieved after calling LogonPstStore from the
RDOSession.Stores.DefaultStore.

'create initialize first
RDOSession object that shared the MAPI session with Outlook
set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT'create and initialize a temporary session that uses a new or
existing PST file
set TempSession = CreateObject("Redemption.RDOSession")
TempSession.LogonPstStore "c:\temp\archive_test.pst", 1, "Archive PST
Store"'delete all folders in the temporary PST store to make sure there is
no collision
set ArchiveRootFolder = TempSession.Stores.DefaultStore.IPMRootFolder
set SubFolders = ArchiveRootFolder.Folders
for i = SubFolders.Count to 1 step - 1
SubFolders.Remove(i)
next'copy the contents of the default store used by the first session
'to the PST file used by the second session
for each Folder in Session.Stores.DefaultStore.IPMRootFolder.Folders
Folder.CopyTo(ArchiveRootFolder)
next

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

GetFolderFromPath(FolderPath)

Returns an RDOFolder object given its full path, e.g. "\\Personal
Folders\Inbox". Note that a folder path (unlike the entry id)
is not guaranteed to be unique, e.g. you can have multiple stores called
"Personal Folders", in which case GetFolderFromPath can fail.

FolderPath - string, full folder path in the form "\\Store
name\Parent Folder Name\Folder". If store name is not specified,
the default store is assumed.

Creates a new MSG file and
returns a message (RDOMail or one of the
derived types, such as RDOContactItem)
created on top of MSG file.

Unlike
RDOSession.GetMessageFromMsgFile
(which can also create a new MSG file if CreateNew parameter = true),
you can specify the MSG file format (default, Unicode or ANSI) and the
message class of the new item so you always get back the right item kind
rather than the generic RDOMail.

'Create a contact (can be
any other type of item) on top of a new MSG file
'Below we will get back a contact since we explicitly specify the
message class ("IPM.Contact").
'The MSG file will be created in the Unicode format fro Outlook 2003 or
higher or ANSI format
'for the older versions of Outlook (mffDefault = 1)'The last two parameters are optional
set Session = CreateObject("Redemption.RDOSession")
Session.Logon 'don't really need to call this
methodset Contact = Session.CreateMessageFromMsgFile("c:\temp\TestContact.Msg",
"IPM.Contact", 1)
Contact.FirstName = "Dmitry"
Contact.LastName = "Streblechenko"
Contact.EMail1Address = "redemption@dimastr.com"
Contact.Save

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.

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.

set Session =
CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set Folder = Session.GetFolderFromID(MAPIFolder.EntryID)
for each Msg in Folder.Items
Debug.Print(Msg.Subject)
next

set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT
set ABDialog = Session.GetSelectNamesDialog
ABDialog.ActiveRecipientSelector = olBCC
set Contacts = Session.GetDefaultFolder(olFolderContacts)
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

GetStoreFromID(EntryIDStore,
Flags)

EntryIDStore - string
representing the entry id of the store.

Flags - (optional). integer flags to be used to call
IMAPISession::OpenMsgStore. 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 MDB_ONLINE(0x100) + MAPI_BEST_ACCESS
(0x10) will open the store in the best access mode bypassing the cached
store.

Flags - (optional). integer flags to be used to call
IAddrBook::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 address entry in the best access
mode bypassing the cached store.

Flags - (optional). integer flags to be used to call
IAddrBook::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 address list in the best access
mode bypassing the cached store.

ProfileOrFileName -
variant, optional. Either a string (profile name of file name) or an
RDOStore object.

If not specified, and there
is no active MAPI session (i.e. you did not call Logon or set the
MAPIOBJECT property), will return the nick names for the default
profile. If there is an active session, the nicknames form the current
profile will be returned.

If specified, Redemption will
check if the profile with the given name exists (see example) and return
nicknames for that profile.

If the profile with the given
name does not exist, Redemption assumes that a fully qualified file name
is specified (e.g. "C:\temp\Nicknames.NK2") and will attempt to open the
file.

If an
RDOStore object is passed, GetNicknames
will attempt to retrieve the nicknames stored in a hidden item in the
Inbox of the specified store.

If neither profile nor file
exist, or the no store is specified, an error will be raised.

Normally, to retrieve an RDO object from an Outlook object, it is
necessary to call
RDOSession.GetMessageFromID.
That call however opens another instance of the message, and if
modifications are made to both objects, can produce an conflict error.
GetRDOObjectFromOutlookObject method will use the MAPIOBJECT
property exposed by the Outlook objects in the same manner used by the
Safe*Item objects.

Returns an
RDOAddressEntry object corresponding to
the specified name, which can be a display name, primary SMTP address,
NT style user name (domain\user), etc. GetWindowsUser
(just like RDOSession.CurrentWindowsUser)
does not require an active MAPI session and can be called without
calling Logon or LogonExchangeMailbox.

Name - string. Name to be resolvedNameKind - one of the rdoWindowsUserNameKind enum
values:

Checks whether the two entry
ids refer to the same MAPI object. Note that entry ids cannot be
directly compared and multiple entry ids can refer to the same object
(e.g. in case of long term vs. short term entry id).

Displays the Pick Folder
dialog box. This is a modal dialog box which means that code execution
will not continue until the user either selects a folder or cancels the
dialog box. Returns an
RDOFolder object corresponding to the folder
that the user selects in the dialog box. Returns Nothing when the dialog
box is canceled by the user.

SelectedFolder -
optional,
RDOFolder. If specified, this folder will be
initially selected. If not specified, the Inbox folder is selected when
the dialog is displayed.

Caption - optional,
string. If specified, determines the Select Folder dialog caption. If
not specified, defaults to "Select Folder" (localized
appropriately in French/German/Italian/Portugese/Russian/Spanish along
with other dialog box controls).

ParentWindow -
optional, integer. If specified, the handle of the dialog's parent
window. If not specified, the dialog is shown as a child of the
currently active window.

Flags - optional. Can
be a combination of the following rdoPickFolderFlags enum values:

sffHideNewButton (1) -
hides the "New" button, preventing the user from creating a new folder.

pffHideParentFolders (2) - displays only the specified folders
and its subfolders (see the screenshot)

pffNoSizing (4) - prevents the user from resizing the dialog.

pffHidePublicFoldersStore
(8) - hides the Public Folders store but leaves all the other stores
visible (unless pffHideParentFolders is also specified).

AllowedFolderType - optional. One of the rdoItemType enums. If
not specified, all folders are displayed. If is specified, only the
folders with the DefaultItemType property matching the specified value
are displayed.

'replacement for
Namespace.PickFolder in OOM
'that allows to specify the initial folder
set Session = CreateObject("Redemption.RDOSession")
Session.MAPIOBJECT = Application.Session.MAPIOBJECT'convert Outlook.Folder to Redemption.RDOFolder
set rFolder =
Session.GetFolderFromID(Application.ActiveExplorer.CurrentFolder.EntryID)
set rFolder = Session.PickFolder(Folder, "Please select a folder")
if Not (rFolder Is Nothing) Then'convert Redemption.RDOFolder back to Outlook.Folder
set oFolder =
Application.Session.GetFolderFromID(rFolder.EntryID)
MsgBox oFolder.Name
End If

DoFastShutdown

Shuts down MAPI in the
current process space. No MAPI calls will be allowed if this method
succeeds.

An error will be raised if
the current version of Outlook and all providers in the profile do not
support fast shutdown.

set Session =
CreateObject("Redemption.RDOSession")
Session.Logon
Debug.Print "Stores in the profile: " & Session.Stores.Count
if Session.FastShutdownSupported Then
Session.DoFastShutdown
Else
Session.Logoff
End If

Events:

OnNewMail(EntryID)

Fires when a new message is
delivered to the Inbox of the default store.

EntryID - string,
entry id (in hex) of the newly delivered message. Note that under
Exchange, the entry id is a short term entry id. To retrieve the long
term entry id, open the message (e.g. using RDOSession.GetMessageFromID),
then read the EntryID property from the RDOMail
object.