Meaning of OLE Notifications

• Microsoft OLE version 1.0

SUMMARY

An OLE server application sends the following messages to an OLE client application's callback function: OLE_CHANGED, OLE_CLOSED, OLE_SAVED, and OLE_RENAMED. These messages inform the client that an embedded object was changed, closed, saved to disk, or saved to disk with a new name, respectively.

Although the client application may receive other notification messages, this discussion focuses on the notifications sent by the server and their effects on the client application.

MORE INFORMATION

The server application sends an OLE_CLOSED notification when it closes the server document and updates changes to the client. The OLE_CLOSED notification applies both to embedded objects and to linked objects. This notification might have been better named OLE_CLOSED_AND_SAVED because sending an OLE_CLOSED notification causes the server application's GetData method to be called; doing so obtains the latest data. Therefore, a server application should send an OLE_CLOSED notification only when the user wants to close the document and update any changes. Note that a client application will never receive an OLE_CLOSED notification for linked objects because the OLE Libraries intercept this notification. The client application for an embedded object will always receive the OLE_CLOSED notification.

The client application will receive an OLE_CLOSED notification for an embedded object regardless of whether the server sends the notification to the client application's callback function. The OLE Libraries maintain parallel internal OLECLIENT structures (and parallel notification callback functions), which intercept any notification sent by the server. Therefore, the client and server applications never communicate directly with each other; all interaction proceeds through the OLE libraries. It is interesting to note the differences between the following two scenarios: If the server calls the OleRevokeServerDoc function, the client receives an OLE_CLOSED notification. However, if the server sends an OLE_CLOSED, then calls OleRevokeServerDoc, the client receives two notifications, OLE_CHANGED followed by OLE_CLOSED.

When the user chooses Update from the File menu, an OLE server sends an OLE_SAVED notification when the server updates an object. The server sends this notification by calling the OleSavedServerDoc function. The client application receives an OLE_SAVED notification whenever the server calls OleSavedServerDoc.

A server application sends an OLE_CHANGED notification only for linked objects. However, a client application may receive an OLE_CHANGED notification for an embedded object. The server should send an OLE_CHANGED notification for a link whenever a linked object is modified in the server. In this scenario, the client application will receive the OLE_CHANGED notification.

A server sends an OLE_RENAMED notification when the user renames the document to which the client is linked. The server sends this notification by calling the OleRenameServerDoc function. The OLE_RENAMED notification implies OLE_CHANGED.

The client application's callback function may receive two other notifications: OLE_QUERY_PAINT and OLE_QUERY_RETRY.

The OLE client-side library sends an OLE_QUERY_PAINT notification only if the object drawn through OleDraw uses a metafile for its presentation. When the presentation is a metafile, after the library plays each record of the metafile, it sends an OLE_QUERY_PAINT message. If the metafile contains only one record, the client application does NOT receive an OLE_QUERY_PAINT notification because the image is completely drawn after playing the first record.

Processing the OLE_QUERY_PAINT notification allows the client application to interrupt playing a large metafile. If the client returns FALSE in response to an OLE_QUERY_PAINT notification, the OLE libraries will discontinue playing the metafile. An application will typically return TRUE in response to an OLE_QUERY_PAINT notification to allow painting to continue uninterrupted. If an application must perform processing while a metafile is rendered, it can do so in response to the OLE_QUERY_PAINT notification. Please note that this does NOT imply that the client application can enter a message dispatch loop; doing so is not allowed in a notification callback function.

The OLE client-side library sends an OLE_QUERY_RETRY notification when the server application notifies the OLE server library that the server is busy. If a client application returns TRUE in response to this notification, the OLE libraries will continue the current operation. If the client application returns FALSE, the OLE libraries will cancel the pending operation.

By processing this notification, a client application can inform the user that the server is busy and allow the user to wait or to cancel the operation. Typically, a client application implements a retry limit under which it will cancel an operation after a set number of retry attempts. Because retry limits differ based on the server applications involved, only experimentation will disclose the correct number; however, 10-15 is probably a reasonable starting place.