Function

Summary

Sets up an advise loop on a specified data item for a conversation.

Package

win32

Signature

dde-advise-start conversation item &key key function format datap type errorp => result

Arguments

conversation

A conversation object.

item

A string or symbol.

key

An object.

function

A function name.

format

A clipboard format specifier.

datap

A boolean.

type

A keyword.

errorp

A boolean.

Values

result

A boolean.

Description

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

See Advise loops for information about DDE advise loops.

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.

See also

dde-advise-start*
dde-advise-stop
dde-client-advise-data