define-dde-server-function name-and-options transaction ( binding *) form * => name
name-and-options ::= name | ( name [[ option ]])
transaction ::= :request | :poke | :execute
option ::= :server server | :topic-class topic-class | :topic topic | :item item | :format format | :command command | :result-type result-type | :advisep advisep
binding ::= var-binding | execute-arg-binding
var-binding ::= ( var :server) | ( var :topic) | ( var :data [ data-type ]) | ( var :format)
A symbol.
A keyword.
A server object.
A topic class.
A symbol naming a dispatch topic.
A string.
A keyword.
A string.
A data type.
A boolean.
A variable.
A data type.
A data type.
A Lisp form.
The macro
define-dde-server-function
is used to define a server function, called
name
, 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.
:server
should be used to specify the server class.
:topic-class
may be used to specify the topic-class for which this definition should be used. It can be a symbol which names a
topic-class
, or
t
(meaning All topics, this is the default for execute transactions), or
:system
(The System topic), or
:non-system
(any topic except the System topic). In the case of execute transactions only,
:topic-class
defaults to
t
; 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.
dde-dispatch-topic
, previously defined by define-dde-dispatch-topic. This is the main use of dispatching topics. In this case
:topic
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
:format
option is used to specify the format understood. It defaults to
:text
. It can be specified as
:all
, in which case the
:format
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.
The
execute-arg-bindings
are only used with execute transactions. They specify the arguments expected.
type-spec
should be one of
t
,
string
,
number
,
integer
or
float
. If not specified,
t
is assumed.
The
var-bindings
may appear anywhere in the binding list, and in any order. Binding variables to
:server
and
:topic
is useful with all transaction types. A
:server
binding causes the variable to be bound to the server object, whereas a
:topic
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.
A
:format
binding can only be used with request and poke transactions, where an
option
of
:format :all
has been specified. It causes the variable specified by
var
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.
A
:data
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
data-type
is specified as
:string-list
, 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.
For execute and poke transactions, the body of the defined function is expected to return t for success and
nil
for failure.
For request transactions, the body of the defined function is normally expected to return a result value, or
nil
for failure.
The
result-type
option may only be specified for request transactions. If it is specified as
:string-list
, 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
nil
to mean the empty list, rather than failure. In this case, the
result-type
can be specified as
(:string-list t)
. 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:
[command1(arg1,arg2,...)][command2(arg1,arg2,...)]...]
Note that multiple commands may be packed into a single execute transaction. However,
dde-execute-command
does not currently generate such strings.
LispWorks User Guide and Reference Manual - 21 Dec 2011