7.1.12 OLE Object Callback Functions

The specific callback functions that each member of the OLEOBJECTVTBL data structure points to are described in the following sections. You will need to code these functions to meet the needs of your application.

7.1.12.1 QueryProtocol

LPVOID (CALLBACK *QueryProtocol)(lpObject, lpProtocol)

LPOLEOBJECT lpObject;

OLE_LPCSTR lpProtocol

The QueryProtocol function is called to determine which protocols the server application supports.

There are currently two possible protocols: StdFileEditing and StdExecute. StdFileEditing is the current OLE protocol while StdExecute is for applications that support WM_DDE_EXECUTE messages.

OLE server applications must support StdFileEditing but are not required to support StdExecute protocol.

In response to the QueryProtocol function, the server application should perform the following steps:

1.If the protocol specified in lpProtocol is supported, return a pointer to and OLEOBJECT structure that contains a VTBL appropriate for the specified protocol. In most cases, the server can just return the lpObject parameter passed to the callback function.

2.If the server application does not support the specified protocol, return NULL.

The return value is NULL if the object does not support the requested protocol.

Otherwise, the return value is a VOID pointer to a data structure similar to the OLEOBJECT structure, but the entries in the corresponding VTBL structure depend on the requested protocol.

For the standard protocols, StdFileEditing and StdExecute, the return value is an OLEOBJECT pointer with corresponding VTBL entries. If an object handler supports additional protocols, the entries in the VTBL structure may be different. Since the caller knows the string name to request, the caller must know the definition of the corresponding VTBL entries.

The DLL can return OLE_WAIT_FOR_RELEASE when an application calls this function.

7.1.12.2 Release

OLESTATUS (CALLBACK *Release)(lpObject)

LPOLEOBJECT lpObject;

The Release function causes the server application to free the resources associated with the specified OLEOBJECT structure. This function is called to inform the server application that an object is no longer connected to any client. This callback can be called when a client application calls OleDelete, or when the server application calls OleRevokeServer, OleRevokeObject, or OleRevokeServerDoc. In response, the server application should free the object's resources.

The server application should not destroy data when the DLL calls Release.

The return value is OLE_OK if successful; otherwise, it is an error value.

7.1.12.3 Show

OLESTATUS (CALLBACK *Show)(lpObject, fTakeFocus)

LPOLEOBJECT lpObject;
BOOL fTakeFocus;

The Show function causes the server application to show an object, showing its window and scrolling (if necessary) to make it visible. The DLL calls the Show function when the server application should show the document to the user for editing, or to request the server application to scroll the document to bring the object into view.

In response to a callback to this function, the server application should perform the following steps:

1.If the server application is not already visible, make it visible.

2.If the object's document window is not already visible, make it visible.

3.If the object is not visible within its document window, make it visible. This may require scrolling the object's document window.

4.Select the object, if possible.

5.If fTakeFocus is TRUE, call SetFocus with the main window handle. Also, if the server application's main window or document window is minimized, it should be restored.

The return value is OLE_OK if successful; otherwise, it is an error value.

7.1.12.4 DoVerb

OLESTATUS (CALLBACK *DoVerb)(lpObject, iVerb, fShow, fTakeFocus);

LPOLEOBJECT lpObject;
UINT iVerb;
BOOL fShow;
BOOL fTakeFocus;

The DoVerb function specifies what kind of action the server should take when a user opens an object.

DoVerb is called when the client application has invoked an object's verb (by calling OleActivate). The server defines the meaning of the verbs. This callback associates meaning with each verb index. In response to DoVerb, a server application should perform the requested verb.

The return value is OLE_OK if the function is successful; otherwise, it is an error value.

7.1.12.5 GetData

OLESTATUS (CALLBACK *GetData)(lpObject, cfFormat, lphdata)

LPOLEOBJECT lpObject;
OLECLIPFORMAT cfFormat;
HANDLE FAR* lphdata;

GetData is called when the server DLL requests a specific data format for an object (for example, Native, OwnerLink or CF_METAFILEPICT.) The server application should return a handle to the requested data to the DLL.

GetData should provide the object data based upon the device specified in the SetTargetDevice callback. The server application must maintain target device information so that it can provide the appropriate data. If SetTargetDevice has not been called, then the server may assume a device, usually the display.

In response to a call to GetData, the server should perform the following steps:

1.Allocate a block of memory big enough to hold the requested data format. Use the GMEM_DDESHARE flag when allocating the memory. (The CF_BITMAP data format is an exception. Allocate memory for a bitmap using the CreateBitmap function.)

2.Lock the memory.

3.Fill the memory with the requested data format (cfFormat) for the object pointed to by lpObject.

4.Unlock the memory.

5.Return a handle to the memory via the lphData parameter.

The return value is OLE_OK if the function is successful; otherwise, it coould be one of the following error values:

OLE_ERROR_BLANK

OLE_ERROR_FORMAT

OLE_ERROR_OBJECT

7.1.12.6 SetData

OLESTATUS (CALLBACK *SetData)(lpObject, cfFormat, hdata)

LPOLEOBJECT lpObject;
OLECLIPFORMAT cfFormat;
HANDLE hdata;

The SetData function is called by the server DLL to provide the server application with an object's native data (usually when the user opens an embedded object for editing).

The server DLL obtains the native data for the embedded object from the client applicaton and sends it to the server through this callback. SetData is called before the Show or DoVerb functions. This function is also used if the client application calls OleSetData with some other format.

In response to a call to SetData, the server application should perform the following steps:

1.If the supplied data format (cfFormat) is not appropriate, return OLE_ERROR_FORMAT.

2.Lock the native data (hData) using GlobalLock. If this fails, return OLE_ERROR_MEMORY.

3.Allocate a buffer, lock it, and copy the data from hData into data into the buffer. If this can not be done, return OLE_ERROR_MEMORY.

4.Unlock and free the native data supplied by the server library (hData). If this fails, return OLE_ERROR_MEMORY.

Note Copying the native data to a private buffer is important. When the OLE DLLs send data to your server application, do not modify it. Always copy the data and modify the copy.

The server application is responsible for the memory identified by the hdata parameter. The server must delete this data even if it returns OLE_BUSY or if an error occurs.

The return value is OLE_OK if successful; otherwise, it is an error value.

7.1.12.7 SetTargetDevice

OLESTATUS (CALLBACK *SetTargetDevice)(lpObject, hdata)

LPOLEOBJECT lpObject;
HGLOBAL hdata;

The SetTargetDevice function communicates information about the client application's target device for the object.

The server application can customize output for the target device, such as a video display or printer. SetTargetDevice is called to identify the type device on which the object will be rendered. The server application can use the information provided by SetTargetDevice to optimize the object presentation it supplies to client applications. For example, a server application could return a 24 bit-per-pixel DIB as the presentation for an object displayed on a high resolution color monitor, and a monochrome metafile picture for the same object when displayed on a monochrome dot matrix printer.

After SetTargetDevice is called, subsequent calls to the GetData callback take the specified target device into consideration. This involves getting a DC for the specified device and providing object information based upon that device.

In response to SetTargetDevice, a server should perform the following steps:

1.Lock hdata using GlobalLock.

2.Allocate a buffer, lock it, and copy the target device information (hdata) into the buffer. If this cannot be done, return OLE_ERROR_MEMORY.

3.Unlock hdata using GlobalUnlock.

4.Free hdata using GlobalFree.

The server application is responsible for the memory identified by the hdata parameter. The server application must delete this data even if it returns OLE_BUSY or if an error occurs.

The DLL passes NULL for the hdata parameter to indicate that the rendering is necessary for the screen.

The return value is OLE_OK if successful; otherwise, it is OLE_ERROR_MEMORY.

7.1.12.8 SetBounds

The SetBounds function provides compatibility only. It should return OLE_OK.

7.1.12.9 EnumFormats

OLESTATUS (CALLBACK *EnumFormats)(lpObject, cfFormat)

LPOLEOBJECT lpObject;
OLECLIPFORMAT cfFormat;

The EnumFormats function enumerates the data formats that the object can render.

Passing NULL for cfFormat on the first call returns the first data format. Passing the first format returns the second format, and so on. When no more formats are available, NULL is returned.

The return value is OLE_OK if successful; otherwise, it is an error value.

7.1.12.10 SetColorScheme

OLESTATUS SetColorScheme(lpObject, lpPalette);

LPOLEOBJECT lpObject;

LPLOGPALETTE lpPalette;

The SetColorScheme function specifies the palette to be used when the server application edits the specified object.