home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c031 / 11.ddi / MFC / DOC / TN008.TX$ / tn008
Encoding:
Text File  |  1992-03-16  |  16.9 KB  |  391 lines
  1. Microsoft Foundation Classes                           Microsoft Corporation
  2. Technical Notes 
  3.  
  4. #8 : General OLE Overview
  5.  
  6. This note gives a general overview of OLE, and the OLE support provided
  7. by the MFC library.
  8.  
  9. The first section is an extract from the OLE API documentation.
  10. The second section describes how the MFC OLE classes provide an
  11. interface to the system level OLE libraries.
  12.  
  13. =============================================================================
  14. General OLE Overview
  15. ====================
  16.  
  17. Compound Documents 
  18. ------------------
  19.  
  20. An application that uses OLE can cooperate with other OLE applications to
  21. produce a document containing different kinds of data, all of which can be
  22. easily manipulated by the user. The user editing such a document is able to
  23. improve the document by using the best features of many different
  24. applications. An application that implements OLE allows its users
  25. to move away from an application-centered view of computing and toward a
  26. document-centered view.
  27.  
  28. A document that supports OLE objects can contain many kinds of
  29. data in many different formats; such a document is called a compound
  30. document. A compound document uses the facilities of different OLE
  31. applications to manipulate the different kinds of data it displays. Any kind
  32. of data format can be incorporated into a compound document; with little or
  33. no extra code.  The user working with a compound document does not need
  34. to know which data formats are compatible with one another or how to find
  35. and start any applications that created the data. Whenever a user chooses to
  36. work with part of a compound document, the application responsible for that
  37. part of the document starts automatically.
  38.  
  39. Linked and Embedded Objects
  40. ---------------------------
  41.  
  42. An object is any data that can be presented in a compound document and
  43. manipulated by a user. Anything from a single cell in a spreadsheet to an
  44. entire document can be an object. When an object is incorporated into a
  45. document, it maintains an association with the application that produced it.
  46.  
  47. For example, if a range of spreadsheet cells were an embedded object in a
  48. text file, all the data associated with the cells would be saved as part of
  49. the text file, including any necessary formulas.
  50. The name of the server for the spreadsheet cells would be saved along with
  51. this data. The user could select this embedded object while working with the
  52. text file, and the spreadsheet application would be started automatically
  53. for editing those cells.
  54. If the range of cells were a linked object instead of an embedded object,
  55. the data would be stored in some other file and only a link to the data
  56. would be saved with the text file. The presentation of the data and the
  57. behavior of the cells would be the same as for an embedded object.
  58.  
  59. Verbs
  60. -----
  61.  
  62. The types of actions a user can perform on an object are called verbs. Two
  63. typical verbs for an object are 'Play' and 'Edit'.
  64.  
  65. The nature of an object determines its behavior when a user works with it.
  66. The most typical use for some objects, such as voice annotations and
  67. animated scripts, is to play them. For example, a user could play an
  68. animated script by double clicking it. In this case, 'Play' is the primary
  69. verb for the object.
  70.  
  71. For other objects, the most typical use is to edit them. In the case of text
  72. produced by a word processor, for example, the primary verb could be 'Edit'.
  73.  
  74. The client application typically specifies the primary verb when the user
  75. double-clicks an object. However, the server application determines the
  76. meaning of that verb. A user can invoke an object's subsidiary verbs by
  77. using the class name Object menu item or the Links dialog box.
  78.  
  79. Many objects support only one verb - for example, an object created by a
  80. text editor might support only 'Edit'. If an object supports only one verb,
  81. that verb is used no matter what the client application specifies.
  82.  
  83. Benefits of Object Linking and Embedding
  84. ----------------------------------------
  85.  
  86. OLE offers the following benefits:
  87.  
  88.   An application can specialize in performing one job very well. For
  89.    example, a drawing application that implements OLE would not necessarily
  90.    need any text-editing tools; a user could put text into the drawing and
  91.    edit that text by using any text editor that supports OLE.
  92.  
  93.   An application automatically extensible for future data formats, because
  94.    the content of an object does not matter to the containing document.
  95.  
  96.   A user can concentrate on the task instead of on any applications
  97.    required to complete the task.
  98.  
  99.   A File can be more compact, because linking to objects allows a file to
  100.    use an object without having to store that object's data.
  101.  
  102.   A document can be printed or transmitted without using the application
  103.    that originally produced the document.
  104.  
  105.   Linked objects in a file can be updated dynamically.
  106.  
  107. -----------------------------------------------------------------------------
  108. Data Transfer in OLE
  109. ---------------------
  110.  
  111. This section gives a brief overview of how applications share information
  112. under OLE.
  113.  
  114. Client Applications
  115. -------------------
  116.  
  117. An OLE client application can accept, display, and store OLE objects. The
  118. objects themselves can contain any kind of data. A client application
  119. typically identifies an object with a distinctive border or other visual
  120. cue.
  121.  
  122. Server Applications
  123. -------------------
  124.  
  125. An OLE server is any application that can edit or otherwise manipulate an
  126. object in response to a request from a client application.
  127. When the user double-clicks an object in a client application, the
  128. server associated with that object starts and the user works with the object
  129. inside the server application. When the server starts, its window is
  130. typically sized so that only the object is visible. If the user
  131. double-clicks a linked object, the entire linked file is loaded, and the
  132. linked portion of the file is selected. For embedded objects, the user
  133. chooses the Update command from the File menu to save changes to the object
  134. and chooses Exit when finished.
  135.  
  136. Many applications are capable of acting as both clients and servers for
  137. OLE objects.
  138.  
  139. Clipboard Conventions
  140. ---------------------
  141.  
  142. When first embedding or linking an object, OLE client and server
  143. applications typically exchange data by using the clipboard. When a server
  144. application puts an object on the clipboard, it represents the object with
  145. data formats, such as Native data, OwnerLink data, ObjectLink data, and a
  146. presentation format. The order in which these formats are put on the
  147. clipboard is very important, because the order determines the type of
  148. object. For example, if the first format is Native and the second is
  149. OwnerLink, client applications can use the data to create an embedded
  150. object. If the first format is ObjectLink, however, the data describes a
  151. linked object.
  152.  
  153. Native data completely defines an object for a particular server. The data
  154. can be meaningful only to the server application. The client application
  155. provides storage for Native data, in the case of embedded objects.
  156.  
  157. Presentation formats allow the client library to display the object in a
  158. document. CF_METAFILEPICT, CF_DIB, and CF_BITMAP are typical presentation
  159. formats.
  160.  
  161. MFC OLE supports Native and CF_METAFILEPICT data formats.  Additional
  162. formats can be added.
  163.  
  164. Registration
  165. ------------
  166.  
  167. The system registration database supports OLE by providing a system-wide
  168. source of information about whether server applications support the OLE
  169. protocol, the names of the executable files for these applications,
  170. the verbs for classes of objects, and whether an object-handler library
  171. exists for a given class of object.
  172.  
  173. When a server application is installed, it registers itself as an OLE
  174. server with the system registration database. (This database is
  175. supported by the dynamic-link library SHELL.DLL.) To register itself
  176. as an OLE server, a setup program, or the AfxOleRegisterServerName()
  177. function records in the database information detailing what OLE
  178. protocols are supported.
  179.  
  180. For example, the MFC sample ole server MINSVR in
  181. \C700\MFC\SAMPLES\MINSVR can be registered just by running the
  182. application in a standalone mode.  Standalone means running the
  183. application from the main menu, file manager, or by clicking an icon.
  184.  
  185. If the location of the server changes, then just re-run the server
  186. application to change the database information.  However, if you are
  187. currently running a client program (i.e. TestClnt, OClient, Word For
  188. Windows, etc.) while re-registering the server, the client must be
  189. shut down and restarted to recieve the updated location.
  190.  
  191. When a client activates a linked or embedded object, the client library
  192. finds the command line for the server in the database, appends the
  193. "/Embedding" or "/Embedding <filename>" command-line option, and uses the new
  194. command line to start the server. (Starting the server with either of these
  195. options differs from the user starting it directly. Either a slash (/) or a
  196. hyphen (-) can precede the word "Embedding.)
  197.  
  198. Registration Database
  199. ---------------------
  200.  
  201. Applications typically add key/value pairs to the registration database by
  202. using the Microsoft Windows Registration Editor. (For more information about
  203. this application, see Microsoft Windows Programming Tools.) Applications
  204. could also use the registration functions to add this information to the
  205. database.
  206.  
  207. To be available for OLE transactions, a server should register the key/value
  208. pairs as illustrated below: (see TN010.TXT for more details)
  209.  
  210. HKEY_CLASSES_ROOT\.ext = class name
  211. HKEY_CLASSES_ROOT\class name = readable version of class name
  212. HKEY_CLASSES_ROOT\class name\protocol\StdFileEditing\server =
  213.         executable file name
  214. HKEY_CLASSES_ROOT\class name\protocol\StdFileEditing\handler =
  215.         dll name
  216. HKEY_CLASSES_ROOT\class name\protocol\StdFileEditing\verb\0 =
  217.         primary verb
  218. HKEY_CLASSES_ROOT\class name\protocol\StdFileEditing\verb\1 =
  219.         secondary verb
  220.  
  221. For compatibility with earlier applications, the system registration service
  222. also reads and writes registration information in the [embedding] section of
  223. the WIN.INI initialization file.
  224.  
  225. The protocol "StdFileEditing" is currently the only OLE protocol used
  226. for linking and embedding.
  227.  
  228. =============================================================================
  229. =============================================================================
  230. MFC and OLE
  231. ===========
  232.  
  233. Applications use three dynamic-libraries, OLECLI.DLL, OLESVR.DLL, and
  234. SHELL.DLL, to implement object linking and embedding. Object linking and
  235. embedding is supported by OLECLI.DLL and OLESVR.DLL. The system registration
  236. database is supported by SHELL.DLL.
  237.  
  238. The MFC library support for OLE makes some simplifying assumptions to make
  239. the common OLE services easier to implement.
  240.  
  241. For those familiar with the existing C based OLE API, please read the next
  242. section which describes the differences between MFC OLE and the system
  243. OLE interface.
  244.  
  245.  
  246. MFC OLE v.s. OLE API
  247. --------------------
  248. Here are the basic differences between MFC OLE and the system OLE API.
  249.  
  250. Language:
  251.         MFC OLE:        C++
  252.         OLE API:        C
  253.  
  254. Library Interface:
  255.         MFC OLE:        C++ classes
  256.         OLE API:        Handles, and manually built jump tables (_VTBLs)
  257.  
  258. Server requests:
  259.         MFC OLE:        Synchronous
  260.         OLE API:        Mostly synchronous, but may be asynchronous
  261.         (i.e. MFC OLE automatically handles OLE_WAIT_FOR_RELEASE)
  262.  
  263. Special case handling for errors, retry:
  264.         MFC OLE:        Provided by library
  265.         OLE API:        Your program must do it all
  266.  
  267. Return codes:
  268.         MFC OLE:        As with standard MFC/Windows API, return useful 
  269.                           values, with Exceptions thrown if appropriate.
  270.         OLE API:        Return OLESTATUS all the time.
  271.  
  272. User Interface Support:
  273.         MFC OLE:        Support for "Insert New Object" dialog, "Links"
  274.                         dialog and support for the "Object" menu item
  275.                         attached to the "Edit" menu.
  276.         OLE API:        none.
  277.  
  278. Other notes:
  279.     * MFC OLE does not currently support "Object Handlers" (i.e. DLLs that
  280.         are more efficient than launching a server application)
  281.     * MFC OLE assumes there is one OLECLIENT for each OLEOBJECT (this is
  282.         part of the OLE API design, but wasn't reflected in old source
  283.         code examples).
  284.     * Users of MFC OLE do not need to build manual VTBLs or call
  285.         MakeProcInstance as described by the OLE API (the MFC libraries
  286.         do all that low level binding for you).
  287.     * MFC OLE does not currently support the "Paste Special" dialog.
  288.  
  289.     * MFC OLE does not provide C++ interfaces to all of the OLE API
  290.         functions, just the most useful ones.
  291.     * MFC OLE is built on top of the OLE API and DLLs. It is easy to
  292.         call additional OLE APIs or use the underlying OLE API if needed.
  293.     * Since MFC OLE is built on top of the OLE API, the underlying transport
  294.         mechanism is the same as all other OLE Apps (i.e. DDE is still
  295.         the communication standard).  MFC OLE apps work with any other
  296.         OLE apps.
  297.  
  298. -----------------------------------------------------------------------------
  299. MFC OLE Classes
  300. ---------------
  301.  
  302. MFC OLE splits the OLE API functionality into two disjoint sets of classes,
  303. one set for client programs, the other set for server programs.
  304. If a program wants to be both a client and a server, it will use all
  305. the OLE classes.  The interface to all MFC OLE classes are contained
  306. in the one C++ header file "afxole.h" that includes the standard OLE API
  307. C header file "ole.h".
  308.  
  309. Terminology note: MFC OLE uses the term "item" to indicate an OLE object
  310. that supports the "StdFileEditing" protocol (to avoid confusion with
  311. the C++ and MFC term "object").
  312.  
  313. General classes:
  314.     COleException is a general exception class used by both
  315.         Clients and Servers.  See MFC overview and class
  316.         reference documentation for more information on exceptions.
  317.  
  318. The Client classes include:
  319.     COleClientDoc is a client document that manages client items
  320.     COleClientItem is the client-side connection to an embedded or
  321.         linked OLE item.
  322.  
  323. The Server classes include:
  324.     COleServer is a server application that creates and manages server
  325.         documents.
  326.     COleServerDoc is a server document that creates and manages server items
  327.     COleServerItem is the server-side of an embedded or linked OLE item.
  328.  
  329. Notes:
  330.     * All MFC OLE classes start with 'COle'.
  331.     * With the exception of COleException, you must derive your own classes
  332.     from each of these COle classes in order to build a working application.
  333.  
  334. See TN009.TXT for what you must do to build a client app.
  335. See TN010.TXT for what you must do to build a server app.
  336.  
  337. -----------------------------------------------------------------------------
  338.  
  339. A class hierarchy diagram of the MFC OLE classes shows the relationship
  340.     between the library classes any your derived classes:
  341.  
  342.     CObject
  343.        COleClientDoc
  344.            << your client doc >>
  345.        COleClientItem
  346.             << your client item >>
  347.        COleServer
  348.             << your server app >>
  349.        COleServerDoc
  350.             << your server doc >>
  351.        COleServerItem
  352.             << your server item >>
  353.        CException
  354.             COleException
  355.  
  356.  
  357. A more interesting diagram shows the relationships between MFC OLE objects:
  358.  
  359.         CLIENT APPLICATION            SERVER APPLICATION
  360.  
  361.     client application                           COleServer
  362.         \                                        /
  363.         COleClientDoc                         COleServerDoc
  364.            \                                /
  365.             COleClientItem    < ----- > COleServerItem
  366.  
  367.     To recap:
  368.         * a client application can have zero or more COleClientDocs
  369.         * each COleClientDoc can have zero or more COleClientItems
  370.         * a COleServer can have zero or more COleServerDocs
  371.         * each COleServerDoc can have zero or more COleServerItems
  372.  
  373. -----------------------------------------------------------------------------
  374. Notes on using the MFC OLE Classes
  375. ----------------------------------
  376. Important Note: The connection between 'COleClientItem' and
  377. 'COleServerItem' in the above diagram is for illustrative purposes only.
  378. The actual connection is through a DDE link which is established and
  379. managed by the OLE DLLs.  A client application should never directly
  380. call a member function of a OLE Server class (COleServer, COleServerDoc
  381. or COleServerItem).  Similarly a server application should never
  382. directly call a member function of an OLE client class (COleClientDoc
  383. or COleClientItem).
  384.  
  385. Many of the member functions in the MFC OLE classes are 'protected',
  386. and some are even pure virtual.
  387. You are responsible for implementing these overridable callbacks even
  388. though you will rarely if ever call them directly.
  389.  
  390. =============================================================================
  391.