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().
DDE is not supported on AIX.
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.
![]() |
public:
virtual ~IDDEClientConversation()
The destructor ends the conversation with the DDE server application if there is one active.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
IOutOfSystemResource | The operating system's request for either an event semaphore or a queue failed. See the text of the exception for further information. |
Windows | OS/2 | AIX |
Yes | Yes | No |
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.
IOutOfSystemResource | The operating system's request for either an event semaphore or a queue failed. See the text of the exception for further information. |
Windows | OS/2 | AIX |
Yes | Yes | No |
Use these members to query information about the topics supported by the currently active DDE server applications.
![]() |
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:
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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:
IInvalidParameter | The topicName parameter is NULL. |
Windows | OS/2 | AIX |
Yes | Yes | No |
Use these members to obtain the attributes of this object, including information about the conversation if there is one currently active.
![]() |
public:
IString application() const
Returns the name of the server application with which the client is conversing.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
public:
bool inConversation() const
Returns true if the client is currently in conversation with a server; otherwise, it returns false.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
public:
bool isCaseSensitive() const
Returns true if the server has indicated it enforces case sensitivity; otherwise, it returns false.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
public:
unsigned long outstandingTransactionCount() const
Returns the number of transactions initiated by the client to which the server has not responded.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
public:
IString topic() const
Returns the name of the topic about which the client is conversing.
Windows | OS/2 | AIX |
Yes | Yes | No |
Use these members to begin and end conversations with DDE server applications.
![]() |
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.
public:
virtual IDDEClientConversation& begin( const IWindowHandle& serverHandle )
IInvalidParameter | The server window handle is not valid. |
IInvalidRequest | The object is already in conversation with another application. |
Windows | OS/2 | AIX |
Yes | Yes | No |
public:
virtual bool begin( const char* applicationName, const char* topicName )
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. |
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
public:
virtual IDDEClientConversation& end()
Ends the current conversation.
IInvalidRequest | The object is not in conversation with a server application. |
Windows | OS/2 | AIX |
Yes | Yes | No |
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.
![]() |
protected:
virtual bool dispatchHandlerEvent(IEvent& event)
Calls the appropriate virtual member if a DDE client conversation event is found.
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. |
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
protected:
virtual void handleAck(const IEvent& ackEvent)
Handles acknowledgments from server applications.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
protected:
virtual void handleData(const IEvent& dataEvent)
Handles data sent from server applications.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
protected:
virtual void handleInitiateAck( const IEvent& initiateAckEvent )
Handles acknowledgments from server applications to begin requests.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
protected:
virtual void handleTerminate(const IEvent& terminateEvent)
Handles termination requests from server applications.
Windows | OS/2 | AIX |
Yes | Yes | No |
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.
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
Use these members to obtain information about the hot links currently active in this object.
![]() |
public:
unsigned long hotLinkCount() const
Returns a count of the number of hot links.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
public:
IDDEClientConversation& hotLinks( IDDEClientHotLinkSet& hotLinkSet )
Adds all item and format pairs for which hot links have been established to
the IDDEClientHotLinkSet passed in.
Note:
Windows | OS/2 | AIX |
Yes | Yes | No |
The IDDEClientConversation object uses these members to provide portions of its implementation. Typically you do not need to override these members.
![]() |
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.
protected:
virtual void endAllHotLinks(const char* item)
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. |
Windows | OS/2 | AIX |
Yes | Yes | No |
protected:
virtual void endAllHotLinks()
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. |
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
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.
![]() |
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.
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. |
Windows | OS/2 | AIX |
Yes | Yes | No |
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*.
![]() |
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.
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. |
Windows | OS/2 | AIX |
Yes | Yes | No |
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*.
![]() |
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.
IInvalidRequest | The object is not in conversation with a server application. |
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
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. |
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
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. |
Windows | OS/2 | AIX |
Yes | Yes | No |
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*.
![]() |
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.
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. |
Windows | OS/2 | AIX |
Yes | Yes | No |
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*.
virtual ~IHandler()
virtual IString asDebugInfo() const
virtual IString asString() const
virtual IHandler& disable()
virtual IHandler& enable(bool enable = true)
virtual IHandler& handleEventsFor(IWindow* window)
IHandler()
bool isEnabled() const
virtual IHandler& stopHandlingEventsFor(IWindow* window)
virtual IEventResult defaultProcedure(IEvent& event)
virtual bool dispatchHandlerEvent(IEvent& event) = 0