README.TXT

Sample Transport 
 
 
The peer.xp sample is a transport service provider (SMPXP.DLL). 
 
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 3.X, Windows 95, and Windows NT 3.5 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: 
 
    \\server-name\share-name\directory-name\...drive-letter:directory-name\... 
 
Note: When typing one-off addresses in the Exchange client, you must double the 
backslashes, like this: 
 
    [MSPEER:\\\\server-name\\share-name\\directory\\...] 
 
This is because the client treats the backslash as an escape character. 
 
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; see the SMPXP.H header file. 
 
General Page 
------------ 
 
Log Events. If this check box is selected, the transport logs events to the 
log file specified on the Logging page. Otherwise, logging is disabled. 
 
Peer to Peer Enabled. If this check box is selected, the transport attempts 
to deliver outbound messages to the directory specified by the e-mail address. 
Otherwise, outbound messages are simply placed in the user's own outbound 
directory. 
 
Logon UI Always. If this check box is selected, the transport always brings 
up this dialog box the first time you log on. If Save Dialog Settings is also 
selected, the dialog box comes up filled with the previously entered 
information. If Logon UI Always is not selected, no dialog box appears at 
logon, and the transport uses saved settings instead. 
 
Save Dialog Settings. If checked, the transport saves the contents of the 
dialog box in your MAPI profile. Otherwise, the dialog box contents are used 
until you log off from MAPI and then discarded. 
 
WGAP Filename. This edit control contains a name which could be used by an 
application to designate resources owned by this user of the peer-to-peer 
transport. No known application uses it. 
 
WGAP Directory. This edit control contains the path to a directory which 
could be used by an application to store files owned by this user of the 
peer-to-peer transport. No known application uses it. 
 
Peer to Peer Page 
----------------- 
 
Display Name. This edit control contains the user's full name. This item 
appears in the From field of any messages sent using the peer-to-peer transport. 
 
E-mail Type. This edit control contains the type component of the user's e-mail 
address. Users who intend to exchange messages with the peer-to-peer transport 
should agree on a common value for this item. MSPEER, which is supported by the 
the sample address book, is a common choice. 
 
E-mail Address. This edit control contains a network path, preferably a UNC 
path, to the user's inbound directory. This item is the return address in 
messages sent from this session. 
 
Inbound Msg Dir. This edit control contains a path, preferably a local path, 
to the user's inbound directory. This item does not appear in messages; the 
transport simply uses it as a location to poll for inbound messages. 
 
Outbound Msg Dir. This edit control contains a path, preferably a local path, 
to the user's outbound directory. 
 
Logging Page 
------------ 
 
Logfile Name. This edit control contains a path to the text file the transport 
uses for event logging. If Log Events is checked on the General page, the 
transport writes a line of text to this file for each event. 
 
Log High Water Mark. This edit control contains the maximum size of the log 
file, in kilobytes. If the log file grows beyond this size, it is truncated. 
 
Log Low Water Mark. This edit control contains the size in kilobytes to which 
the log file is truncated when it grows beyond the high-water mark. 
 
Known Problems 
-------------- 
 
Self-relative UNC paths on Windows for Workgroups. If the user's inbound 
directory is shared from the workstation using Windows for Workgroups and the 
e-mail address is a UNC path, sending messages to oneself from this 
workstation might not work. 
 
Installation 
------------ 
 
To install the sample transport you have to 
 
1. Merge the file smpxp.inf with the mapisvc.inf located in your windows 
   system directory. You can do this using the mergeini utility that comes 
   with the MAPI SDK. The syntax is "mergeini -m smpxp.inf". 
 
2. Copy smpxp(32).dll to the windows system directory. 
 
3. Add the sample transport to any MAPI profile using the Mail and Fax 
   control panel applet.