ID Number: Q83454
3.00 3.10
WINDOWS
Summary:
An object linking and embedding (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.
Additional reference words: 3.00 3.10