The specific functions that each member of the OLESERVERVTBL data structure members point to are described in the following sections. You will need to code these functions to the meet the needs of your application.
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. This function typically opens a linked object for a client application.
| Parameter | Description |
| lpServer | Points to an OLESERVER structure identifying the server application. |
| lhDoc | Identifies the document; the server DLL uses this handle internally. |
| lpszDoc | Points to a null-terminated string specifying the pathname of the document to be opened. Normally this string is a pathname to a file, but for some applications it might specify other data—for example, 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. |
When the server DLL calls this function, the server application opens the specified document, allocates and initializes an OLESERVERDOC structure, associates the handle lhDoc with the document, and returns the address of the structure.
The server application does not show the document or its window.
The return value is OLE_OK if successful; otherwise, it is an error value.
OLESTATUS Create(lpServer, lhDoc, lpszClass, lpszDoc, lplpDoc)
LPOLESERVER lpServer;
LHSERVERDOC lhDoc;
OLE_LPCSTR lpszClass;
OLE_LPCSTR lpszDoc;
LPOLESERVERDOC FAR * lplpDoc;
The Create function creates a new server document.
| Parameter | Description |
| lpServer | Points to an OLESERVER structure identifying the server application. |
| lhDoc | Identifies the document. The server DLL 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. |
When the server DLL calls this function, the server application creates a document of a specified class, allocates and initializes an OLESERVERDOC structure, associates the 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 application document when it is updated or closed.
The server should perform the following steps:
1.Create a document of a specified class.
2.Allocate and initialize an OLESERVERDOC structure and its associated OLESERVERDOCVTBL.
3.Save the lhDoc parameter for future use.
4.Return a pointer to the OLESERVERDOC via the lplpDoc parameter.
The return value is OLE_OK if successful; otherwise, it could be OLE_ERROR_NEW.
OLESTATUS CreateFromTemplate(lpServer, lhDoc, lpszClass, lpszDoc,
lpszTemplate, lplpDoc)
LPOLESERVER lpServer;
LHSERVERDOC lhDoc;
OLE_LPCSTR lpszClass;
OLE_LPCSTR lpszDoc;
OLE_LPCSTR lpszTemplate;
LPOLESERVERDOC FAR * lplpDoc;
CreateFromTemplate creates a new object from a template (usually using OleCreateFromTemplate).
| Parameter | Description |
| lpServer | Points to an OLESERVER structure identifying the server application. |
| lhDoc | Identifies the document. The DLL 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 the name for the document to be created. This name can be used in window titles and so on. |
| lpszTemplate | Points to a null-terminated string specifying the permanent name of the document to use when initializing 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. |
In response to this call, the server application creates a new document that is initialized with the data from a specified file. The new document is opened for editing by this function. When the server DLL calls this function, the server application should perform the following steps:
1.Create a document of specified class.
2.Read the contents of the specified file and use it to initialize the document.
3.Allocate and initialize an OLESERVERDOC structure.
4.Save the lhDoc for future use.
5.Return a pointer to the OLESERVERDOC via the lplpDoc parameter.
The return value is OLE_OK if successful; otherwise it could be OLE_ERROR_TEMPLATE.
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.
| Parameter | Description |
| lpServer | Points to an OLESERVER structure identifying the server application. |
| lhDoc | Identifies the document. The DLL 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 may be used in window titles and so on. |
| lplpDoc | Points to an LPOLESERVERDOC where the server application should return a long pointer to the created OLESERVERDOC structure. |
The server application does not show the document or its window in response to this call. In response to a call to Edit, the server application needs to create a new server document by doing the following steps:
1.Create a document of the specified class.
2.Allocate and initialize an OLESERVERDOC structure.
3.Save the lhDoc for future use.
4.Return a pointer to the OLESERVERDOC via the lplpDoc parameter.
The document created by the Edit function retrieves the initial data from the client application in a subsequent call to the SetData function. The user can edit the document when the data has been retrieved and the DLL uses the Show function in the OLEOBJECTVTBL structure (or the DoVerb function with an "edit" verb) to show the document to the user.
The return value is OLE_OK if successful; otherwise it could be OLE_ERROR_EDIT.
OLESTATUS Exit(lpServer)
LPOLESERVER lpServer;
The Exit function instructs the server application to close documents and terminate.
| Parameter | Description |
| lpServer | Points to an OLESERVER structure identifying the server application. |
If the server application has no open documents when the Exit function is called, it should call OleRevokeServer.
In response to a call to Exit, the server applicaiton should perform the following steps:
1.Call OleRevokeServer, which will eventually cause Release to be called (OLE_WAIT_FOR_RELEASE can be ignored).
2.Do whatever is required to terminate the application such as post a WM_CLOSE message or call a termination routine. It is legal to call DestroyWindow or PostQuitMessage from within Exit.
The return value is OLE_OK if successful; otherwise it could be OLE_ERROR_GENERIC.
OLESTATUS Release(lpServer)
LPOLESERVER lpServer;
The Release function notifies the server application that all connections to it have closed and that it is safe to terminate.
| Parameter | Description |
| lpServer | Points to an OLESERVER structure identifying the server application. |
Generally, the server DLL calls the Release function when it is safe for a server application to terminate. When a server application calls the OleRevokeServer function, it must wait, dispatching messages, for the DLL to call the Release function before terminating.
If the server application has already called OleRevokeServer when Release is called, then it can terminate. If Release is called before the server application has called OleRevokeServer, then rather than terminating, it must call OleRevokeServer before returning from Release.
If the server application has already called OleRevokeServer, it should respond to a subsequent Release call by performing the following steps:
1.Free any resources associated with lpServer, including the OLESERVER structure if it was dynamically allocated.
2.Set a release status flag, if appropriate. (Many applications keep a flag indicating the release status of the server.)
3.Do whatever is necessary to terminate—for example, posting a WM_CLOSE message would be one way to terminate an application.
If the server application has not called OleRevokeServer, the following actions apply:
If the server application is invisible when the DLL calls Release, it must call OleRevokeServer and return. (The only exception is when an application supports multiple server applications; in which case, an invisible server application is sometimes not revocable when the DLL calls Release.)
If the server application has no open documents and was started with the /Embedding option (indicating that it was started by a client application), it should call OleRevokeServer and return when the DLL calls Release.
Note If the preceding conditions are not present and the server application has not yet called OleRevokeServer, or conditions are not present and the user has explicitly loaded a document into a single-instance MDI server application, then the server should neither terminate nor call OleRevokeServer.
All registered server structures must be released before a server can terminate.
A server can call the PostQuitMessage function inside the Release function.
The return value is OLE_OK if successful; otherwise it could be OLE_ERROR_GENERIC.
OLESTATUS Execute(lpServer, hCommands)
LPOLESERVER lpServer;
HGLOBAL hCommands;
The Execute function sends the server application one or more DDE execute commands.
| Parameter | Description |
| lpServer | Points to an OLESERVER structure identifying the server application. |
| 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.