### 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.

~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

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 name of the server application with which a conversation is desired
  - The name of the topic about which a conversation is desired

  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.

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

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.

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

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

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

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

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

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.

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

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.

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

handleAck

      protected:
      virtual void handleAck(const IEvent& ackEvent)

  Handles acknowledgments from server applications.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

handleData

      protected:
      virtual void handleData(const IEvent& dataEvent)

  Handles data sent from server applications.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

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

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.

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

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

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

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

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

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.

hotLinkCount

      public:
      unsigned long hotLinkCount() const

  Returns a count of the number of hot links.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

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.

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

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.

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*.

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*.

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

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

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*.

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

  -     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)

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IHandler

  -     virtual IEventResult defaultProcedure(IEvent& event)

  -     virtual bool dispatchHandlerEvent(IEvent& event) = 0

#### Inherited Protected Data

  - None