The callback function pointed to by the OLECLIENTVTBL structure is described in the following section. You will need to code this function to meet the needs of your application.
INT (CALLBACK* CallBack)(lpclient, notification, lpobject)
LPOLECLIENT lpclient;
OLE_NOTIFICATION notification;
LPOLEOBJECT lpobject;
| Parameter | Description |
| lpclient | Points to the client structure associated with the object. The client DLL retrieves this pointer from its object structure when a notification occurs, uses it to locate the callback function, and passes the pointer to the client structure for the client application's use. |
| notification | Specifies the reason for the notification. This parameter can be one of the following values: |
| Value | Meaning | |
| OLE_CHANGED | The object has changed within the server application. Received whenever a linked object, opened for editing from the client application, is changed in the server application. May be received when an embedded object is changed and the server applications is closed with document changes saved. Typical actions to take with this notification are to redraw or save the object. | |
| OLE_CLOSED | The object has been closed in its server application. When the client receives this notification, it should not call any function that causes an asynchronous operation until it regains control of program execution. | |
| OLE_QUERY_PAINT | A lengthy drawing operation is occurring. This notification allows the drawing to be interrupted. | |
| OLE_QUERY_RETRY | The server has responded to a request indicating that it is busy. This notification requests the client to determine whether the DLL should continue to make the request. If the callback function returns FALSE, the transaction with the server is discontinued. | |
| OLE_RELEASE | The object has been released because an asynchronous operation has completed. The client application can call the OleQueryReleaseError function to determine whether the operation succeeded. It can also call the OleQueryReleaseMethod function, if necessary, to verify that the operation has terminated. | |
| OLE_RENAMED | The linked object has been renamed in its server application. This notification is for information only, because the DLL automatically updates its link information. | |
| OLE_SAVED | The object has been saved in its server application. The client receives this notification when the server calls the OleSavedServerDoc function in response to the user choosing "Update" in the server's File menu. Typical actions to take with this notification are to redraw or save the object. |
| When the client receives the OLE_CLOSED notification, it typically stores the condition and returns control to the client DLL. the application takes action only when the client DLL returns control of program execution to the client application. If the client application must take action before regaining control, it should not call any functions that could result in an asynchronous operation. | |
| lpobject | Points to the object that caused the notification to be sent. Applications that use the same client structure for more than one object use the lpobject parameter to distinguish between notifications. |
The client application should act on these notifications at the next appropriate time; for example, as part of the main event loop or when closing the object. The updating of objects can be deferred until the user requests the update, if the client application provides that functionality. The client application may call the DLL from a notification callback function (the DLL is reentrant).
The client application should not attempt an asynchronous operation while another operations is in progress (for example, opening or deleting an object). The client application should also not enter a message-dispatch loop inside the callback function (calling MessageBox will cause this to happen).
When the client application calls a function that would cause an asynchronous operation, the client DLL returns OLE_WAIT_FOR_RELEASE when the function is called, notifies the application when the operation completes by using OLE_RELEASE, and returns OLE_BUSY if the client application attempts to invoke a conflicting operation while the previous one is in progress. The client application can determine if an asynchronous operation is in progress by calling OleQueryReleaseStatus, which returns OLE_BUSY if the operation has not yet completed. For more information on asynchronous operations, see Chapter 5, "Implementing OLE into Client Applications."
When the notification parameter specifies either OLE_QUERY_PAINT or OLE_QUERY_RETRY, the client should return TRUE if the DLL should continue, or FALSE to terminate the painting operation or discontinue the server transaction. When the notification parameter does not specify either OLE_QUERY_PAINT or OLE_QUERY_RETRY, the return value is ignored.