OLESERVERDOCVTBL

3.1

#include <ole.h>

typedef struct _OLESERVERDOCVTBL {   /* odv */
    OLESTATUS (CALLBACK* Save)(LPOLESERVERDOC);
    OLESTATUS (CALLBACK* Close)(LPOLESERVERDOC);
    OLESTATUS (CALLBACK* SetHostNames)(LPOLESERVERDOC, OLE_LPCSTR,
        OLE_LPCSTR);
    OLESTATUS (CALLBACK* SetDocDimensions)(LPOLESERVERDOC,
        OLE_CONST RECT FAR*);
    OLESTATUS (CALLBACK* GetObject)(LPOLESERVERDOC, OLE_LPCSTR,
        LPOLEOBJECT FAR*, LPOLECLIENT);
    OLESTATUS (CALLBACK* Release)(LPOLESERVERDOC);
    OLESTATUS (CALLBACK* SetColorScheme)(LPOLESERVERDOC,
        OLE_CONST LOGPALETTE FAR*);
    OLESTATUS (CALLBACK* Execute)(LPOLESERVERDOC, HGLOBAL);
} OLESERVERDOCVTBL;

The OLESERVERDOCVTBL structure points to functions that manipulate a document. A server application creates this structure and an OLESERVERDOC structure to give the server library access to a document.

Documents opened or created on request from the library should not be shown to the user for editing until the library requests that they be shown.

Every function except Release can return OLE_BUSY.

Function

Save

The Save function instructs the server to save the document.

Parameters

lpDoc

Points to an OLESERVERDOC structure corresponding to the document to save.

Return Value

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

Function

Close

The Close function instructs the server application to unconditionally close the document. The library calls this function when the client application initiates the closure.

Parameters

lpDoc

Points to an OLESERVERDOC structure corresponding to the document to close.

Return Value

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

Comments

The library always calls the Close function before calling the Release function in the OLESERVERVTBL structure.

The server application should not prompt the user to save the document or take other actions; messages of this kind are handled by the client application.

When the library calls the Close function, the server should respond by calling the OleRevokeServerDoc function. The resources for the document are freed when the library calls the Release function. The server should not wait for the Release function by entering a message-dispatch loop after calling OleRevokeServerDoc. (A server should never enter message-dispatch loops while processing any of these functions.)

When a document is closed, the server should free the memory for the OLESERVERDOCVTBL structure and associated resources.

Function

SetHostNames

The SetHostNames function sets the name that should be used for a window title. This name is used only for an embedded object, because a linked object has its own title. This function is used only for documents that are embedded objects.

Parameters

lpDoc

Points to an OLESERVERDOC structure corresponding to a document that is the embedded object for which a name is specified.

lpszClient

Points to a null-terminated string specifying the name of the client.

lpszDoc

Points to a null-terminated string specifying the client's name for the object.

Return Value

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

Function

SetDocDimensions

The SetDocDimensions function gives the server the rectangle on the target device for which the object should be formatted. This function is relevant only for documents that are embedded objects.

Parameters

lpDoc

Points to the OLESERVERDOC structure corresponding to the document that is the embedded object for which the target size is specified.

lpRect

Points to a RECT structure containing the target size of the object, in MM_HIMETRIC units. (In the MM_HIMETRIC mapping mode, the positive y-direction is up.)

Return Value

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

Function

GetObject

The GetObject function requests the server to create an OLEOBJECT structure.

Parameters

lpDoc

Points to an OLESERVERDOC structure corresponding to this document.

lpszItem

Points to a null-terminated string specifying the name of an item in the specified document for which an object structure is requested. If this string is set to NULL, the entire document is requested. This string cannot contain a slash mark (/).

lplpObject

Points to a variable of type LPOLEOBJECT in which the server application should return a long pointer to the allocated OLEOBJECT structure.

lpClient

Points to an OLECLIENT structure allocated by the library. The server should associate the OLECLIENT structure with the object and use it to notify the library of changes to the object.

Return Value

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

Comments

The server application should allocate and initialize the OLEOBJECT structure, associate it with the OLECLIENT structure pointed to by the lpClient parameter, and return a pointer to the OLEOBJECT structure through the lplpObject argument.

The library calls the GetObject function to associate a client with the part of the document identified by the lpszItem parameter. When a client has been associated with an object by this function, the server can send notifications to the client.

Applications should be prepared to handle multiple calls to GetObject for a given object. This entails creating multiple OLECLIENT structures and sending notifications to each of these structures when appropriate. Multiple calls to GetObject are possible because some client applications that implement object linking and embedding (OLE) by using dynamic data exchange (DDE) rather than the OLE dynamic-link libraries may use both NULL and an actual item name for the lpszItem parameter.

Function

Release

The Release function notifies the server when a revoked document has terminated conversations and can be destroyed.

Parameters

lpDoc

Points to an OLESERVERDOC structure for which the handle was revoked and which can now be released.

Return Value

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

Function

SetColorScheme

The SetColorScheme function sends the server application the color palette recommended by the client application.

Parameters

lpDoc

Points to an OLESERVERDOC structure for which the client application recommends a palette.

lpPal

Points to a LOGPALETTE structure specifying the recommended palette.

Return Value

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

Comments

Server applications are not required to use the palette recommended by the client application.

Before returning from the SetColorScheme function, the server application should create a handle to the palette. To do this, the server application should use the palette pointed to by the lpPal parameter in a call to the CreatePalette function, as shown in the following example.

hpal = CreatePalette(lpPal);

The server can then use the palette handle to refer to the palette.

The first palette entry in the LOGPALETTE structure specifies the foreground color recommended by the client application. The second palette entry specifies the background color. The first half of the remaining palette entries are fill colors, and the second half are colors for lines and text.

Client applications typically specify an even number of palette entries. When there is an uneven number of entries, the server should interpret the odd entry as a fill color; that is, if there are five entries, three should be interpreted as fill colors and two as line and text colors.

Function

Execute

The Execute function receives WM_DDE_EXECUTE commands sent by client applications. The applications send these commands by calling the OleExecute function.

Parameters

lpDoc

Points to an OLESERVERDOC structure to which the dynamic data exchange (DDE) commands apply.

hCommands

Identifies memory containing one or more DDE execute commands.

Return Value

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

Comments

The server should never free the handle specified in the hCommands parameter.