OLEOBJECTVTBL

typedef struct _OLEOBJECTVTBL { /* oov */

void FAR* (CALLBACK* QueryProtocol) (LPOLEOBJECT, OLE_LPCSTR);

OLESTATUS (CALLBACK* Release)(LPOLEOBJECT);

OLESTATUS (CALLBACK* Show)(LPOLEOBJECT, BOOL);

OLESTATUS (CALLBACK* DoVerb)(LPOLEOBJECT, UINT, BOOL, BOOL);

OLESTATUS (CALLBACK* GetData)(LPOLEOBJECT, OLECLIPFORMAT,

HANDLE FAR*);

OLESTATUS (CALLBACK* SetData)(LPOLEOBJECT, OLECLIPFORMAT, HANDLE);

OLESTATUS (CALLBACK* SetTargetDevice)(LPOLEOBJECT, HGLOBAL);

OLESTATUS (CALLBACK* SetBounds)(LPOLEOBJECT, OLE_CONST RECT FAR*);

OLECLIPFORMAT (CALLBACK* EnumFormats)(LPOLEOBJECT, OLECLIPFORMAT);

OLESTATUS (CALLBACK* SetColorScheme)(LPOLEOBJECT,

OLE_CONST LOGPALETTE FAR*);

/* Server has to implement only the above methods. */

#ifndef SERVERONLY

/* Extra methods required for client. */

OLESTATUS (CALLBACK* Delete)(LPOLEOBJECT);

OLESTATUS (CALLBACK* SetHostNames)(LPOLEOBJECT, OLE_LPCSTR,

OLE_LPCSTR);

OLESTATUS (CALLBACK* SaveToStream)(LPOLEOBJECT, LPOLESTREAM);

OLESTATUS (CALLBACK* Clone)(LPOLEOBJECT, LPOLECLIENT, LHCLIENTDOC,

OLE_LPCSTR, LPOLEOBJECT FAR*);

OLESTATUS (CALLBACK* CopyFromLink)(LPOLEOBJECT, LPOLECLIENT,

LHCLIENTDOC, OLE_LPCSTR,

LPOLEOBJECT FAR*);

OLESTATUS (CALLBACK* Equal)(LPOLEOBJECT, LPOLEOBJECT);

OLESTATUS (CALLBACK* CopyToClipboard)(LPOLEOBJECT);

OLESTATUS (CALLBACK* Draw)(LPOLEOBJECT, HDC, OLE_CONST RECT FAR*,

OLE_CONST RECT FAR*, HDC);

OLESTATUS (CALLBACK* Activate)(LPOLEOBJECT, UINT, BOOL, BOOL,

HWND, OLE_CONST RECT FAR*);

OLESTATUS (CALLBACK* Execute)(LPOLEOBJECT, HGLOBAL, UINT);

OLESTATUS (CALLBACK* Close)(LPOLEOBJECT);

OLESTATUS (CALLBACK* Update)(LPOLEOBJECT);

OLESTATUS (CALLBACK* Reconnect)(LPOLEOBJECT);

OLESTATUS (CALLBACK* ObjectConvert)(LPOLEOBJECT, OLE_LPCSTR,

LPOLECLIENT, LHCLIENTDOC,

OLE_LPCSTR, LPOLEOBJECT FAR*);

OLESTATUS (CALLBACK* GetLinkUpdateOptions)(LPOLEOBJECT, OLEOPT_UPDATE FAR*);

OLESTATUS (CALLBACK* SetLinkUpdateOptions)(LPOLEOBJECT, OLEOPT_UPDATE);

OLESTATUS (CALLBACK* Rename)(LPOLEOBJECT, OLE_LPCSTR);

OLESTATUS (CALLBACK* QueryName)(LPOLEOBJECT, LPSTR, UINT FAR*);

OLESTATUS (CALLBACK* QueryType)(LPOLEOBJECT, LONG FAR*);

OLESTATUS (CALLBACK* QueryBounds)(LPOLEOBJECT, RECT FAR*);

OLESTATUS (CALLBACK* QuerySize)(LPOLEOBJECT, DWORD FAR*);

OLESTATUS (CALLBACK* QueryOpen)(LPOLEOBJECT);

OLESTATUS (CALLBACK* QueryOutOfDate)(LPOLEOBJECT);

OLESTATUS (CALLBACK* QueryReleaseStatus)(LPOLEOBJECT);

OLESTATUS (CALLBACK* QueryReleaseError)(LPOLEOBJECT);

OLE_RELEASE_METHOD (CALLBACK* QueryReleaseMethod)(LPOLEOBJECT);

OLESTATUS (CALLBACK* RequestData)(LPOLEOBJECT, OLECLIPFORMAT);

OLESTATUS (CALLBACK* ObjectLong)(LPOLEOBJECT, UINT, LONG FAR*);

/* This method is internal only */

OLESTATUS (CALLBACK* ChangeData)(LPOLEOBJECT, HANDLE, LPOLECLIENT, BOOL);

#endif /* !SERVERONLY */

} OLEOBJECTVTBL;

The OLEOBJECTVTBL structure points to functions that manipulate an object. A server application creates this structure and an OLEOBJECT structure to give the server library access to an object.

Server applications do not need to implement functions beyond the SetColorScheme function. Object handlers can provide specialized treatment for some or all of the functions in the OLEOBJECTVTBL structure.

The following list of structure members does not document all the functions pointed to by the OLEOBJECTVTBL structure. For information about the functions not documented here, see the documentation for the corresponding OLE API function. For example, for more information about the QueryProtocol member, see the OleQueryProtocol function.

Comments

The following functions in OLEOBJECTVTBL should return OLE_BUSY when appropriate:

Activate

Close

CopyFromLink

Delete

DoVerb

Execute

ObjectConvert

Reconnect

RequestData

SetBounds

SetColorScheme

SetData

SetHostNames

SetLinkUpdateOptions

SetTargetDevice

Show

Update

Release

The Release function causes the server to free the resources associated with the specified OLEOBJECT structure.

Parameters

lpObject

Points to the OLEOBJECT structure to be released.

Return Value

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

Comments

The server application should not destroy data when the library calls the Release function. The library calls the Release function when no clients are connected to the object.

Show

The Show function causes the server to show an object, showing its window and scrolling (if necessary) to make it visible.

Parameters

lpObject

Points to the OLEOBJECT structure to show.

fTakeFocus

Specifies whether the server window gets the focus. This value is TRUE to take the focus or FALSE otherwise.

Return Value

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

Comments

The library calls the Show function when the server application should show the document to the user for editing, or to request the server to scroll the document to bring the object into view.

DoVerb

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

Parameters

lpObject

Points to the object to activate.

iVerb

Specifies the action to take. This meaning of this parameter is determined by the server application.

fShow

Specifies whether to show the server window. This value is TRUE to show the window or FALSE otherwise.

fFocus

Specifies whether the server window gets the focus. This parameter is relevant only if the fShow parameter is TRUE.

Return Value

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

Comments

All servers must support the editing of objects. If a server does not support any verbs except “Edit,” it should edit the object no matter what value is specified by the iVerb parameter.

GetData

The GetData function retrieves data from an object in a specified format. The server application should allocate memory, fill it with the data, and return the data through the lphdata parameter.

Parameters

lpObject

Points to the OLEOBJECT structure from which data is requested.

cfFormat

Specifies the format in which the data is requested.

lphdata

Points to the handle to allocated memory that the server application returns. The library frees the memory when it is no longer needed.

Return Value

The return value is OLE_OK if the function is successful. Otherwise, it is an error value, which can be one of the following:

OLE_ERROR_BLANK
OLE_ERROR_FORMAT
OLE_ERROR_OBJECT
OLE_WARN_DELETE_DATA

The server should return OLE_WARN_DELETE_DATA if the client application will be responsible for the data.

SetData

The SetData function stores data in an object in a specified format. This function is called (with the Native data format) when a client opens an embedded object for editing. This function is also used if the client calls the OleSetData function with some other format.

Parameters

lpObject

Points to the OLEOBJECT structure in which data is stored.

cfFormat

Specifies the format of the data.

hdata

Identifies a place in memory from which the server application should extract the data. The server should delete this handle after it uses the data.

Return Value

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

Comments

The server application is responsible for the memory identified by the hdata parameter. Even if an error occurs, the server must delete this data.

SetTargetDevice

The SetTargetDevice function communicates information about the client's target device for the object. The server can use this information to customize output for the target device.

Parameters

lpObject

Points to the OLEOBJECT structure for which the target device is specified.

hdata

Identifies a memory object containing a StdTargetDevice structure. For a description of this structure, see the OleSetTargetDevice function.

Return Value

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

Comments

The server application is responsible for the memory identified by the hdata parameter. Even if an error occurs, the server must delete this data.

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

See Also

OleSetTargetDevice

ObjectLong

The ObjectLong function allows the calling application to store data with an object. This function is typically used by object handlers.

Parameters

lpObject

Points to the OLEOBJECT structure for which the data is stored.

wFlags

Specifies the method used for setting and retrieving data. It can be one or more of the following values:

If the calling application specifies OF_SET and OF_GET, the function returns a pointer to the previous data and overwrites the data pointed to by the lpLong parameter with the data specified by the calling application.

lpLong

Points to data being written or read.

Return Value

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