home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-386-Vol-2of3.iso / a / am-21b.zip / DDE.TX_ < prev    next >
Text File  |  1992-12-06  |  15KB  |  197 lines
  1.  
  2. This file contains information about Address Manager and DDE support.
  3.  
  4.  
  5. /****************************************************************************
  6. *                                                                           *
  7. *                Here is the DDE protocol                                   *
  8. *                                                                           *
  9. *                                                                           *
  10. *  Address Manager currently acts only as a SERVER application for DDE      *
  11. *  conversations.  This means *any* application can ask AM for data,        *
  12. *  such as an address or a phone number.                                    *
  13. *                                                                           *
  14. *  The following protocol is used and must be followed by any application   *
  15. *  wishing to get data from AM:                                             *
  16. *                                                                           *
  17. *  1.  Initiate the conversation with AM                                    *
  18. *                                                                           *
  19. *          AppName         Topic                                            *
  20. *          -------         -----                                            *
  21. *          Address         <name of AM data file>  (ie. mynames.add)        *
  22. *                                                                           *
  23. *  2.  Request data from AM                                                 *
  24. *                                                                           *
  25. *          Using W4W macro lang, this can be done using                     *
  26. *          DDERequest() function.  For example, the following               *
  27. *          request could be made:                                           *
  28. *                                                                           *
  29. *                  DDERequest(ChanNum, "a Smith");                          *
  30. *                                                                           *
  31. *          This would request all names from AM that match "Smith"          *
  32. *                                                                           *
  33. *                                                                           *
  34. *          If you are programming in the SDK, the client app would          *
  35. *          post a WM_DDE_REQUEST message to AM with the appropriate         *
  36. *          parameters passed in wParam and lParam.  The HIWORD(lParam)      *
  37. *          in this case would be CF_TEXT.                                   *
  38. *                                                                           *
  39. *                                                                           *
  40. *       The types of data that can be requested are outlined below.  The    *
  41. *       syntax is as follows:                                               *
  42. *                                                                           *
  43. *          <> indicate a required field, and the text between <> will       *
  44. *             describe what goes there.                                     *
  45. *                                                                           *
  46. *          {} indicate an optional field                                    *
  47. *                                                                           *
  48. *          [] indicate a logical entity.  See the protocol for "complete    *
  49. *             control" below to see what I mean.                            *
  50. *                                                                           *
  51. *                                                                           *
  52. * 1===> The protocol for addresses is:                                      *
  53. *                                                                           *
  54. *          a <exact name, as entered in AM, you want an address for>        *
  55. *                                                                           *
  56. *       NOTE:  THIS PROTOCOL IS OUTDATED AND IS SUPERCEDED BY THE           *
  57. *              "Complete Control" PROTOCOL BELOW.  THIS IS PROVIDED         *
  58. *              FOR BACKWARD COMPATIBILITY ONLY.                             *
  59. *                                                                           *
  60. * 2===> The protocol for phone numbers is:                                  *
  61. *                                                                           *
  62. *          p h{wf} <exact name, as entered in AM, you want phone #'s for>   *
  63. *                                                                           *
  64. *       Here, h is for "home" phone, the w for "work" and the f for "fax"   *
  65. *       You may request any or all of the phone numbers for a given person. *
  66. *                                                                           *
  67. *       NOTE:  THIS PROTOCOL IS OUTDATED AND IS SUPERCEDED BY THE           *
  68. *              "Complete Control" PROTOCOL BELOW.  THIS IS PROVIDED         *
  69. *              FOR BACKWARD COMPATIBILITY ONLY.                             *
  70. *                                                                           *
  71. * 3===> The protocol for retrieving the number of names in a specified      *
  72. *       list is:                                                            *
  73. *                                                                           *
  74. *          c  [List]                                                        *
  75. *                                                                           *
  76. *       where the call looks like DDERequest(ChanNum, "c [Current List]")   *
  77. *       The [List] field is REQUIRED, but can be set to [Current List] to   *
  78. *       return a count for the current list AM is showing.                  *
  79. *       This does NOT return the total entries in the file, just the        *
  80. *       entries for the specified list.  To get a total count in the file,  *
  81. *       specify [All Addresses] as the List                                 *
  82. *                                                                           *
  83. *                                                                           *
  84. * 4===> The protocol for retreiving the name of the current list being      *
  85. *       shown in Address Manager is:                                        *
  86. *                                                                           *
  87. *                                                                           *
  88. *          l                                                                *
  89. *                                                                           *
  90. *       where the call looks like DDERequest(ChanNum, "l").  So if you are  *
  91. *       currently viewing the "Friends" list in Address Manager, this       *
  92. *       call will return "Friends"                                          *
  93. *                                                                           *
  94. * 5===> The "COMPLETE CONTROL" Protocol                                     *
  95. *                                                                           *
  96. *                                                                           *
  97. *       The protocol for complete control of what you want and where you    *
  98. *       want it from is:                                                    *
  99. *                                                                           *
  100. *          uf <[List]> {[Name]} <Format String>                             *
  101. *                                                                           *
  102. *       where:                                                              *
  103. *                                                                           *
  104. *          List is: "All Addresses" or a user defined list.  This field     *
  105. *                   is REQUIRED.  To retreive data from the current list    *
  106. *                   specify [Current List] in this field                    *
  107. *                                                                           *
  108. *          Name is: Exact name, as entered in Address Manager.  This field  *
  109. *                   is OPTIONAL, and if left out will return the first      *
  110. *                   name for the list specified in [List]                   *
  111. *                                                                           *
  112. *          Format String is: Definition of what data to return, for the     *
  113. *                            requested name.  This field is REQUIRED        *
  114. *                                                                           *
  115. *                            The format string can be made up of one or     *
  116. *                            more of the following:                         *
  117. *                                                                           *
  118. *                            String                      Returns            *
  119. *                            ------                      -------            *
  120. *                            %NAME                       Sal. + Full Name   *
  121. *                            %SAL                        Salutation         *
  122. *                            %FN                         First Name         *
  123. *                            %MN                         Middle Name        *
  124. *                            %LN                         Last Name          *
  125. *                            %CO                         Company            *
  126. *                            %A1                         Address Line 1     *
  127. *                            %A2                         Address Line 2     *
  128. *                            %A3                         Address Line 3     *
  129. *                            %CITY                       City               *
  130. *                            %ST                         State              *
  131. *                            %ZIP                        Zip                *
  132. *                            %HP                         Home Phone         *
  133. *                            %WP                         Work Phone         *
  134. *                            %WE                         Work Extension     *
  135. *                            %FP                         Fax Phone          *
  136. *                            %HISB                       His Birthday       *
  137. *                            %HERB                       Her Birthday       *
  138. *                            %AN                         Anniversary        *
  139. *                            %CMT                        Comments           *
  140. *                            %CR                         Inserts New Line   *
  141. *                            %TAB                        Inserts TAB char   *
  142. *                            %<any text up to 50 chars>  Inserts exact text *
  143. *                                                                           *
  144. *          A typical format string might look like this:                    *
  145. *                                                                           *
  146. *                                                                           *
  147. *            %FN% %MN% %LN%CR%A1%CR%A2%CR%A3%CR%CITY% %ST%, %ZIP            *
  148. *                                                                           *
  149. *                                                                           *
  150. *          Example of how to use this protocol:                             *
  151. *                                                                           *
  152. *                                                                           *
  153. *            uf [Friends] %FN% %MN% %LN%CR                                  *
  154. *                                                                           *
  155. *          This example will retrieve information from the first entry in   *
  156. *          the Friends list.  The First Name, Middle Name and Last Name     *
  157. *          followed by a carriage return/line feed will be returned.  Note  *
  158. *          how a space char has been inserted between each names, using     *
  159. *          the "% " format string.                                          *
  160. *                                                                           *
  161. *                                                                           *
  162. *          IMPORTANT INFORMATION                                            *
  163. *          =====================                                            *
  164. *                                                                           *
  165. *          *  The total length of the DDE string sent to Address Manager    *
  166. *             can not exceed 512 bytes.                                     *
  167. *                                                                           *
  168. *          *  The total length of an idividual part of the format string    *
  169. *             can not exceed 50 bytes.  See the last entry in the table     *
  170. *             above to see what I'm talking about.                          *
  171. *                                                                           *
  172. *          *  Note that this protocol will give you either a specific name  *
  173. *             from a specific list, or the first name from a specific list. *
  174. *             Once you have used this protocol, you can use the next        *
  175. *             protocol (described below) to get the next name from the      *
  176. *             same list.                                                    *
  177. *                                                                           *
  178. *                                                                           *
  179. * 6===> The "COMPLETE CONTROL" Protocol's partner                           *
  180. *                                                                           *
  181. *      The protocl to retrieve the next name from a specified list (as      *
  182. *      specified in the previous protocol) is:                              *
  183. *                                                                           *
  184. *          un                                                               *
  185. *                                                                           *
  186. *      This protocol can only be used AFTER a call has been made using the  *
  187. *      previously mentioned protocol.  Essentially, you use the "uf"        *
  188. *      protocol to get the first name, specify the list you want to get     *
  189. *      information from, specify *what* information you want, and then      *
  190. *      you use this protocol to get information for the next name in the    *
  191. *      list.                                                                *
  192. *                                                                           *
  193. *  3.  Terminate the DDE conversation.                                      *
  194. *                                                                           *
  195. *                                                                           *
  196. ****************************************************************************/
  197.