IDDEClientConversation

The IDDEClientConversation class adds Dynamic Data Exchange (DDE) client function to an application.

Create an object of this class for each conversation you want to initiate with a server application. The object manages all window, shared memory, and atom table processing. When a conversation with a server ends, the IDDEClientConversation object can initiate another conversation with that server or any other server. An object of this class can find all topics supported by all DDE server applications on the system.

This class uses a window to communicate; therefore, window message processing must occur. This means that ICurrentThread::processMsgs must be called. There are several ways for this to occur. Normally, this is accomplished by calling IApplication::current().run().

Portability Considerations

DDE is not supported on AIX.


IDDEClientConversation - Member Functions and Data by Group

Constructors & Destructor

You can construct objects of this class in two ways. Both constructors have a boolean argument, useEventThread. This argument is optional but is also highly recommended if the application must do any extensive processing or interacts with the user during any of the callback functions. Specifying true allows IDDEClientConversation to create a secondary thread to process incoming events. This prevents problems with window message processing because the thread is created without a message queue. If you specify false, no secondary thread is created, and you should return promptly from all callback functions.


[view class]
~IDDEClientConversation
public:
virtual ~IDDEClientConversation()

The destructor ends the conversation with the DDE server application if there is one active.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
IDDEClientConversation


Overload 1
public:
IDDEClientConversation( const char* applicationName, const char* topicName, bool useEventThread = true )

This constructor accepts the following arguments and attempts to begin a conversation with the requested server application on the requested topic:

The parameter useEventThread is ignored on the Windows operating system. All functions are run on the primary thread.

Exception

IOutOfSystemResource The operating system's request for either an event semaphore or a queue failed. See the text of the exception for further information.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
IDDEClientConversation(bool useEventThread = true)

This constructor initializes the object but does not start a conversation. The parameter useEventThread is ignored on the Windows operating system. All functions are run on the primary thread.

Exception

IOutOfSystemResource The operating system's request for either an event semaphore or a queue failed. See the text of the exception for further information.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Broadcasts

Use these members to query information about the topics supported by the currently active DDE server applications.


[view class]
supportedTopics
public:
virtual IDDEClientConversation& supportedTopics( IDDEActiveServerSet& activeServerSet, const char* applicationName = 0 )

Adds IDDEActiveServer objects that represent topics supported by DDE server applications to the IDDEActiveServerSet passed in as the first argument. If the applicationName argument is specified, only the topics supported by that application are added to the set. The default is to add all topics supported by all server applications.
Note: Include the iddecset.hpp header file when you use this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
supportingApplications
public:
virtual IDDEClientConversation& supportingApplications( IDDEActiveServerSet& activeServerSet, const char* topicName )

Adds IDDEActiveServer objects that represent DDE server applications that support the specified topic to the IDDEActiveServerSet passed in as the first argument.
Note: Include the iddecset.hpp header file when you use this function.

Exception

IInvalidParameter The topicName parameter is NULL.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Conversation Information

Use these members to obtain the attributes of this object, including information about the conversation if there is one currently active.


[view class]
application
public:
IString application() const

Returns the name of the server application with which the client is conversing.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
clientHandle
public:
IWindowHandle clientHandle() const

Returns the window handle of the client conversation. This is provided, along with the IDDEClientConversation::begin member, to allow an object of this class to converse with a server without engaging in the normal conversation initialization.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
inConversation
public:
bool inConversation() const

Returns true if the client is currently in conversation with a server; otherwise, it returns false.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
isCaseSensitive
public:
bool isCaseSensitive() const

Returns true if the server has indicated it enforces case sensitivity; otherwise, it returns false.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
outstandingTransactionCount
public:
unsigned long outstandingTransactionCount() const

Returns the number of transactions initiated by the client to which the server has not responded.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
topic
public:
IString topic() const

Returns the name of the topic about which the client is conversing.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Conversation Initiation and Termination

Use these members to begin and end conversations with DDE server applications.


[view class]
begin

Attempts to initiate a conversation with the requested server application on the requested topic. The primary version of this overloaded member accepts the name of the requested application and topic as input and returns true if the conversation is successfully begun; otherwise, it returns false. The version that accepts a server handle is provided along with the IDDEClientConversation::clientHandle member to allow an object of this class to converse with a server without engaging in the normal conversation initialization.


Overload 1
public:
virtual IDDEClientConversation& begin( const IWindowHandle& serverHandle )

Exception

IInvalidParameter The server window handle is not valid.
IInvalidRequest The object is already in conversation with another application.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
virtual bool begin( const char* applicationName, const char* topicName )

Exception

IInvalidParameter The applicationName or topicName parameter is NULL or has a zero length.
IInvalidRequest The object is already in conversation with another application.
IAccessError The operating system's request to begin a conversation failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
end
public:
virtual IDDEClientConversation& end()

Ends the current conversation.

Exception

IInvalidRequest The object is not in conversation with a server application.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Event Dispatching

Event-dispatching members process events sent by the DDE server application. The dispatchHandlerEvent function is called whenever an event is sent to this object, and it calls one of the other appropriate members in this object to actually process the event.

Typically, you do not need to override any of these members. If you want to provide some additional behavior before or after the event is processed, make sure that you call the IDDEClientConversation version of the member or unpredictable results can occur and the conversation may not be able to process further events from the DDE server application. You may need to override one of these members if the server application sends a DDE message not supported by the DDE protocol at that particular point in the conversation. You may need to do this because the IDDEClientConversation object throws these invalid events away.


[view class]
dispatchHandlerEvent
protected:
virtual bool dispatchHandlerEvent(IEvent& event)

Calls the appropriate virtual member if a DDE client conversation event is found.

Exception

IOutOfSystemResource The operating system's request to write to a queue failed. See the text of the exception for further information.
IAccessError This function has been called recursively, possibly violating DDE synchronization rules. Either construct this object with useEventThread=true or avoid displaying dialog boxes in the event callback functions.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
handleAck
protected:
virtual void handleAck(const IEvent& ackEvent)

Handles acknowledgments from server applications.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
handleData
protected:
virtual void handleData(const IEvent& dataEvent)

Handles data sent from server applications.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
handleInitiateAck
protected:
virtual void handleInitiateAck( const IEvent& initiateAckEvent )

Handles acknowledgments from server applications to begin requests.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
handleTerminate
protected:
virtual void handleTerminate(const IEvent& terminateEvent)

Handles termination requests from server applications.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Event Processing

Event-processing members are called to provide you with information when events are received from the DDE server application. To obtain the information provided by any of these virtual members, you must derive from this class and override the members. All of the members, except for the data member which is pure virtual, have default implementations so that you only need to override the members that provide information you want to process.

If you specify true for the useEventThread parameter of the IDDEClientConversation constructor, all of these members are invoked on a secondary thread.


[view class]
acknowledged
protected:
virtual void acknowledged( IDDEClientAcknowledgeEvent& event )

Provides generic acknowledgment from the server to a client-initiated transaction. To get information provided by this function, provide a specialized implementation in the derived class.

A positive acknowledgment can be sent in response to an IDDEClientConversation::beginHotLink or IDDEClientConversation::endHotLink member. A negative acknowledgment can be sent in response to the same two members, as well as to an IDDEClientConversation::requestData member.

If true is specified for the useEventThread argument of the IDDEClientConversation constructor, this member is called on a secondary thread.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
conversationEnded
protected:
virtual void conversationEnded(IDDEClientEndEvent& event)

Notifies the client that the conversation is ending or ended. The conversation end can be initiated by either the client or the server, and it can also be caused by an error condition in the IDDEClientConversation.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
data
protected:
virtual bool data(IDDEDataEvent& event) = 0

Provides data sent from the server. To get information provided by this member, provide a specialized implementation in the derived class.

The data can be from an active hot link or as the result of the IDDEClientConversation::requestData member being called.

If the server has requested an acknowledgment, the IDDEClientConversation object uses the return value from this member to determine whether to send a positive or negative acknowledgment. If the data is for a valid item and in the correct format, return true; otherwise, return false.

If true is specified for the useEventThread argument of the IDDEClientConversation constructor, this member is called on a secondary thread.

This member is pure virtual and must be overridden.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
executeAcknowledged
protected:
virtual void executeAcknowledged( IDDEAcknowledgeExecuteEvent& event )

Provides a positive or negative acknowledgment from the server as the result of the IDDEClientConversation::executeCommands member being called. To get information provided by this member, provide a specialized implementation in the derived class.

If true is specified for the useEventThread argument of the IDDEClientConversation constructor, this member is called on a secondary thread.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
hotLinkInform
protected:
virtual bool hotLinkInform(IDDEClientHotLinkEvent& event)

Notifies the client that the value of an item in the server for which the client has a hot link has changed. To get information provided by this member, provide a specialized implementation in the derived class.

If the server has requested an acknowledgment, the IDDEClientConversation object uses the return value from this member to determine whether to send a positive or negative acknowledgment. If the client has an active hot link for this item and has requested that only notifications be sent, return true; otherwise, return false. The default behavior is to return true.

If true is specified for the useEventThread argument of the IDDEClientConversation constructor, this member is called on a secondary thread.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
pokeAcknowledged
protected:
virtual void pokeAcknowledged( IDDEAcknowledgePokeEvent& event )

Provides a positive or negative acknowledgment from the server as the result of the IDDEClientConversation::pokeData member being called. To get information provided by this member, provide a specialized implementation in the derived class. If true is specified for the useEventThread argument of the IDDETopicServer constructor, this member is called on a secondary thread.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Hot Link Information

Use these members to obtain information about the hot links currently active in this object.


[view class]
hotLinkCount
public:
unsigned long hotLinkCount() const

Returns a count of the number of hot links.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
hotLinks
public:
IDDEClientConversation& hotLinks( IDDEClientHotLinkSet& hotLinkSet )

Adds all item and format pairs for which hot links have been established to the IDDEClientHotLinkSet passed in.
Note: Include the iddecset.hpp header file when you use this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Miscellaneous Implementation

The IDDEClientConversation object uses these members to provide portions of its implementation. Typically you do not need to override these members.


[view class]
endAllHotLinks

Called by the IDDEClientConversation::endHotLinks function to update hot link instance data when one or more hot links are ending. The first version of this overloaded member is called when all hot links on an item are ending. The other version, which accepts no arguments, is used when all hot links are ending.


Overload 1
protected:
virtual void endAllHotLinks(const char* item)

Exception

IInvalidParameter The item parameter has a zero length.
IAccessError The operating system's request to post the DDE message to the server application failed.
IInvalidRequest There are no active hot links for this item, or an endHotLinks request for this item is pending.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
protected:
virtual void endAllHotLinks()

Exception

IAccessError The operating system's request to post the DDE message to the server application failed.
IInvalidRequest There are no active hot links, or an endHotLinks request for all hot links is pending.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
findTransaction
protected:
virtual bool findTransaction( const IEvent& event, bool removeMatch = false )

Called by any of the handle members, such as IDDEClientConversation::handleAck and IDDEClientConversation::handleData, when it is suspected that the server is not sending acknowledgments when it should. If this member determines that the suspicion is correct, it simulates acknowledgments for the transactions that are waiting for these acknowledgments.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Transactions

Use these members to send transactions to the DDE server application. Most of them accept a string that identifies the format in which the data is rendered. The default is IDDE::textFormat, which specifies text format. Formats are standardized by various vendors, who describe them in their operating system or application documentation.


[view class]
beginHotLink
public:
virtual IDDEClientConversation& beginHotLink( const char* item, IDDE::Format format = IDDE::textFormat, bool sendData = true, bool pacing = false )

Requests the server to send a notification every time the value of the item changes. If the sendData argument is true, the data is sent with the notification in the requested format. If the pacing argument is true, the server is asked to wait for an acknowledgment from the client before sending a subsequent notification.

This function accepts a format string that identifies the format in which the data is rendered. The default is IDDE::textFormat, which specifies the text format.

Formats are standardized by various vendors, who describe them in their operating system or application documentation.

Exception

IInvalidRequest The object is not in conversation with a server application, or a hot link for this item and format is already active or pending.
IInvalidParameter The item or format parameter is NULL or has a zero length.
IAccessError The operating system's request to post the DDE message to the server application failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Windows Considerations

Formats in Windows are numbers. If you register a private format, pass it to this function using the name of that format as a char*.


[view class]
endHotLink
public:
virtual IDDEClientConversation& endHotLink( const char* item, IDDE::Format format = IDDE::textFormat )

Requests the server to end a hot link on the specified item and format. This member accepts a format string that identifies the format in which the data is rendered. The default is IDDE::textFormat, which specifies the text format.

Formats are standardized by various vendors, who describe them in their operating system or application documentation.

Exception

IInvalidRequest The object is not in conversation with a server application, there is no hot link for this item and format, or an endHotLink request for this item and format is pending.
IInvalidParameter The item or format parameter is NULL or has a zero length.
IAccessError The operating system's request to post the DDE message to the server application failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Windows Considerations

Formats in Windows are numbers. If you register a private format, pass it to this function using the name of that format as a char*.


[view class]
endHotLinks
public:
virtual IDDEClientConversation& endHotLinks( const char* item = 0 )

Requests the server to end one or more hot links. If the item argument is specified, the server is requested to end all hot links on the item in all formats. If no arguments are provided, the server is requested to end all hot links on all items in all formats.

Exception

IInvalidRequest The object is not in conversation with a server application.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
executeCommands
public:
virtual IDDEClientConversation& executeCommands( const void* commands, unsigned long commandLength )

Requests the server to execute one or more commands. Each command string is NULL terminated. If there is more than one command the entire data item is NULL terminated as well.

Exception

IInvalidRequest The object is not in conversation with a server application.
IInvalidParameter The commands or commandLength parameter is NULL.
IAccessError The operating system request to post the DDE message to the server application failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
pokeData
public:
virtual IDDEClientConversation& pokeData( const char* item, const void* data, unsigned long dataLength, IDDE::Format format = IDDE::textFormat )

Requests the server to set the specified item to the value of the data provided. This function accepts a format string that identifies the format in which the data is rendered. The default is IDDE::textFormat, which specifies the text format.

Formats are standardized by various vendors, who describe them in their operating system or application documentation.

Exception

IInvalidRequest The object is not in conversation with a server application.
IInvalidParameter Either the item, format, or data parameter is NULL, or the item or format parameter has a zero length.
IAccessError The operating system's request to post the DDE message to the server application failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Windows Considerations

Formats in Windows are numbers. If you register a private format, pass it to this function using the name of that format as a char*.


[view class]
requestData
public:
virtual IDDEClientConversation& requestData( const char* item, IDDE::Format format = IDDE::textFormat )

Requests the value of the item rendered in the specified format from the server. This function accepts a format string that identifies the format in which the data is rendered. The default is IDDE::textFormat, which specifies the text format.

Formats are standardized by various vendors, who describe them in their operating system or application documentation.

Exception

IInvalidRequest The object is not in conversation with a server application.
IInvalidParameter The item or format parameter is NULL or has a zero length.
IAccessError The operating system's request to post the DDE message to the server application failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Windows Considerations

Formats in Windows are numbers. If you register a private format, pass it to this function using the name of that format as a char*.


IDDEClientConversation - Inherited Member Functions and Data

Inherited Public Functions

IHandler

Inherited Public Data

Inherited Protected Functions

IHandler

Inherited Protected Data