Values

Description

The
dde-advise-start
function sets up an advise loop for the data item specified by
item
on the specified
conversation
.

The argument
format
should be one of the following:

A DDE format specifier, consisting of either a standard clipboard format or a registered clipboard format.

A string containing either the name of a standard clipboard format (without the
CF_
prefix), or the name of a registered clipboard format.

A symbol, in which case its print name is taken to specify the clipboard format.

The keyword
:text
- the default value of
format
. The keyword
:text
is treated specially. If supported by the server it uses the
CF_UNICODETEXT
clipboard format, otherwise it used the
CF_TEXT
format.

The argument
type
specifies how the response data should be converted to a Lisp object. For text formats, the default value indicates that a Lisp string should be created. The value
:string-list
may be specified to indicate that the return value should be taken as a tab-separated list of strings; in this case the Lisp return value is a list of strings. The default conversation class only supports text formats, unless
type
is specified as
:foreign
, which can be used with any clipboard format. It returns a
clipboard-item
structure, containing a foreign pointer to the data, the data length, and the format identifier.

If
datap
is
t
(the default value), a hot link is established, where the new data is supplied whenever it changes. If
datap
is
nil
, a warm link is established, where the data is not passed, and must be explicitly requested using dde-request.

The argument
key
is used to identify this link. If specified as
nil
(the default value), it defaults to the conversation. Multiple links are permitted on a conversation with the same
item
and
format
values, as long as their
key
values differ.

If the link is established, the return value
result
is
t
. If the link could not be established, the behavior depends on the value of
errorp
. If
errorp
is
t
(the default value), LispWorks signals an error. If it is
nil
, the function returns
nil
to indicate failure.

If the link is established, the function
function
is called whenever the data changes. If
function
is
nil
(the default value), then the generic function dde-client-advise-data will be called.

The function specified by
function
should have a lambda list similar to the following:

key
item
data
&key
conversation
&allow-other-keys

The arguments
key
and
item
identify the link. The argument
data
contains the new data for hot links; for warm links it is
nil
.