define-dde-server-function

Signature

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)

execute-arg-binding ::= var | ( var type-spec )

Description

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.

To attach the definition to a server, :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.

A server function may instead be attached to a particular instance of 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.