unit: MAPISessionUtils.pas
file path: ..\Library\
version: 2014.хх
uses Classes, Windows, ExtendedMAPI, SysUtils,
MAPIUtils, IMIEMTypes
Available functions:
function GetMAPISession - Initialize MAPI Subsystem and return IMAPISession Interface
procedure ReleaseMapiSession
- Logoff from MAPI Session and UnInitialize MAPI Subsystem.
A client application calls the ReleaseMapiSession function to end its
interaction with MAPI, begun with a call to the GetMAPISession function.
After ReleaseMapiSession is called, no other MAPI calls can be made by the
client.
function GetProfileName - Returns current MAPI Profile Name, for example as "Outlook"
function GetProfiles - Returns all available MAPI/Outlook profiles
function GetExchangeServerName - Returns Microsoft Exchange Server Name
function GetAddressBook - Returns interface to MAPI Address Book
procedure GetRecipientsFromAB - Displays the Outlook address book dialog box and returns an aray of TRecipientHead
function GetMAPIStoresTable - Returns the message store table that contains information about all the message stores in the session profile.
function GetMsgStoreType - Returns MAPI Store type - i.e. Local, Exchange Private, Exchange Public, etc..
function GetMAPIStores
- Returns an array of all available MsgStores
procedure ClearStoresHeadList - Clears the memory occupied by the TStoresHeadList structure returned by the function GetMAPIStores
function GetDefaultStore - Returns default MsgStore for the current MAPI Session
function GetMAPIStore
- Returns specific MsgStore from its entry identifier
function IsExchangeStore
- Returns True is MsgStore is an Exchange Server Store, as Mailbox Store,
as Public Store, as Delegated Store, etc..
procedure ReleaseMsgStore - Close and release IMsgStore.
function IsSameMAPIObject
- Compares the entry identifier with an opened MAPI property object
function IsSameEntryIDs -
Compares two entry identifiers to determine whether they refer to the same
object.
function GetProfileServiceVersion - Detect the version of Microsoft Exchange server in an Outlook (2007 and above) profile
function EnableReconnect - Enables the MAPI global catalog server reconnect logic to work correctly in a MAPI profile.
function DeleteProfile - Deletes a MAPI/Outlook profile.
function SelectABUsers
- Displays the Outlook address book dialog box.
function SelectABUsersEx - Displays the Outlook address book dialog box (extended version).
function ResolveRecipients
- Performs name resolution, assigning entry identifiers to recipients in a
recipient list.
function ForceSMTPAddress - Performs name resolution,
and converts Exchange-based email address into SMTP email address, i.e. converts
/O=ORGANIZATION_NAME/OU=EXCHANGE_GROUP/CN=RECIPIENTS/CN=USER_NAME to
USER_NAME@DOMAIN.COM
procedure AddPSTToProfile - Adds a PST (Personal Storage Table) file to and Outlook profile. If file does not exists, a new one is created.
function SvcAdminOpenProfileSection - Opens a Profile Section with full access
function ProvAdminOpenProfileSection - Opens a Profile Section with full access
procedure MarkExistingProviders
- Service (internal) function, mark/find providers
function FindUnmarkedProvider - Service (internal) function, mark/find providers
function GetExchangeGlobalAddressList - Returns Exchange Server Global Address List - GAL
procedure AddDelegateExchangeMailBox - Adds additional mailboxes to an existing mail profile
function GetMAPISession(const DlgHwnd: UINT_PTR = 0; const ProfileName: String = ''; const LogonFlags: Cardinal = MAPI_USE_DEFAULT; const FromService: Boolean = False; const MultiThreaded: Boolean = False): IMAPISession;
description
Initialize MAPI Subsystem and return
IMAPISession Interface
parameters
DlgHwnd - Handle for Logon Dialog. If it is 0 (zero) Logon Dialog will be
Modeless
ProfileName - Profile name. Specify it if you like to open explicit profile
LogonFlags - flags as MAPI_NO_MAIL and etc.. See MSDN documentation
for options
FromService - Is it Windows Service? See MSDN documentation for more
information.
MultiThreaded - Is it MultiThreaded applicaion? See MSDN documentation for more
information.
usage
// Get MAPI Session
MAPISession := GetMAPISession(Self.Handle, '', MAPI_LOGON_UI);
if Assigned(MAPISession) then
StoreList := GetMAPIStores(MAPISession);
procedure ReleaseMapiSession(var MAPISession: IMAPISession);
description
Logoff from MAPI Session and UnInitialize MAPI Subsystem
parameters
MAPISession - IMAPISession, obtained from GetMAPISession function
usage
// Log Off
// Close and clear MAPI Session
ReleaseMapiSession(MAPISession);
function GetProfileName(Const MAPISession: IMAPISession): String;
description
Returns current MAPI Profile Name, for example as "Outlook"
parameters
MAPISession - IMAPISession, obtained from GetMAPISession function
usage
// Get Profile name
StatusBar.Panels[0].Text:='Profile
name: ' + GetProfileName(MAPISession);
function GetProfiles: TStrings;
description
Returns all available MAPI/Outlook profiles. If profile is "default profile",
then Object member of TStrings item is equal to 1
parameters
None
usage
// Get Profiles
var
Profiles: TStrings;
iCount: Integer;
TempString: string;
begin
Profiles := GetProfiles;
if not Assigned(Profiles) then
Exit;
for iCount := 0 to Profiles.Count - 1
do
begin
TempString := Profiles.Strings[iCount] + ' - ' + BoolToStr(Boolean(Integer(Profiles.Objects[iCount])),
True);
OutputDebugString(PChar(TempString));
end;
FreeAndNil(Profiles);
end;
function GetExchangeServerName(Const MAPISession: IMAPISession): String;
description
Returns Microsoft Exchange Server Name
parameters
MAPISession - IMAPISession, obtained from GetMAPISession function
usage
ShowMessage(GetExchangeServerName(MAPISession));
function GetAddressBook(Const MAPISession: IMAPISession; UIParam: ULONG_PTR = 0; AllowsDialogs: Boolean = True): IAddrBook;
description
Returns interface to MAPI Address Book
parameters
MAPISession - IMAPISession, obtained from GetMAPISession
function
UIParam - A handle to the parent window of the common address dialog box and
other related displays
AllowsDialogs - if it is False - Suppresses the display of
dialog boxes
usage
// Get Address Book
AddressBook := GetAddressBook(MAPISession, Self.Handle);
// Get recipients
GetRecipientsFromAB(AddressBook, RecipientHeadList, rtBCc, Self.Handle);
procedure GetRecipientsFromAB(const AddressBook: IAddrBook; var Recipients: TRecipientsHeadList; FocussedType: TMAPIRecipientType = rtTo; UIParam: ULONG_PTR = 0; Const DialogTitle: String = 'Select Names');
description
Displays the Outlook address book dialog box and returns an aray of
TRecipientHead
parameters
AddressBook- IAddrBook, obtained from GetAddressBook
function
Recipients - An array of TRecipientHead
FocussedType - Indicates the particular text box control that should have the
initial focus when the modal version of the dialog box appears
UIParam - Handle of the parent window of the dialog box
DialogTitle - Text to be used as the title for the common address dialog box
usage
// Get Address Book
AddressBook := GetAddressBook(MAPISession, Self.Handle);
// Show Address Book and get recipients
GetRecipientsFromAB(AddressBook, RecipientHeadList, rtBCc, Self.Handle);
// Set Message Recipients
SetMsgRecipients(MAPIMessage,
AddressBook, RecipientHeadList, Self.Handle);
function GetMAPIStoresTable(const MAPISession: IMAPISession; out IsUnicode: Boolean): IMAPITable; overload;
function GetMAPIStoresTable(const MAPISession: IMAPISession): IMAPITable; overload;
description
Returns the message store table that contains information about all
the message stores in the session profile.
parameters
MAPISession -
IMAPISession interface
IsUnicode - Boolean. Indicates that the session does
support/not support Unicode.
remarks
The complete list of columns in the message store table are:
PR_INSTANCE_KEY - Contains a value that uniquely identifies a row in a
table.
PR_ENTRYID - Contains a MAPI entry identifier used to open and edit
properties of a particular MAPI object.
PR_DISPLAY_NAME - Contains the display name for a given MAPI object.
PR_PROVIDER_DISPLAY - Contains the vendor-defined display name for a service
provider.
PR_DEFAULT_STORE - Contains TRUE if a message store is the default message
store in the message store table.
PR_MDB_PROVIDER - Contains a provider-defined
MAPIUID structure that indicates the type of the message store.
usage
procedure TfrmMain.BuildFoldersTree;
var
MAPISession: IMAPISession;
MAPITable: IMAPITable;
iCount: Integer;
begin
MAPISession := GetMAPISession(self.Handle);
if not Assigned(MAPISession) then
Exit;
MAPITable := GetMAPIStoresTable(MAPISession);
if not Assigned(MAPITable) then
Exit;
with TMAPITable.Create(MAPITable) do
begin
for iCount := 0 to Count - 1 do
CopyStoreHead(MailboxTreeView, Row[iCount]);
Free;
end;
end;
function GetMsgStoreType(const Provider: TBytes): TMsgStoreType; overload;
function GetMsgStoreType(const MsgStore: IMsgStore): TMsgStoreType; overload;
description Returns MAPI Store type - i.e. Local, Exchange Private, Exchange Public, etc..
parameters
Provider - TBytes.
PR_MDB_PROVIDER value as TBytes.
MsgStore - IMsgStore
interface.
usage
var
oMAPIStore: TMAPIStore absolute Result;
begin
oMAPIStore := nil;
if not Assigned(Store) then
Exit;
case GetMsgStoreType(Store) of
stUndefined:
oMAPIStore := TMAPIStore.Create(Store);
stExchangePrivate:
oMAPIStore := TMAPIExchangePrivateStore.Create(Store);
stExchangeDelegate:
oMAPIStore := TMAPIExchangeStore.Create(Store);
stExchangePublic:
oMAPIStore := TMAPIExchangePublicStore.Create(Store);
stLocalPersonal:
oMAPIStore := TMAPILocalPersonalStore.Create(Store);
end;
function GetMAPIStores(const MAPISession: IMAPISession): TStoresHeadList;
description
Returns an array of all available MsgStores
parameters
MAPISession - IMAPISession, obtained from GetMAPISession function
usage
var
StoreList: TStoresHeadList = nil;
...
...
MAPISession := GetMAPISession(Self.Handle, '', MAPI_LOGON_UI);
if Assigned(MAPISession) then
StoreList := GetMAPIStores(MAPISession);
AddStores;
...
...
procedure AddStores;
var
iCount: Integer;
LenA: Integer;
TreeNode: TTreeNode;
begin
LenA := Length(StoreList);
if LenA < 1 then
Exit;
for iCount := 0 to LenA - 1 do
begin
if StoreList[iCount].IsDefault then
TreeNode := MailboxTreeView.Items.AddObjectFirst(nil, StoreList[iCount].DisplayName,
@StoreList[iCount])
else
TreeNode := MailboxTreeView.Items.AddObject(nil, StoreList[iCount].DisplayName,
@StoreList[iCount]);
if StoreList[iCount].IsDefault then
TreeNode.ImageIndex := 0
else
TreeNode.ImageIndex := 1;
TreeNode.SelectedIndex := TreeNode.ImageIndex;
TreeNode.Expanded := False;
end;
end;
procedure ClearStoresHeadList(var StoresHeadList: TStoresHeadList);
description
Clears the memory occupied by the TStoresHeadList structure returned by the function GetMAPIStores
parameters
StoresHeadList - TStoresHeadList returned by the function GetMAPIStores
usage
var
StoreList: TStoresHeadList = nil;
...
...
MAPISession := GetMAPISession(Self.Handle, '', MAPI_LOGON_UI);
if Assigned(MAPISession) then
StoreList := GetMAPIStores(MAPISession);
AddStores;
ClearStoresHeadList(StoreList);
...
...
function GetDefaultStore(const MAPISession: IMAPISession; const OnLine: Boolean = True; const AllowDialog: Boolean = True; const DialogHandle: UINT_PTR = 0): IMsgStore;
description
Returns default MsgStore for the current MAPI Session
parameters
MAPISession -
IMAPISession, obtained from GetMAPISession
function
OnLine - if true, forces the live, on-line IMsgStore. Otherwise local, cached
store can be used. applicable only if IMsgStore resides on remote server, as
Microsoft Exchange Server.
AllowDialog - if it is False - Suppresses the display of
dialog boxes, as prompt for message store password
DialogHandle -handle to the parent window of the common address dialog box and
other related displays
usage
fMAPISession := GetMapiSession(Self.Handle, '', MAPI_LOGON_UI);
// Get Profile name
FProfileName := GetProfileName(fMAPISession);
StatusBar.SimpleText := 'Profile name: ' + FProfileName;
// Get Default Store
fMsgStore := GetDefaultStore(fMAPISession);
// Get Calendar folder
fMsgFolder := GetDefaultFolder(fMsgStore, oFolderCalendar);
function GetMAPIStore(const MAPISession: IMAPISession; EntryID: TBytes; const OnLine: Boolean = True; const ReadOnly: Boolean = True; const Temporary: Boolean = False; const AllowDialogs: Boolean = False; const DlgHwnd: UINT_PTR = 0): IMsgStore;
description
Returns specific MsgStore from its entry identifier
parameters
MAPISession -
IMAPISession, obtained from GetMAPISession
function
EntryID - unique entry identifier (PR_ENTRYID)
OnLine - if true, forces the live, on-line IMsgStore. Otherwise local, cached
store can be used. applicable only if IMsgStore reside on remote server, as
Microsoft Exchange Server.
ReadOnly - if True, do not requests read/write permission to the message store
Temporary - Instructs MAPI that the message store is not permanent and should
not be added to the message store table
AllowDialog - if it is False - Suppresses the display of
dialog boxes, as prompt for message store password
DlgHwnd -handle to the parent window of the common address dialog box and other
related displays
usage
var
StoreList: TStoresHeadList = nil;
...
...
MAPISession := GetMAPISession(Self.Handle, '', MAPI_LOGON_UI);
if Assigned(MAPISession) then
StoreList := GetMAPIStores(MAPISession);
...
...
// Get the first Exchange Server Public store
for iCount:=0 to
Length(StoreList) - 1 do
if StoreList[iCount].StoreType = stExchangePublic
then
begin
fMsgStore := GetMAPIStore(MAPISession, StoreList[iCount].ID);
break;
end;
function IsExchangeStore(const MsgStore: IMsgStore): Boolean;
description
Returns True is MsgStore is an Exchange Server Store, as Mailbox Store,
Public Store, Etc..
parameters
MsgStore - IMsgStore interface
usage
// Check for Exchange Store
ListBox.Items.Add('Is Exchange Store: '+ BooltoStr(IsExchangeStore(fMsgStore),
True));
procedure ReleaseMsgStore(MsgStore: IMsgStore);
description
Close and release IMsgStore
parameters
MsgStore - IMsgStore interface
usage
// Check if opened MsgStore is same as the
target MsgStore. if it is a different store, close the current store and open
target store
if not IsSameMAPIObject(MAPISession, MAPIStore,
TargetStoreID) then
begin
ReleaseMsgStore(MAPIStore);
MAPIStore := GetMAPIStore(MAPISession, TargetStoreID);
end;
function IsSameMAPIObject(const MAPISession: IMAPISession; const MAPIProperty: IMAPIProp; EntryID: TBytes): Boolean;
description
Compares the entry identifier with an opened MAPI property object (IMsgStore,
IMAPIFolder, IMessage, etc..) to determine whether it refer to the same object.
parameters
MAPISession -
IMAPISession interface
MAPIProperty - an already opened MAPI property object (as
IMsgStore,
IMAPIFolder,
etc..) to be compared
EntryID - entry identifier to be compared (PR_ENTRYID)
usage
// Check if opened MsgStore is same as the
target MsgStore. if it is a different store, close the current store and open
target store
if not IsSameMAPIObject(MAPISession, MAPIStore,
TargetStoreID) then
begin
ReleaseMsgStore(MAPIStore);
MAPIStore := GetMAPIStore(MAPISession, TargetStoreID);
end;
function IsSameEntryIDs(const MAPISession: IMAPISession; const EntryID1: TBytes; const EntryID2: TBytes): Boolean;
description
Compares two entry identifiers to determine whether they refer to the same object.
parameters
MAPISession -
IMAPISession interface
EntryID1 - entry identifier to be compared (PR_ENTRYID)
EntryID2 - entry identifier to be compared (PR_ENTRYID)
function GetProfileServiceVersion(const ProfileName: string;
var ServerVersion: ULONG; var MajorVersion, MinorVersion, Build, MinorBuild: WORD;
var FoundServerVersion, FoundServerFullVersion: Boolean): Boolean;
overload;
function GetProfileServiceVersion(const MAPISession: IMAPISession;
var ServerVersion: ULONG; </p>MajorVersion, MinorVersion, Build, MinorBuild: WORD;
var FoundServerVersion, FoundServerFullVersion: Boolean): Boolean;
overload;
description
Detect the version of Microsoft Exchange server in an Outlook (2007 and above) profile
function EnableReconnect(const ProfileName: AnsiString): HRESULT;
description
Enables the MAPI global catalog server reconnect logic to work correctly in a MAPI profile.
For more information please see Microsoft article: How to enable the MAPI global catalog server reconnect logic
function DeleteProfile(ProfileName: AnsiString): HRESULT;
description
Deletes a MAPI/Outlook profile.
function SelectABUsers(const MAPISession:
IMAPISession; const HNDL: ULONG_PTR; out
EntryIDs: TBytesArray; const OneAddressOnly: Boolean = False): Boolean; overload;
function SelectABUsers(const AddrBook:
IAddrBook; const HNDL: ULONG_PTR; out EntryIDs:
TBytesArray; const OneAddressOnly: Boolean = False): Boolean; overload;
description
Displays the Outlook address book dialog box.
parameters
MAPISession -
IMAPISession interface / AddrBook - IAddrBook interface
HNDL - Parent window handle
EntryIDs - EntryID array of selected users (PR_ENTRYID)
OneAddressOnly - The user can select exactly
one recipient (True) instead of
multiple recipients from a list
(False). Default - False
function SelectABUsersEx(const MAPISession:
IMAPISession; const HNDL: ULONG_PTR; var
Recipients: TRecipientsHeadList; const OneAddressOnly: Boolean
= False; const ForceResolving: Boolean = True; ToLabel: String
= 'To'; CcLabel: String = 'Cc'; BCCLabel: String = 'BCc'; const FocusLabel:
TMAPIRecipientType = rtTo; const DialogTitle: String = 'Select
Names'; const NewEntryTitle: string = 'New Recipient';
const DestWellsTitle: string = 'Recipients'; ForceSMTP: Boolean =
False): Boolean; overload;
function SelectABUsersEx(const AddrBook:
IAddrBook; const HNDL: ULONG_PTR; var
Recipients: TRecipientsHeadList; const OneAddressOnly: Boolean
= False; const ForceResolving: Boolean = True; ToLabel: String
= 'To'; CcLabel: String = 'Cc'; BCCLabel: String = 'BCc';
const FocusLabel: TMAPIRecipientType = rtTo; const
DialogTitle: String = 'Select Names'; const NewEntryTitle: string = 'New
Recipient';
const DestWellsTitle: string = 'Recipients'; ForceSMTP: Boolean
= False): Boolean; overload;
description
Displays the Outlook address book dialog box (extended version).
parameters
MAPISession -
IMAPISession interface / IAddrBook - IAddrBook interface
HNDL - Parent window handle
Recipients - Recipients array of selected users
OneAddressOnly - The user can select exactly
one recipient (True) instead of
multiple recipients from a list
(False). Default - False
ForceResolving - Performs name resolution, assigning entry identifiers to
recipients (True). Default - True
ToLabel, CcLabel, BCCLabel - Labels for buttons associated with each of the text
box controls. Default values: 'To', 'Cc', 'BCc'
FocusLabel - Indicates the particular text box control that should have the
initial focus. Default - rtTo
DialogTitle - Text to be used as the title for the common address dialog box.
Default - 'Select Names'
NewEntryTitle - Text to be used as the button label for the button that invokes
either the New Entry dialog box or another dialog box. Default - 'New Recipient'
DestWellsTitle - text to be used as a title for the recipient text box controls
that can appear in the modal version of the common address dialog box. Default -
'Recipients'
ForceSMTP - When selected recipients reside inside Microsoft Exchange Global
Address Book, replaces 'EX' address type to 'SMTP' address type. Default - False
function ResolveRecipients(const
MAPISession:
IMAPISession; const HNDL: ULONG_PTR; var
Recipients: TRecipientsHeadList; const AllowDialog: Boolean =
True): Boolean; overload;
function ResolveRecipients(const AddrBook:
IAddrBook; const HNDL: ULONG_PTR; var
Recipients: TRecipientsHeadList; const AllowDialog: Boolean =
True): Boolean; overload;
description
Performs name resolution, assigning entry identifiers to recipients in a
recipient list.
parameters
MAPISession -
IMAPISession interface / AddrBook - IAddrBook interface
HNDL - Parent window handle
Recipients - Recipients array of selected users
AllowDialog - Displays a dialog box to
prompt the user for additional name resolution information.
usage
var
EntryIDs: TRecipientsHeadList;
begin
SetLength(EntryIDs, 1);
EntryIDs[0].DisplayName:='KokoBoko';
ResolveRecipients(MAPISession, Self.Handle, EntryIDs, True);
end;
description
Performs name resolution, and converts Exchange-based email address into
SMTP email address, i.e. converts /O=ORGANIZATION_NAME /OU=EXCHANGE_GROUP
/CN=RECIPIENTS /CN=USER_NAME to USER_NAME@DOMAIN.COM
parameters
MAPISession -
IMAPISession interface / AddrBook - IAddrBook interface
Recipients - Recipient
HNDL - Parent window handle
procedure AddPSTToProfile(const
ProfileName: AnsiString; const PSTFileNameAndPath: AnsiString;
const DisplayName: AnsiString = '';
const Password: AnsiString = ''; const
ParentWnd: ULONG_PTR = 0; const CreateAsUnicode: Boolean =
True; const AllowUI: Boolean = True;
AllowWarning: Boolean = True);
description
Adds a PST (Personal Storage Table) file to and Outlook profile. If file does not exists, a new one is created.
parameters
ProfileName - Profile name
PSTFileNameAndPath - Path and PST name
DisplayName - PST Display name
Password - PST password
ParentWnd - Parent window
CreateAsUnicode - Enable creating Unicode-enabled format of PST file.
AllowUI - The message service should display its configuration property sheet
only if the service is not completely configured.
AllowWarning - Displays the message "You must restart Outlook for these changes
to take effect."
function SvcAdminOpenProfileSection(const SvcAdmin: IMsgServiceAdmin; UID: PMAPIUID; pInterface: PGUID; out ProfSect: IProfSect): HRESULT;
description
Opens a Profile Section with full access
parameters
SvcAdmin - IMsgServiceAdmin
UID - PMAPIUID
pInterface - PGUID
ProfSect - IProfSect
For more information please see Microsoft article: How to enable the MAPI global catalog server reconnect logic
function ProvAdminOpenProfileSection(const ProvAdmin: IProviderAdmin; UID: PMAPIUID; pInterface: PGUID; out ProfSect: IProfSect): HRESULT;
description
Opens a Profile Section with full access
parameters
ProvAdmin - IProviderAdmin
UID - PMAPIUID
pInterface - PGUID
ProfSect - IProfSect
For more information please see Microsoft article: How to enable the MAPI global catalog server reconnect logic
procedure MarkExistingProviders(const ServiceAdmin: IMsgServiceAdmin; AddMark: Boolean);
description
Service (internal) function, mark/find providers
parameters
ServiceAdmin - IMsgServiceAdmin
AddMark - BooleanTop
function FindUnmarkedProvider(const ServiceAdmin: IMsgServiceAdmin; out RowSet: PSRowSet): Boolean;
description
Service (internal) function, mark/find providers
parameters
ServiceAdmin - IMsgServiceAdmin
RowSet - PSRowSetTop
parameters
MAPISession - IMAPISession
HNDL - ULONG_PT
AddrBook - IAddrBook
procedure
AddDelegateExchangeMailBox(const ProfileName: AnsiString;
const MailboxDisplay: WideString; const
MailboxDN, Server, ServerDN: AnsiString;
const ParentWnd: ULONG_PTR = 0);
description
Adds additional mailboxes to an existing mail profile
parameters
ProfileName - AnsiString
MailboxDisplay - WideString
MailboxDN - AnsiString
Server - AnsiString
ServerDN - AnsiString
ParentWnd: ULONG_PTR
Copyright © 2021 IMIBO
Privacy Statement |