IMIBO - Down To The Metal

Home

Development

Partners

Resellers

About

After a few years of investigating and building MAPI clients applications, we shifted part of our development team to the "MAPI inferno" - the service providers. This area of MAPI cannot be done with any kind of third-party custom MAPI components we know - they all have proved inapplicable here.

(Extended MAPI in DELPHI - Service Providers)
AKA MAPI Inferno

This section of our DEVELOPMENT site is for MAPI Service Providers. That means that you have to cover the following requirements: Very good (expert) DELPHI knowledge (this does not includes knowledge for working with third party components and VCLs), good understanding of Low-Level Microsoft API (functions, structures, pointers, memory managements, etc..), very good Extended MAPI background, and not last - strong will to learn more and investigate further.

After a few years of investigating and building MAPI clients applications, we shifted part of our development team to the "MAPI inferno" - the service providers. This area of MAPI cannot be done with any kind of third-party custom MAPI components we know - they all have proved inapplicable here. Each MAPI service provider is unique, and moreover - they work in opposite sides.

As suggested by some of our readers, this part of MAPI is not well documented. The reason? It is in the background of many Microsoft commercial products (including Microsoft Exchange Server). You can find basic information in MSDN, but the essentials are hidden. If you are "strong-headed" enough, maybe after a few weeks of digging, you could find some scraps at Google. There are only very few publications - one from Microsoft, dating from 1996, and another good is "Inside MAPI" - Microsoft (again) Press book (1996) - out of print. In June 11, 1996 Microsoft shipped the first version of Exchange server (Exchange Server 4.0) and stopped any development of documentation and also stopped producing any examples. Only some revisions of published web pages (if they are not removed).

There are three common types of MAPI service providers:

- Address book providers
- Message store providers
- Transport providers

We'd translated from the old C (not C++), these three fundamental MAPI service providers. They have only a basic functionality, but if you have enough enthusiasm - you can improve then further.

You can see also Delphi & ADO & MAPI Together - our implementation of some Extended MAPI service providers, that mix ADO DB (Active Data Objects) and Extended MAPI.

See a few screen shoots!

The first one, available for download MAPI service provider, is the compiled version of the Sample Address
Book Provider Sample (DELPHI 6 edition).

DELPHI Flat File Address Book Provider
This sample supports a single read-only container with names read from a flat binary file containing display names and e-mail addresses. It supports one-off templates and all configuration options.

It is about 49 000 lines (some of them shared with the Peer Transport Provider) without blanks (a monstrous job!) translated from C code, with original comments from the Microsoft developers. Moreover, the code includes DELPHI improvements (we haven't had the patience to leave part of the code as it used to be, also the side-by-side translation doesn't mean a working application.). In addition, the package includes a simple editor (not provided from Microsoft), which can edit this read-only AB provider. This was compiled with using DELPHI 6 and the improved by us version is tested with Exchange client (shipped with Windows NT 4.0), Outlook 97, Outlook 2000, Outlook 2002 (XP) and Outlook 2003 - (the original C code works fine only with the Exchange client).

Details (according the original C code and Microsoft Readme.txt file):
The sample address book provider is based on a read-only file of fixed-length records (.SAB File). Each record contains the display name and e-mail address of a messaging user. This file supplies the contents of a single, read-only address container, which contains only e-mail users. The sample address book supports one e-mail address type; it is hard-coded to MSPEER.

Upported Features:
Table restrictions. The sample address book implements the two most commonly used types of restrictions for an address book: prefix match and ANR. It does not implement the full MAPI restriction language, and restrictions are supported only on the display name.

Incremental searching.
Details. The sample address book implements its own details display table for messaging users. There are two sets of properties, divided into two pages. The first page has the standard properties: display name, e-mail address, and address type. The second page has an example of almost every control type implemented in MAPI display tables (the data is hard-coded, not drawn from
the address book). There is a template identifier for messaging user details, which enables all details to be supported for users copied from the sample address book to the personal address book. Details are also supported for the top-level directory, including the ability to change the .SAB file from the details pane. The directory details view uses a notification to update the display when the .SAB file is changed.

Custom recipients (one-offs). The sample address book implements a one-off table with a set of properties different from the native details; these properties combine to form the e-mail address. The template identifier enables messaging users to be added to the personal address book, or directly to a message, using a special dialog box; processing is routed through the sample address book, which has the ability to generate the e-mail address from the properties entered in the dialog box.

Advanced search dialog box. The sample address book implements an advanced search dialog box, accessible by choosing the Advanced button on the MAPI addressing dialog box. In reality, the advanced search is only slightly different from the standard search, which uses an ANR restriction.

Configuration interfaces. The sample address book supports both interactive and programmatic configuration.

Unsupported:
Distribution lists. Creating, deleting, and modifying entries from particular user.
Multi-valued properties. Named properties.

Download DEMO

DELPHI Peer Transport Provider

It is about 47 000 lines (some of them shared with the Address Book Provider), without blanks, translated from C code, with original comments from the Microsoft developers. Moreover, the code includes DELPHI improvements (the side-by-side translation doesn't mean a working application.). In addition, the package includes a simple “installer” (not provided from Microsoft).

This was compiled with DELPHI 6 and improved by us version was tested with Exchange client (shipped with Windows NT 4.0), Outlook 97, Outlook 2000, Outlook 2002 (XP) and Outlook 2003 – (the original C code work fine only with the Exchange client).

Details
(according original Microsoft Readme.txt file)

Peer-to-Peer
The sample peer-to-peer transport transmits messages as files and uses network file paths as its e-mail addresses. Each user has an inbound message directory and an outbound message directory; the user e-mail address is the network path to the inbound directory. The transport creates an outbound message in each recipient's inbound directory (obtained from the recipient's address).

Not Peer-to-Peer
If peer-to-peer transmission is disabled (this is a configuration option), the transport simply leaves outbound messages in the outbound directory and collects inbound messages from the inbound directory. It does not attempt delivery. This mode can be used as the first of two stages, where the second stage moves messages to and from the network.

Addressing
In peer mode, the network path of the user's inbound directory is the e-mail address. Network paths are normally Universal Naming Convention (UNC) paths, but an MS-DOS drive and directory path can also be used.

Message in TNEF
A small set of message properties, including recipients, subject, and message text, are encoded as text for transmission. Other message properties are encapsulated in a binary file in the Transport Neutral Encapsulation Format (TNEF), using functions supplied in TNEF.DLL. This division approximates the division of properties that real transports must often make, where those properties understood by non-MAPI clients must be encoded in a transport-specific format and the remainder can be left to the TNEF.

Interface Lifetime and Cross-Referencing
Interfaces created by the transport in response to service provider interface (SPI) calls, including status interfaces, are hooked to the transport logon object and invalidated when MAPI logs off the transport. The provider INIT object is an exception, as you might expect.

Address Type and UID
The transport handles a single e-mail address type, which is configurable. It does not handle any UIDs, that is, it does not call SetProviderUID.

Per-recipient and per-message Option Support

The transport supports deferred delivery of messages on a per-recipient basis, as well as on a per-message basis.

Supported Features
Basic features. The sample transport supports sending, receiving, and polling for new messages.
Configuration. Interactive and programmatic configuration of 14 parameters is supported.
Status interface. The sample transport supports all methods of the IMAPIStatus interface, except property setting.

Multithread safety. MAPI carefully limits the exposure of transports to access by multiple threads of execution on Win32 platforms. The sample transport protects itself against concurrency problems in the remaining cases where they might arise (in the status interface, for instance).

Cross-platform support. The sample transport generates executable files for Windows 95, Windows 98, Windows NT 3.5, Windows NT 4, Windows 2000, Windows XP and later from a single set of source files.

Event logging. The sample transport supports event logging to a text file. The file is automatically limited to a specified size. All transport sessions use the same file.

Unsupported Features
Asynchronous detection of incoming messages. The transport design does not lend itself to asynchronous detection because the file system does not notify the transport when new messages arrive.

Address Format
This transport supports a single address type whose name is configurable. MSPEER is commonly chosen; this is the type supported by the sample address book. When creating new one-off entries in an address book (i.e. the Personal Address Book), this is the value for the Address Type field. Email addresses for this transport look like DOS file paths. They can be either UNC paths, or ordinary fully qualified paths.

Configuration
The sample transport has a three-page property sheet interface for interactive configuration, which is accessible through service provider logon, through the ServiceEntry call, and through the IMAPIStatus.SettingsDialog method. The configurable parameters appear following. The sample transport also defines a property tag for each parameter so that parameters may be set programmatically through ServiceEntry calls.

Download DEMO

DELPHI Sample Message Store

This project, for shame or pride, took us more than year and a half (with some brakes).
It is based of old Microsoft Example for building a Message Store. Original comments are saved.
The message store is based on the file system. Each folder is a directory and each message is a file. Additional files hold properties of folders and of the message store itself.

The project named DSEMPMS32.dpr contains about 63 000 lines of code. It was very hard to make our Message Store working with all the Outlook versions, starting from Exchange for WinNT4 to the last one (Outlook 2003) with all possible service packs. Notice that for each Outlook version, Microsoft has separate Message Store Provider for PST - MSPST32.DLL

Some of the things, that make possible for DSEMPMS32 to work with the other Outlook versions.
Even it doesn't support Extender Searches, we "cheated" Outlook 2003. Of course, these have side effects, for example, you won't receive notifications, when there is an event in the Calendar.

Ability to create "contacts. The original code doesn't support this. Notice that the "contacts in the realization of this Message Store, doesn’t allow to be used as e-mail recipients in the Address Book, despite, they are shown there.

- Ability to have fully functional Calendar, with records and events.
- To make Tasks functional
- To create Notes.
- Support of Named Properties
- Support of Associated folders and messages - with their help you can create different Custom Views of the folders.
- Etc.

Despite it doesn’t support all possible Outlook extras, this DELPHI Sample Message Store can serve as an excellent instrument, that you can explore how Outlook communicates with Message Store, do extend it with additional functionality, and to create your own message store.

DELPHI Sample Message was started with Delphi 5, developed with Delphi 6, and in the moment the source code is fully compatible with Delphi 5/6/7/2005 win32. Where it was possible were used try..finally..end, TCriticalSection were used to insure Multithread safety.

Download DEMO

Love us? Hate us? Questions or comments?
If you have any questions, concerns, compliments, or suggestions about these articles - write us

Can we license the source code (Delphi 6/Delphi 2007) of these providers?
The answer is YES.