OLESERVERVTBL

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.

Open

	OLESTATUS Open(lpServer, lhDoc, lpszDoc, lplpDoc)
	LPOLESERVER lpServer;
	LHSERVERDOC lhDoc;
	LPSTR 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. Normally this string is a path name, 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 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.

Create

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

The Create function makes a new object of a given class name which will 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 an LPOLESERVERDOC where 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.

CreateFromTemplate

	OLESTATUS CreateFromTemplate(lpServer, lhDoc, lpszClass, lpszDoc, lpszTemplate, lplpDoc)
	LPOLESERVER lpServer;
	LHSERVERDOC lhDoc;
	LPSTR lpszClass;
	LPSTR lpszDoc;
	LPSTR 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 may be used in window titles etc.

lpszTemplate

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

lplpDoc

Points to an LPOLESERVERDOC where 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

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

Edit

	OLESTATUS Edit(lpServer, lhDoc, lpszClass, lpszDoc, lplpDoc)
	LPOLESERVER lpServer;
	LHSERVERDOC lhDoc;
	LPSTR lpszClass;
	LPSTR 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 in window titles etc.

lplpDoc

Points to an LPOLESERVERDOC where 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 when the data has been retrieved and the library uses the Show function in the OLEOBJECTVTBL structure (or the DoVerb function with an “edit” verb) to show the document to the user.

Exit

	OLESTATUS Exit(lpServer)
	LPOLESERVER lpServer;

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

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.

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 terminate.

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 terminate. When a server application calls the OleRevokeServer function, the application must wait, dispatching messages, for the library to call the Release function before terminating.

The server must exit when it is invisible and the library calls Release. (The only exception is when an application supports multiple servers; in this case, an invisible server is sometimes not revokable 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 explicitly loads a document into a single-instance (MDI) server, however, the server should not exit when the library calls Release.

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

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

Execute

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

The Execute function sends the server application one or more DDE execute commands.

Parameters

lpServer

Points to an OLESERVER structure identifying the server.

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.