OLESERVERVTBL

3.1

#include <ole.h>

typedef struct _OLESERVERVTBL {  /* osv */
    OLESTATUS (CALLBACK* Open)(LPOLESERVER, LHSERVERDOC,
        OLE_LPCSTR, LPOLESERVERDOC FAR*);
    OLESTATUS (CALLBACK* Create)(LPOLESERVER, LHSERVERDOC,
        OLE_LPCSTR, OLE_LPCSTR, LPOLESERVERDOC FAR*);
    OLESTATUS (CALLBACK* CreateFromTemplate)(LPOLESERVER,
        LHSERVERDOC, OLE_LPCSTR, OLE_LPCSTR, OLE_LPCSTR,
        LPOLESERVERDOC FAR*);
    OLESTATUS (CALLBACK* Edit)(LPOLESERVER, LHSERVERDOC,
        OLE_LPCSTR, OLE_LPCSTR, LPOLESERVERDOC FAR*);
    OLESTATUS (CALLBACK* Exit)(LPOLESERVER);
    OLESTATUS (CALLBACK* Release)(LPOLESERVER);
    OLESTATUS (CALLBACK* Execute)(LPOLESERVER, HGLOBAL);
} OLESERVERVTBL;

The OLESERVERVTBL structure points to functions that manipulate a server. After a server application creates this structure and an OLESERVER structure, the server library can perform operations on the server application.

Every function except Release can return OLE_BUSY.

Function

Open

	OLESTATUS Open(lpServer, lhDoc, lpszDoc, lplpDoc)
	LPOLESERVER lpServer;
	LHSERVERDOC lhDoc;
	OLE_LPCSTR lpszDoc;
	LPOLESERVERDOC FAR* lplpDoc;

The Open function opens an existing file and prepares to edit the contents. A server typically uses this function to open a linked object for a client application.

Parameters

lpServer

Points to an OLESERVER structure identifying the server.

lhDoc

Identifies the document. The library uses this handle internally.

lpszDoc

Points to a null-terminated string specifying the permanent name of the document to be opened. Typically this string is a path, but for some applications it might be further qualified. For example, the string might specify a particular table in a database.

lplpDoc

Points to a variable of type LPOLESERVERDOC in which the server application returns a long pointer to the OLESERVERDOC structure it has created in response to this function.

Return Value

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

Comments

When the library calls this function, the server application opens a specified document, allocates and initializes an OLESERVERDOC structure, associates the library's handle with the document, and returns the address of the structure. The server does not show the document or its window.

Function

Create

	OLESTATUS Create(lpServer, lhDoc, lpszClass, lpszDoc, lplpDoc)
	LPOLESERVER lpServer;
	LHSERVERDOC lhDoc;
	OLE_LPCSTR lpszClass;
	OLE_LPCSTR lpszDoc;
	LPOLESERVERDOC FAR* lplpDoc;

The Create function makes a new object that is to be embedded in the client application. The lpszDoc parameter identifies the object but should not be used to create a file for the object.

Parameters

lpServer

Points to an OLESERVER structure identifying the server.

lhDoc

Identifies the document. The library uses this handle internally.

lpszClass

Points to a null-terminated string specifying the class of document to create.

lpszDoc

Points to a null-terminated string specifying a name for the document to be created. This name can be used to identify the document in window titles.

lplpDoc

Points to a variable of type LPOLESERVERDOC in which the server application should return a long pointer to the created OLESERVERDOC structure.

Return Value

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

Comments

When the library calls this function, the server application creates a document of a specified class, allocates and initializes an OLESERVERDOC structure, associates the library's handle with the document, and returns the address of the structure. This function opens the created document for editing and embeds it in the client when it is updated or closed.

Server applications often track changes to the document specified in this function, so that the user can be prompted to save changes when necessary.

Function

CreateFromTemplate

	OLESTATUS CreateFromTemplate(lpServer, lhDoc, lpszClass, lpszDoc, lpszTemplate, lplpDoc)
	LPOLESERVER lpServer;
	LHSERVERDOC lhDoc;
	OLE_LPCSTR lpszClass;
	OLE_LPCSTR lpszDoc;
	OLE_LPCSTR lpszTemplate;
	LPOLESERVERDOC FAR* lplpDoc;

The CreateFromTemplate function creates a new document that is initialized with the data in a specified file. The new document is opened for editing by this function and embedded in the client when it is updated or closed.

Parameters

lpServer

Points to an OLESERVER structure identifying the server.

lhDoc

Identifies the document. The library uses this handle internally.

lpszClass

Points to a null-terminated string specifying the class of document to create.

lpszDoc

Points to a null-terminated string specifying a name for the document to be created. This name need not be used by the server application but can be used in window titles.

lpszTemplate

Points to a null-terminated string specifying the permanent name of the document to use to initialize the new document. Typically this string is a path, but for some applications it might be further qualified. For example, the string might specify a particular table in a database.

lplpDoc

Points to a variable of type LPOLESERVERDOC in which the server application should return a long pointer to the created OLESERVERDOC structure.

Return Value

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

Comments

A server application often tracks changes to the document specified in this function, so that the user can be prompted to save changes when necessary.

Function

Edit

	OLESTATUS Edit(lpServer, lhDoc, lpszClass, lpszDoc, lplpDoc)
	LPOLESERVER lpServer;
	LHSERVERDOC lhDoc;
	OLE_LPCSTR lpszClass;
	OLE_LPCSTR lpszDoc;
	LPOLESERVERDOC FAR* lplpDoc;

The Edit function creates a document that is initialized with data retrieved by a subsequent call to the SetData function. The object is embedded in the client application. The server does not show the document or its window.

Parameters

lpServer

Points to an OLESERVER structure identifying the server.

lhDoc

Identifies the document. The library uses this handle internally.

lpszClass

Points to a null-terminated string specifying the class of document to create.

lpszDoc

Points to a null-terminated string specifying a name for the document to be created. This name need not be used by the server application but may be used—for example, in a window title.

lplpDoc

Points to a variable of type LPOLESERVERDOC in which the server application should return a long pointer to the created OLESERVERDOC structure.

Return Value

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

Comments

The document created by the Edit function retrieves the initial data from the client in a subsequent call to the SetData function. The user can edit the document after the data has been retrieved and the library has used either the Show function in the OLEOBJECTVTBL structure or the DoVerb function with an Edit verb to show the document to the user.

Function

Exit

	OLESTATUS Exit(lpServer)
	LPOLESERVER lpServer;

The Exit function instructs the server application to close documents and quit.

Parameters

lpServer

Points to an OLESERVER structure identifying the server.

Return Value

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

Comments

The server library calls the Exit function to instruct a server application to terminate. If the server application has no open documents when the Exit function is called, it should call the OleRevokeServer function.

Function

Release

	OLESTATUS Release(lpServer)
	LPOLESERVER lpServer;

The Release function notifies a server that all connections to it have closed and that it is safe to quit.

Parameters

lpServer

Points to an OLESERVER structure identifying the server.

Return Value

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

Comments

The server library calls the Release function when it is safe for a server to quit. When a server application calls the OleRevokeServer function, the application must continue to dispatch messages and wait for the library to call the Release function before quitting.

When the server is invisible and the library calls Release, the server must exit. (The only exception is when an application supports multiple servers; in this case, an invisible server is sometimes not revocable when the library calls Release.) If the server has no open documents and it was started with the /Embedding option (indicating that it was started by a client application), the server should exit when the library calls the Release function. If the user has explicitly loaded a document into a single-instance multiple document interface server, however, the server should not exit when the library calls Release. Typically, a single-instance server is a multiple document interface (MDI) server.

All registered server structures must be released before a server can quit.

A server can call the PostQuitMessage function inside the Release function.

Function

Execute

	OLESTATUS Execute(lpServer, hCommands)
	LPOLESERVER lpServer;
	HGLOBAL hCommands;

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

Parameters

lpServer

Points to an OLESERVER structure identifying the server.

hCommands

Identifies memory containing one or more dynamic data exchange (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.