![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tn008.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [WindowsNT SDKs] / mstools / mfc / doc|
Return to tn008.txt CVS log | Up to [WindowsNT SDKs] / mstools / mfc / doc |
1.1 root 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: =============================================================================
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.