### IDDETopicServer

  The IDDETopicServer class adds Dynamic Data Exchange (DDE) server function to an application.

  Create an object of this class for each topic you want to support in a DDE server application. The object manages all window, shared memory, and atom table processing.

  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.

### IDDETopicServer - Member Functions and Data by Group

### Constructors & Destructor

You can construct and destruct objects of this class.

~IDDETopicServer

      public:
      virtual ~IDDETopicServer()

  The destructor ends all conversations with all DDE client applications as part of its cleanup.

Supported Platforms

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

IDDETopicServer

      public:
      IDDETopicServer( const char* applicationName,
                       const char* supportedTopic,
                       IFrameWindow* owner = 0,
                       bool useEventThread = true )

  You can construct objects of this class in the following way; The constructor accepts the following two required arguments and two optional arguments:

  - The name of the application to which the topic server belongs (required).
  - The name of the topic that the topic server supports (required).
  - The third argument is optional but highly recommended if the application has a main frame window. IDDETopicServer creates an IFrameWindow object, which must be destructed for the application to end normally. Specifying this argument guarantees that this window is destructed when the main frame window is closed. The alternative is to ensure that all objects of IDDETopicServer are deleted before attempting to end the application.
  - The fourth argument is also optional but also highly recommended if the application must do any extensive processing or if it interacts with the user during any of the callback functions. Specifying true allows the IDDETopicServer object 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.

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

Exception

  IInvalidParameter | The applicationName or supportedTopic parameter is NULL or has a zero length.
  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

### Conversation Initiation and Termination

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

beginConversation

      public:
      virtual IDDETopicServer&
        beginConversation( const IWindowHandle& clientHandle )

  This is provided along with the IDDETopicServer::serverHandle member to allow a topic server to get into conversation with a client without engaging in the normal conversation initialization.

  This member sets the window handle associated with the client conversation. To initiate a conversation in this manner, the client and server application must have their own method for exchanging their window handles.

Exception

  IInvalidParameter | The client window handle is not valid.
  IInvalidRequest | A conversation with this client window is already active.

Supported Platforms

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

endConversation

      public:
      virtual IDDETopicServer&
        endConversation( unsigned long conversationId )

  Ends a conversation with a DDE client.

Exception

  IInvalidRequest | There is no active conversation identified by this ID.

Supported Platforms

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

### Event Dispatching

Event-dispatching members process events sent by DDE client applications. 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 IDDETopicServer version of the member or unpredictable results can occur and the conversation may not be able to process further events from the DDE client application. You may need to override one of these members if the client 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 IDDETopicServer object throws these invalid events away.

dispatchHandlerEvent

      protected:
      virtual bool dispatchHandlerEvent(IEvent& event)

  Calls the appropriate virtual member if a DDE topic server 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 client applications.

Supported Platforms

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

handleAdvise

      protected:
      virtual void handleAdvise(const IEvent& adviseEvent)

  Handles hot link requests from client applications.

Supported Platforms

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

handleExecute

      protected:
      virtual void handleExecute(const IEvent& executeEvent)

  Handles execute command requests from client applications.

Supported Platforms

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

handleInitiate

      protected:
      virtual void handleInitiate(const IEvent& initiateEvent)

  Handles conversation initialization requests from client applications.

Supported Platforms

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

handlePoke

      protected:
      virtual void handlePoke(const IEvent& pokeEvent)

  Handles data poke requests from client applications.

Supported Platforms

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

handleRequest

      protected:
      virtual void handleRequest(const IEvent& requestEvent)

  Handles data requests from client applications.

Supported Platforms

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

handleTerminate

      protected:
      virtual void handleTerminate(const IEvent& terminateEvent)

  Handles conversation termination requests from client applications.

Supported Platforms

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

handleUnadvise

      protected:
      virtual void handleUnadvise(const IEvent& unadviseEvent)

  Handles hot link end requests from client applications.

Supported Platforms

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

removeLink

      protected:
      virtual bool
        removeLink( IString item,
                    IString format,
                    unsigned long conversationId )

  Called by the IDDETopicServer::handleUnadvise function to update hot link information when a client ends a hot link.

Supported Platforms

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

### Event Processing

Event-processing members provide you with information when events, typically requests, are received from a DDE client application. To obtain the information provided by any of these virtual members and to support the requested transactions, derive from this class and override the members. All of the members, except for the IDDETopicServer::requestData member which is pure virtual, have default implementations so that you only need to override the functions that you want to support or use.

If you specify true for the useEventThread parameter of the IDDETopicServer constructor, all of these members except for IDDETopicServer::acceptConversation and, in some cases, IDDETopicServer::requestHotLinkData, are invoked on a secondary thread.

acceptConversation

      protected:
      virtual bool
        acceptConversation( unsigned long conversationId,
                            IDDEBeginEvent& event )

  Informs the server application that a client is asking to begin a conversation. The topic server calls this member if the application and topic match, ignoring mismatches due to different cases. The application should return promptly from this member because the request is sent, not posted, by the client application. Therefore, this member is always called in the main thread.

  Return true if the conversation is accepted. (The application can indicate it enforces case sensitivity by calling IDDEBeginEvent::setCaseSensitive.

  If the conversation request is rejected, return false so the topic server does not accept the conversation. The default behavior is to return true.

Supported Platforms

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

acknowledged

      protected:
      virtual void
        acknowledged( unsigned long conversationId,
                      IDDEServerAcknowledgeEvent& event )

  Informs the server application that a client has acknowledged the receipt of data or notification of changed hot link data. If true is specified for the useEventThread argument of the IDDETopicServer constructor, this member is called on a secondary thread.
  Note: The IDDETopicServer::hotLinkUpdate and IDDETopicServer::endConversation members must not be called from this member. Otherwise, a deadlock can occur.

Supported Platforms

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

beginHotLink

      protected:
      virtual bool
        beginHotLink( unsigned long conversationId,
                      IDDEServerHotLinkEvent& event )

  Informs the server application that a client is requesting a hot link on a particular item and format. If the application supports hot links for this item and format, return true so the topic server sends the client a positive acknowledgment. The IDDETopicServer::hotLinkUpdate member is provided for sending either data or a notification when the item's value changes.

  If the application does not support this hot link request, it should use any appropriate members of the IDDEServerHotLinkEvent object to indicate the reason and return false. This causes the topic server to send a negative acknowledgment to the client.

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

  The default behavior is to return false.

Supported Platforms

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

conversationEnded

      protected:
      virtual void
        conversationEnded( unsigned long conversationId,
                           IDDEEndEvent& event )

  Notifies the server application 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 DDE client.

  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

executeCommands

      protected:
      virtual bool
        executeCommands( unsigned long conversationId,
                         IDDEExecuteEvent& event )

  Informs the server application that a client is requesting the application to execute a string of one or more commands. If the application supports the request and successfully executes the commands, return true so the topic server sends the client a positive acknowledgment. If the application cannot honor this request, it should use any appropriate members of the IDDEExecuteEvent object to indicate the reason and return false. This causes the topic server to send a negative acknowledgment to the client. The default behavior is to return false.

  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

hotLinkEnded

      protected:
      virtual void
        hotLinkEnded( unsigned long conversationId,
                      IDDEEvent& event )

  Informs the server application that a client has ended one or more hot links. If the format is a 0-length string, all hot links on the specified item are ended. If the item is a 0-length string, all hot links with this client are ended.

  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

pokeData

      protected:
      virtual bool
        pokeData( unsigned long conversationId,
                  IDDEPokeEvent& event )

  Informs the server application that a client is requesting it to set an item to the new value provided by the client. If the application is able to honor the request, return true so the topic server sends the client a positive acknowledgment. If the application is unable to honor the request, it should use any appropriate members of the IDDEPokeEvent object to indicate the reason and return false. This causes the topic server to send a negative acknowledgment to the client. The default behavior is to return false.

  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

requestData

      protected:
      virtual bool
        requestData( unsigned long conversationId,
                     IDDERequestDataEvent& event ) = 0

  Informs the server application that a client is requesting data for an item in a specified format. If the request is for an item and format that the application supports, it should provide the data using the IDDERequestDataEvent::setData member and return true. The application can also request an acknowledgment from the client when it has received the data using the IDDERequestDataEvent::requestAck function.

  If the application cannot provide the data, it can indicate one of several reasons using the appropriate members of IDDERequestDataEvent and return false. This causes the topic server to send the client a negative acknowledgment. This function is pure virtual and must be overridden.

  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

requestHotLinkData

      protected:
      virtual void
        requestHotLinkData( IDDERequestDataEvent& event )

  Informs the server application that data is required for an item in a specified format. This member is called once for each format that has an active hot link that requires data when the server calls the IDDETopicServer::hotLinkUpdate member for an item. The server calls the hotLinkUpdate member when an item with active hot links changes.

  There is no need for this member to call the IDDERequestDataEvent::requestAck member because the topic server does this automatically for all hot links that have pacing active. (The server can request an acknowledgment even if pacing is not active.) For hot links that have pacing active and an outstanding acknowledgment, the update is not sent.

  When the acknowledgment is received, the topic server requests the latest update if the data has changed while the acknowledgment was outstanding. In these cases, if true is specified for the useEventThread argument of the IDDETopicServer constructor, this member is called on a secondary thread; otherwise, it is called in the main thread.
  Note: The IDDETopicServer::hotLinkUpdate and IDDETopicServer::endConversation members must not be called from this member. Otherwise, a deadlock can occur.

Supported Platforms

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

### Hot Link Updates

Use these members to initiate the sending of hot link updates to DDE client applications.

hotLinkUpdate

      public:
      unsigned long hotLinkUpdate(const char* item)

  Sends either data or a change notification for items whose data has changed to all clients who have an active hot link for this item. IDDETopicServer::requestHotLinkData is called for each format that has an active hot link and requires data. The number of hot links for which data or a notification is sent is returned to the caller.

  If there is an outstanding acknowledgment for a hot link, the notification is not sent to the client to which the hot link belongs. When the acknowledgment is satisfied, a notification is sent to the client with the most current data if it is a data hot link.

Exception

  IInvalidParameter | The item parameter is NULL or has a zero length.
  IAccessError | The operating system's request to post the DDE message to a client application failed.
  IInvalidRequest | There is no active hot link for this item and format.

Supported Platforms

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

### Server Information

Use these members to query information about the attributes of objects of this class.

application

      public:
      IString application() const

  Returns the name of the server application.

Supported Platforms

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

conversationCount

      public:
      unsigned long conversationCount() const

  Returns the number of conversations in which the topic server is currently engaged.

Supported Platforms

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

hotLinkCount

      public:
      unsigned long hotLinkCount() const

  Returns the number of hot links in which the topic server is currently engaged.

Supported Platforms

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

serverHandle

      public:
      IWindowHandle serverHandle() const

  Returns the window handle of the topic server. This is provided along with the IDDETopicServer::beginConversation member to allow a topic server to get in conversation with a client without engaging in the normal conversation initialization. Only a client is normally allowed to initiate a conversation.

Supported Platforms

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

topic

      public:
      IString topic() const

  Returns the name of the supported topic.

Supported Platforms

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

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