home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / msdn_vcb / samples / vc98 / sdk / dbmsg / mapi / peer.xp / readme.txt < prev    next >
Encoding:
Text File  |  1996-04-06  |  8.5 KB  |  209 lines
  1. Sample Transport
  2.  
  3.  
  4. The peer.xp sample is a transport service provider (SMPXP.DLL).
  5.  
  6. Peer-to-Peer
  7. ------------
  8.  
  9. The sample peer-to-peer transport transmits messages as files and uses
  10. network file paths as its e-mail addresses. Each user has an inbound message
  11. directory and an outbound message directory; the user e-mail address is the
  12. network path to the inbound directory. The transport creates an outbound
  13. message in each recipient's inbound directory (obtained from the recipient's
  14. address).
  15.  
  16. Not Peer-to-Peer
  17. ----------------
  18.  
  19. If peer-to-peer transmission is disabled (this is a configuration option), the
  20. transport simply leaves outbound messages in the outbound directory and
  21. collects inbound messages from the inbound directory. It does not attempt
  22. delivery. This mode can be used as the first of two stages, where the second
  23. stage moves messages to and from the network.
  24.  
  25. Addressing
  26. ----------
  27.  
  28. In peer mode, the network path of the user's inbound directory is the e-mail
  29. address. Network paths are normally Universal Naming Convention (UNC) paths,
  30. but an MS-DOS drive and directory path can also be used.
  31.  
  32. Message in TNEF
  33. ---------------
  34.  
  35. A small set of message properties, including recipients, subject, and message
  36. text, are encoded as text for transmission. Other message properties are
  37. encapsulated in a binary file in the Transport Neutral Encapsulation Format
  38. (TNEF), using functions supplied in TNEF.DLL. This division approximates
  39. the division of properties that real transports must often make, where those
  40. properties understood by non-MAPI clients must be encoded in a transport-
  41. specific format and the remainder can be left to the TNEF.
  42.  
  43. Interface Lifetime and Cross-Referencing
  44. ----------------------------------------
  45.  
  46. Interfaces created by the transport in response to service provider interface
  47. (SPI) calls, including status interfaces, are hooked to the transport logon
  48. object and invalidated when MAPI logs off the transport. The provider INIT
  49. object is an exception, as you might expect.
  50.  
  51. Address Type and UID
  52. --------------------
  53.  
  54. The transport handles a single e-mail address type, which is configurable.
  55. It does not handle any UIDs, that is, it does not call SetProviderUID.
  56.  
  57. Per-recipient and per-message Option Support
  58. --------------------------------------------
  59.  
  60. The transport supports deferred delivery of messages on a per-recipient
  61. basis, as well as on a per-message basis.
  62.  
  63. Supported Features
  64. ------------------
  65.  
  66. Basic features. The sample transport supports sending, receiving, and polling
  67. for new messages.
  68.  
  69. Configuration. Interactive and programmatic configuration of 14 parameters
  70. is supported.
  71.  
  72. Status interface. The sample transport supports all methods of the IMAPIStatus
  73. interface, except property setting.
  74.  
  75. Multithread safety. MAPI carefully limits the exposure of transports to access
  76. by multiple threads of execution on Win32 platforms. The sample transport
  77. protects itself against concurrency problems in the remaining cases where they
  78. might arise (in the status interface, for instance).
  79.  
  80. Cross-platform support. The sample transport generates executable files for
  81. Windows 3.X, Windows 95, and Windows NT 3.5 and later from a single set of
  82. source files.
  83.  
  84. Event logging. The sample transport supports event logging to a text file.
  85. The file is automatically limited to a specified size. All transport sessions
  86. use the same file.
  87.  
  88. Unsupported Features
  89. --------------------
  90.  
  91. Asynchronous detection of incoming messages. The transport design does not
  92. lend itself to asynchronous detection because the file system does not notify
  93. the transport when new messages arrive.
  94.  
  95. Address Format
  96. --------------
  97.  
  98. This transport supports a single address type whose name is configurable.
  99. MSPEER is commonly chosen; this is the type supported by the sample address
  100. book. When creating new one-off entries in an address book (i.e. the Personal
  101. Address Book), this is the value for the Address Type field. Email addresses
  102. for this transport look like DOS file paths. They can be either UNC paths,
  103. or ordinary fully qualified paths:
  104.  
  105.     \\server-name\share-name\directory-name\...drive-letter:directory-name\...
  106.  
  107. Note: When typing one-off addresses in the Exchange client, you must double the
  108. backslashes, like this:
  109.  
  110.     [MSPEER:\\\\server-name\\share-name\\directory\\...]
  111.  
  112. This is because the client treats the backslash as an escape character.
  113.  
  114. Configuration
  115. -------------
  116.  
  117. The sample transport has a three-page property sheet interface for interactive
  118. configuration, which is accessible through service provider logon, through
  119. the ServiceEntry call, and through the IMAPIStatus::SettingsDialog method.
  120. The configurable parameters appear following. The sample transport also
  121. defines a property tag for each parameter so that parameters may be set
  122. programmatically through ServiceEntry calls; see the SMPXP.H header file.
  123.  
  124. General Page
  125. ------------
  126.  
  127. Log Events. If this check box is selected, the transport logs events to the
  128. log file specified on the Logging page. Otherwise, logging is disabled.
  129.  
  130. Peer to Peer Enabled. If this check box is selected, the transport attempts
  131. to deliver outbound messages to the directory specified by the e-mail address.
  132. Otherwise, outbound messages are simply placed in the user's own outbound
  133. directory.
  134.  
  135. Logon UI Always. If this check box is selected, the transport always brings
  136. up this dialog box the first time you log on. If Save Dialog Settings is also
  137. selected, the dialog box comes up filled with the previously entered
  138. information. If Logon UI Always is not selected, no dialog box appears at
  139. logon, and the transport uses saved settings instead.
  140.  
  141. Save Dialog Settings. If checked, the transport saves the contents of the
  142. dialog box in your MAPI profile. Otherwise, the dialog box contents are used
  143. until you log off from MAPI and then discarded.
  144.  
  145. WGAP Filename. This edit control contains a name which could be used by an
  146. application to designate resources owned by this user of the peer-to-peer
  147. transport. No known application uses it.
  148.  
  149. WGAP Directory. This edit control contains the path to a directory which
  150. could be used by an application to store files owned by this user of the
  151. peer-to-peer transport. No known application uses it.
  152.  
  153. Peer to Peer Page
  154. -----------------
  155.  
  156. Display Name. This edit control contains the user's full name. This item
  157. appears in the From field of any messages sent using the peer-to-peer transport.
  158.  
  159. E-mail Type. This edit control contains the type component of the user's e-mail
  160. address. Users who intend to exchange messages with the peer-to-peer transport
  161. should agree on a common value for this item. MSPEER, which is supported by the
  162. the sample address book, is a common choice.
  163.  
  164. E-mail Address. This edit control contains a network path, preferably a UNC
  165. path, to the user's inbound directory. This item is the return address in
  166. messages sent from this session.
  167.  
  168. Inbound Msg Dir. This edit control contains a path, preferably a local path,
  169. to the user's inbound directory. This item does not appear in messages; the
  170. transport simply uses it as a location to poll for inbound messages.
  171.  
  172. Outbound Msg Dir. This edit control contains a path, preferably a local path,
  173. to the user's outbound directory.
  174.  
  175. Logging Page
  176. ------------
  177.  
  178. Logfile Name. This edit control contains a path to the text file the transport
  179. uses for event logging. If Log Events is checked on the General page, the
  180. transport writes a line of text to this file for each event.
  181.  
  182. Log High Water Mark. This edit control contains the maximum size of the log
  183. file, in kilobytes. If the log file grows beyond this size, it is truncated.
  184.  
  185. Log Low Water Mark. This edit control contains the size in kilobytes to which
  186. the log file is truncated when it grows beyond the high-water mark.
  187.  
  188. Known Problems
  189. --------------
  190.  
  191. Self-relative UNC paths on Windows for Workgroups. If the user's inbound
  192. directory is shared from the workstation using Windows for Workgroups and the
  193. e-mail address is a UNC path, sending messages to oneself from this
  194. workstation might not work.
  195.  
  196. Installation
  197. ------------
  198.  
  199. To install the sample transport you have to
  200.  
  201. 1. Merge the file smpxp.inf with the mapisvc.inf located in your windows
  202.    system directory. You can do this using the mergeini utility that comes
  203.    with the MAPI SDK. The syntax is "mergeini -m smpxp.inf".
  204.  
  205. 2. Copy smpxp(32).dll to the windows system directory.
  206.  
  207. 3. Add the sample transport to any MAPI profile using the Mail and Fax
  208.    control panel applet.
  209.