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 / flatfile.ab / readme.txt < prev    next >
Encoding:
Text File  |  1996-07-28  |  6.3 KB  |  146 lines
  1. Sample Address Book
  2.  
  3.  
  4. The FlatFile.AB is a sample address book service provider (SMPAB.DLL) that is
  5. part of the prerelease MAPI SDK.
  6.  
  7. The .SAB File
  8. -------------
  9.  
  10. The sample address book provider is based on a read-only file of fixed-length
  11. records. Each record contains the display name and e-mail address of a
  12. messaging user. This file supplies the contents of a single, read-only
  13. address container, which contains only e-mail users. A separate utility
  14. program, SAB.EXE, converts a text file to an .SAB file. Each line of input
  15. text must be formatted as follows:
  16.  
  17. display name<tab>e-mail address
  18.  
  19. The e-mail address must not contain white space, and the input file must be
  20. sorted on the display name; the conversion utility does not sort.
  21.  
  22. Address Type
  23. ------------
  24.  
  25. The sample address book supports one e-mail address type; it is hard-coded
  26. to MSPEER. If you plan to use the sample address book and sample transport
  27. together, configure the sample transport provider to use MSPEER also.
  28.  
  29. Entry Identifiers
  30. -----------------
  31.  
  32. The sample address book registers one MAPIUID with SetProviderUID(); it is
  33. also hard-coded. The unique part of a messaging user entry identifier is
  34. the e-mail address. Messaging user entry identifiers use the hard-coded UID,
  35. so they are the same across all instances of the sample address book.
  36. The sample address book chooses a UID at random the first time it is
  37. configured for use in its top-level container entry identifier. This enables
  38. multiple instances of the provider, each with its own top-level container,
  39. to coexist in a single profile.
  40.  
  41. The sample address book does not distinguish between short- and long-term
  42. entry identifiers.
  43.  
  44. Table Implementation
  45. --------------------
  46.  
  47. The sample address book largely delegates the implementation of its hierarchy
  48. table to the IMAPITableData interface. For its contents table, the sample
  49. address book implements the IMAPITable interface directly on the .SAB file.
  50. The contents table is a good example of a caching table implementation; it
  51. defers reading records from disk until absolutely necessary and can handle
  52. quite large files with limited memory. The contents table also supports prefix
  53. searching and ambiguous name resolution (ANR). The contents table
  54. implementation closes the .SAB file if the table interface is not accessed
  55. for a while. This makes it possible to update the .SAB file while it is in
  56. use. If the .SAB file changes, the sample address book notices at the next
  57. file access and issues a notification on the contents table so that the user
  58. interface can be updated. It uses the idle task engine to do the closing.
  59.  
  60. Supported Features
  61. ------------------
  62.  
  63. Table restrictions. The sample address book implements the two most commonly
  64. used types of restrictions for an address book: prefix match and ANR. It does
  65. not implement the full MAPI restriction language, and restrictions are
  66. supported only on the display name.
  67.  
  68. Prefix matching enables incremental searching through an address book
  69. container in which the user types the initial characters of a display name.
  70. ANR, on the other hand, matches one or more prefix strings against the entire
  71. container, regardless of first or last name order, and returns all matching
  72. entries; this enables checking of partial names typed into a message.
  73.  
  74. Details. The sample address book implements its own details display table
  75. for messaging users. There are two sets of properties, divided into two pages.
  76. The first page has the standard properties: display name, e-mail address, and
  77. address type.  The second page has an example of almost every control type
  78. implemented in MAPI display tables (the data is hard-coded, not drawn from
  79. the address book). There is a template identifier for messaging user details,
  80. which enables all details to be supported for users copied from the sample
  81. address book to the personal address book. Details are also supported for the
  82. top-level directory, including the ability to change the .SAB file from the
  83. details pane. The directory details view uses a notification to update the
  84. display when the .SAB file is changed.
  85.  
  86. Custom recipients (one-offs). The sample address book implements a one-off
  87. table with a set of properties different from the native details; these
  88. properties combine to form the e-mail address. The template identifier
  89. enables messaging users to be added to the personal address book, or directly
  90. to a message, using a special dialog box; processing is routed through the
  91. sample address book, which has the ability to generate the e-mail address
  92. from the properties entered in the dialog box.
  93.  
  94. Advanced search dialog box. The sample address book implements an advanced
  95. search dialog box, accessible by choosing the Advanced button on the MAPI
  96. addressing dialog box. In reality, the advanced search is only slightly
  97. different from the standard search, which uses an ANR restriction.
  98.  
  99. Status interface. The IMAPIStatus interface is partially supported; its
  100. IMAPIProp methods are delegated to the IMAPIPropData interface.
  101.  
  102. Configuration interfaces. The sample address book supports both interactive
  103. and programmatic configuration.
  104.  
  105. Cross-platform support. The sample address book source code generates
  106. executables for Windows 3.X, Windows 95, and Windows NT 3.5 and later from a
  107. single set of source files.
  108.  
  109. Unsupported Features
  110. --------------------
  111.  
  112. Sorting.
  113.  
  114. Distribution lists.
  115.  
  116. Creating, deleting, and modifying entries.
  117.  
  118. Multi-valued properties.
  119.  
  120. Named properties.
  121.  
  122. Distinguishing first and last name in display names.
  123.  
  124. Configuration
  125. -------------
  126.  
  127. The only configurable property supported by the sample address book is the
  128. path to the .SAB file. The path can be set interactively either through the
  129. service configuration dialog box or at provider logon. It can also be set
  130. programmatically through the ServiceEntry function. For the definitions
  131. needed to set the path programmatically, see the SMPAB.H header file.
  132.  
  133. Installation
  134. ------------
  135.  
  136. To install the sample address book, you have to:
  137.  
  138. 1. Merge the file smpab.inf with mapisvc.inf located in your windows system
  139.    directory. You can do this using the mergeini utility that comes with
  140.    the MAPI SDK. The syntax is "mergeini -m smpab.inf".
  141.  
  142. 2. Copy smpab(32).dll to the windows system directory.
  143.  
  144. 3. Add the sample address book to any MAPI profile using the Mail and Fax
  145.    control panel applet.
  146.