The specific callback functions that each member of the OLESERVERDOCVTBL data structure points to are described in the following sections. You will need to code these functions to meet the needs of your application.
OLESTATUS Save(lpDoc)
LPOLESERVERDOC lpDoc;
The Save function instructs the server application to save the document.
| Parameter | Description |
| lpDoc | Points to an OLESERVERDOC structure corresponding to the document to save. |
This callback is only invoked when a linked object is being edited, so it is assumed that the server application already knows the object's filename. In response, the server application should save the specified document.
The return value is OLE_OK if successful; otherwise, it could be OLE_ERROR_GENERIC.
OLESTATUS Close(lpDoc)
LPOLESERVERDOC lpDoc;
The Close function instructs the server application to unconditionally close the document.
| Parameter | Description |
| lpDoc | Points to an OLESERVERDOC structure corresponding to the document to close. |
The server DLL calls this function when the client application initiates the closure. lpDoc points to an OLESERVERDOC structure corresponding to the document to close.
When the server DLL calls the Close function, the server application should respond by calling OleRevokeServerDoc. The resources for the document are freed when the DLL calls the Release callback function. The server should not wait for the Release function by entering a message-dispatch loop after calling OleRevokeServerDoc. (Message-dispatch loops should never be entered while processing any of these functions.)
The return value is OLE_OK if successful; otherwise, it is an error value.
OLESTATUS SetHostNames(lpDoc, lpszClient, lpszDoc)
LPOLESERVERDOC lpDoc;
OLE_LPCSTR lpszClient;
OLE_LPCSTR lpszDoc;
The SetHostNames function sets the names that should be used for window titles. This function is relevant only for documents that are embedded objects.
| Parameter | Description |
| lpDoc | Points to an OLESERVERDOC structure corresponding to a document that is the embedded object for which names are specified. |
| lpszClient | Points to a null-terminated string specifying the name of the client. |
| lpszDoc | Points to a null-terminated string specifying the client application's name for the object. |
The names are used only for embedded objects, because linked objects have their own titles.
The server should perform the following steps:
1.Change the title bar to reflect the embedded state with appropriate names.
2.Change the File menu to reflect the name of the client application. (See Chapter 3, "The OLE User Interface," for explicit information on the appearance of menus and title bars.)
3.Save the client and object names for later use in message boxes.
The return value is OLE_OK if successful; otherwise, it could be OLE_ERROR_GENERIC.
OLESTATUS SetDocDimensions(lpDoc, lpRect)
LPOLESERVERDOC lpDoc;
OLE_CONST RECT FAR* lpRect;
The SetDocDimensions function gives the server application the rectangle on the target device for which the object should be formatted. This function is relevant only for documents that are embedded objects.
| Parameter | Description |
| 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.) |
The return value is OLE_OK if successful; otherwise, it is an error value.
OLESTATUS GetObject(lpDoc, lpszItem, lplpObject, lpClient)
LPOLESERVERDOC lpDoc;
OLE_LPCSTR lpszItem;
LPOLEOBJECT FAR * lplpObject;
LPOLECLIENT lpClient;
The GetObject function requests the server application to create an OLEOBJECT structure.
| Parameter | Description |
| 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 NULL or "" (GetObject should check for either), the entire document is requested. |
| lplpObject | Points to a variable of type LPOLEOBJECT where the server application should return a long pointer to the allocated OLEOBJECT structure. |
| lpClient | Points to an OLECLIENT structure allocated by the DLL. The server should associate the OLECLIENT structure with the object and use it to notify the DLL of changes to the object. |
GetObject is called when a client application creates an object (usually using functions like OleCreate). It requests that the server associate an OLECLIENT structure with an object. If the object name is NULL (lpszItem = = "" or lpszItem = = NULL), then the object is the whole document. Otherwise, the object name specifies which object in the document is to be associated with the structure.
GetObject is generally called after ServerCreateFromTemplate, ServerCreate, ServerEdit or ServerOpen is called, although not limited to these cases.
The DLL calls the GetObject function to associate a client application with the part of the document identified by the lpszItemname parameter. When a client has been associated with an object by this function, the server application can send notifications to it.
The server should perform the following steps:
1.Allocate and initialize an OLEOBJECT structure.
2.Save the LPOLECLIENT with the OLEOBJECT for later use in notifying the client's callback.
3.Return a pointer to the OLEOBJECT via the lplpObject parameter.
The return value is OLE_OK if successful; otherwise, it could be
OLE_ERROR_MEMORY
OLE_ERROR_NAME
OLESTATUS Release(lpDoc)
LPOLESERVERDOC lpDoc;
The Release function notifies the server application when a revoked document has terminated conversations and may be destroyed.
The server application may free any document resources.
| Parameter | Description |
| lpDoc | Points to an OLESERVERDOC structure for which the handle was revoked and which may now be released. |
The return value is OLE_OK if successful; otherwise, it is an error value.
OLESTATUS SetColorScheme(lpDoc, lpPal)
LPOLESERVERDOC lpDoc;
OLE_CONST LOGPALETTE FAR* lpPal;
The SetColorScheme function sends the server application the color palette recommended by the client application although server applications are not required to use the palette recommended by the client application.
| Parameter | Description |
| lpDoc | Points to an OLESERVERDOC structure for which the client application recommends a palette. |
| lpPal | Points to a LOGPALETTE structure specifying the recommended palette. |
The server application should:
1.Allocate and fill in its own LOGPALETTE structure that contains the colors passed via lpPal.
2.Create a palette from the application-defined LOGPALETTE structure using CreatePalette. This palette can be used to render objects and color menus as the user edits objects in the document.
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 round to the fill colors; that is, if there are five entries, three should be interpreted as fill colors and two as line and text colors.
The return value is OLE_OK if successful; otherwise is could be OLE_ERROR_PALETTE.
OLESTATUS Execute(lpDoc, hCommands)
LPOLESERVERDOC lpDoc;
HGLOBAL hCommands;
The Execute function sends the server application one or more DDE execute commands.
| Parameter | Description |
| lpDoc | Points to an OLESERVERDOC structure to which the DDE commands apply. |
| hCommands | Identifies memory containing one or more DDE execute commands. |
The server application should never free the handle specified in the hCommands parameter.
The return value is OLE_OK if successful; otherwise, it is an error value.