22.3 Server interface

22.3.1 Starting a DDE server

To provide a LispWorks application with a DDE server, follow the following three steps.

Define a specialized Lisp DDE server class using define-dde-server. Here the server class is called foo-server and it has the service name "FOO":
```
(define-dde-server foo-server "FOO")
```
Provide the server class with the functionality it requires by specializing methods on it and/or using define-dde-server-function. Here the server function is bar, which takes a string as an argument, and prints this to the standard output. For convenience, the system topic is used, though usually it is better to define your own topic.
```
(define-dde-server-function (bar :topic :system)
    :execute
    ((x string))
  (format t "~&~s~%" x)
  t)
```
Start an instance of the server foo-server using start-dde-server.
```
(start-dde-server `foo-server)
```
This function returns the server object, which responds to requests for conversations with the service name "FOO", and accepts execute transactions for the function bar in the "System" topic.

22.3.2 Handling poke and request transactions

Poke and request transactions issued to a server object are handled by defining a method on each of the generic functions dde-server-poke and dde-server-request.

22.3.3 Topics

DDE servers respond to connection requests containing a service name and a topic name. The service name of a server is the same for any conversation whereas the topic name may vary from conversation to conversation, and identifies the context of the conversation. Typically, valid topics correspond to open documents within the application, so the set of valid topics varies from time to time. In addition, all servers implement a topic called "System", which contains a standard set of items that can be read.

The LispWorks DDE interface supports three types of topics:

General topics.
A general topic is an instance of a user-defined topic class. The actual set of topics available may vary from time to time as the application is running.
Dispatching topics.
A dispatching topic has a fixed name, and is available at all times that the server is running. It supports a fixed set of items, and each of these items has Lisp code associated with it to implement these items.
The system topic.
The system topic is provided automatically by the LispWorks DDE interface. However, a mechanism is provided to extend the functionality of the system topic by handling additional items.

22.3.3.1 General topics

To use general topics, the LispWorks application must define one or more subclasses of dde-topic. If an application supports only a single type of document, it will typically require only one topic class. If several different types of document are supported, it may be convenient to define a different topic class for each type of document.

If the application uses general topics, it should define a method on the dde-server-topics generic function, specializing on the application's server class.

22.3.3.2 Dispatching topics

A dispatching topic is a topic which has a fixed name and always exists. Dispatching topics provide dispatching capabilities, whereby appropriate application-supplied code is executed for each supported transaction. Dispatch topics are defined using define-dde-dispatch-topic.

22.3.3.3 The system topic

The system topic is implemented as a predefined dispatching topic called :system. It is automatically available to all defined DDE servers. Its class is dde-system-topic, which is a subclass of dde-topic.

The following items are implemented by the system topic:

SZDDESYS_ITEM_TOPICS Constant

The constant SZDDESYS_ITEM_TOPICS has the value "Topics". Referring to this item in the system topic calls dde-server-topics to obtain a list of topics implemented by the server. The server should define a method on this generic function to return a list of strings naming the topics supported by the server. If this item is not to be implemented, do not define a method on the function, or define a method that returns :unknown.

SZDDESYS_ITEM_SYSITEMS Constant

The constant SZDDESYS_ITEM_SYSITEMS has the value "SysItems". Referring to this item in the system topic calls dde-topic-items to obtain a list of items implemented by the system topic. If a server implements additional system topic items it should define a method on the generic function specialized on its server class and dde-system-topic returning the complete list of supported topics. The server can return :unknown if this item is not to be implemented.

SZDDESYS_ITEM_FORMATS Constant

The constant SZDDESYS_ITEM_FORMATS has the value "Formats", and returns unicodetext and text. Currently only text formats are supported.

The system topic is a single object which is used by all DDE servers running in the Lisp image. You should therefore not under normal circumstances modify it with define-dde-server-function by specifying a value of :system for the topic argument, as this would make the changes to the system topic visible to all users of DDE within the Lisp image.

Instead, specify :server my-server :topic :system, where my-server is the name of your DDE server. This makes the additional items available only on the system topic of the specified server.