A server object.
A topic class.
A symbol naming a dispatch topic.
A data type.
A data type.
A data type.
A Lisp form.
is used to define a server function, called
, which is called when a specific transaction occurs. The defined function may either be attached to a server class (using the dispatching capabilities built into the server implementation) or to a named dispatch topic.
To attach the definition to a server,
should be used to specify the server class.
may be used to specify the topic-class for which this definition should be used. It can be a symbol which names a
(meaning All topics, this is the default for execute transactions), or
(The System topic), or
(any topic except the System topic). In the case of execute transactions only,
; in all other cases, it must be specified. Typically, execute transactions ignore the topic of the conversation. Alternatively, you may choose to only support execute transactions in the system topic.
A server function may instead be attached to a particular instance of
, previously defined by define-dde-dispatch-topic. This is the main use of dispatching topics. In this case
should be provided with a symbol that names a dispatching topic. The function is installed on that topic, and only applies to that topic.
In the case of a request or poke transaction, item is a string defining the item name for which this definition should be invoked. It defaults to the capitalized print-name of name , with hyphens removed.
For request transactions, the
option is used to specify the format understood. It defaults to
. It can be specified as
, in which case the
binding may be used to determine the actual format requested (see below).
In the case of an execute transaction, command is a string specifying the name of the command for which this definition should be invoked. It defaults to the capitalized print-name of name , with hyphens removed.
are only used with execute transactions. They specify the arguments expected.
should be one of
. If not specified,
may appear anywhere in the binding list, and in any order. Binding variables to
is useful with all transaction types. A
binding causes the variable to be bound to the server object, whereas a
binding causes the variable to be bound to the topic object. This allows the server and/or the topic to be referred to in the body of the function.
binding can only be used with request and poke transactions, where an
has been specified. It causes the variable specified by
to be bound to the format of data requested or supplied. The body of the defined function should fail the transaction if it does not support the requested format.
binding can only be used with poke transactions. It binds a variable to the data to be poked. For text transfers, the data variable is normally bound to a string. However, if
is specified as
, the data in the transaction is interpreted as a tab-separated list of strings, and the data variable is bound to a list of strings.
option may only be specified for request transactions. If it is specified as
, then for text requests the body is expected to return a list of strings, which are used to create a tab-separated list to be returned to the client.
Sometimes, it may be necessary to support returning
to mean the empty list, rather than failure. In this case, the result-type can be specified as
. The body is then expected to return two values: a list of strings, and a flag indicating success.
In the case of execute transactions, the command name and arguments are unmarshalled by the default argument unmarshalling. This is compatible with the default argument unmarshalling described under dde-execute-command. The execute string is expected to be of the following syntax: