![[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.