define-dde-server-function

define-dde-server-function Macro

Summary

Defines a server function that is called when a specific transaction occurs.

Package

win32

Signature

define-dde-server-function name-and-options transaction (binding*) form* => name

name-and-options ::= name | (name [[option]])

transaction ::= :request | :poke | :execute

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)

Arguments

`transaction`	A keyword.
`form`⇩	A Lisp form.
`name`⇩	A symbol.
`server`⇩	A server object.
`topic-class`⇩	A topic class.
`topic`⇩	A symbol naming a dispatch topic.
`item`⇩	A string.
`format`⇩	A keyword.
`command`⇩	A string.
`result-type`⇩	A data type.
`advisep`⇩	A boolean.
`var`⇩	A variable.
`data-type`⇩	A data type.
`type-spec`⇩	A data type.

Values

name

A symbol.

Description

The macro define-dde-server-function is used to define a server function, called name, which causes form's to be evaluated 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 server should be used to specify the server class. :topic-class topic-class may be used to specify the topic-class for which this definition should be used. topic-class 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 topic should be provided, where topic is 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 format option is used to specify the format understood. format 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 addition, if advisep is non-nil then the server will accept requests to start an advise loop.

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.

result-type 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, 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.