#include <ole.h>
typedef struct _OLECLIENTVTBL { /* ocv */
int (CALLBACK* CallBack)(LPOLECLIENT, OLE_NOTIFICATION, LPOLEOBJECT);
} OLECLIENTVTBL;
The OLECLIENTVTBL structure contains a pointer to a callback function for the client application.
The address passed as the CallBack member must be created by using the MakeProcInstance function.
ClientCallback
INT ClientCallback(lpclient, notification, lpobject) | |||
LPOLECLIENT lpclient; | |||
OLE_NOTIFICATION notification; | |||
LPOLEOBJECT lpobject; |
The ClientCallback function must use the Pascal calling convention and must be declared FAR.
lpclient
Points to the client structure associated with the object. The library 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 linked object has changed. (This notification is not sent for embedded objects.) A typical action to take with this notification is either to redraw or to save the object. |
OLE_CLOSED | The object has been closed in its server. 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 by indicating that it is busy. This notification requests the client to determine whether the library 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 finished. The client should not quit until all objects have been released. 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 that operation has ended . |
OLE_RENAMED | The linked object has been renamed in its server. This notification is for information only, because the library automatically updates its link information. |
OLE_SAVED | The linked object has been saved in its server. The client receives this notification when the server calls the OleSavedServerDoc function in response to the user choosing the Update command in the server's File menu. |
When the client receives the OLE_CLOSED notification, it typically stores the condition and returns to the client library, taking action only when the client library 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.
When the notification parameter specifies either OLE_QUERY_PAINT or OLE_QUERY_RETRY, the client should return TRUE if the library 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.
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 an object can be deferred until the user requests the update, if the client provides that functionality. The client may call the library from a notification callback function (the library is reentrant). The client should not attempt an asynchronous operation while certain other operations are in progress (for example, opening or deleting an object). The client also should not enter a message-dispatch loop inside the callback function. When the client application calls a function that would cause an asynchronous operation, the client library 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 attempts to invoke a conflicting operation while the previous one is in progress. The client can determine if an asynchronous operation is in progress by calling OleQueryReleaseStatus, which returns OLE_BUSY if the operation has not yet completed.