Accessor

Summary

An accessor which can perform a request transaction or a poke transaction on an automatically managed conversation.

Package

win32

Signature

dde-item* service topic item &key format type errorp connect-error-p new-conversation-p => result

Arguments

service

A string or symbol.

topic

A string or symbol.

item

A string or symbol.

format

A clipboard format specifier.

type

A keyword.

errorp

A boolean.

connect-error-p

A boolean.

new-conversation-p

A boolean.

Values

result

A boolean.

Description

The accessor dde-item* is similar to dde-item, and performs a request transaction when read. It performs a poke transaction when set.

To illustrate, the following dde-request* command

(dde-request* service topic item :format format :type type :errorp errorp connect-error-p new-conversation-p)

can also be issued using dde-item* as follows:

(dde-item* service topic item :FORMAT format :TYPE type :ERRORP errorp connect-error-p new-conversation-p)

Similarly, the following dde-poke* command

(dde-poke* conversation item data :format format :type type :errorp errorp connect-error-p new-conversation-p)

can be issued using dde-item* as follows:

(setf (dde-item* conversation item :format format :type type :errorp errorp connect-error-p new-conversation-p) data)

except that the format always returns data.

If necessary, the accessor dde-item* creates a conversation for the duration of the transaction, but if a suitable conversation already exists, the transaction is executed over that conversation. If you need to make several transactions with the same service and topic, placing them inside a with-dde-conversation prevents a new conversation being established for each transaction.

If new-conversation-p is set to t a new conversation is always established for the transaction. This new conversation is always automatically disconnected when the transaction is completed.

If connect-error-p is t (the default value), then LispWorks signals an error if a conversation cannot be established. If it is nil, dde-item* returns nil if a conversation cannot be established. This allows the caller to distinguish between the cases when the server is not running, and when the server is running but the transaction fails.

On success, the function returns t. On failure, the behavior depends on the value of the errorp argument. If errorp is t (the default value), LispWorks signals an error. If it is nil, the function returns nil to indicate failure.

See also

dde-item
dde-poke
dde-request