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().
DDE is not supported on AIX.
You can construct and destruct objects of this class.
![]() |
public:
virtual ~IDDETopicServer()
The destructor ends all conversations with all DDE client applications as part of its cleanup.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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 parameter useEventThread is ignored on the Windows operating system. All functions are run on the primary thread.
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. |
Windows | OS/2 | AIX |
Yes | Yes | No |
Use these members to begin and end conversations with DDE client applications.
![]() |
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.
IInvalidParameter | The client window handle is not valid. |
IInvalidRequest | A conversation with this client window is already active. |
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
public:
virtual IDDETopicServer& endConversation( unsigned long conversationId )
Ends a conversation with a DDE client.
IInvalidRequest | There is no active conversation identified by this ID. |
Windows | OS/2 | AIX |
Yes | Yes | No |
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.
![]() |
protected:
virtual bool dispatchHandlerEvent(IEvent& event)
Calls the appropriate virtual member if a DDE topic server 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 client applications.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
protected:
virtual void handleAdvise(const IEvent& adviseEvent)
Handles hot link requests from client applications.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
protected:
virtual void handleExecute(const IEvent& executeEvent)
Handles execute command requests from client applications.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
protected:
virtual void handleInitiate(const IEvent& initiateEvent)
Handles conversation initialization requests from client applications.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
protected:
virtual void handlePoke(const IEvent& pokeEvent)
Handles data poke requests from client applications.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
protected:
virtual void handleRequest(const IEvent& requestEvent)
Handles data requests from client applications.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
protected:
virtual void handleTerminate(const IEvent& terminateEvent)
Handles conversation termination requests from client applications.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
protected:
virtual void handleUnadvise(const IEvent& unadviseEvent)
Handles hot link end requests from client applications.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
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.
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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:
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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:
Windows | OS/2 | AIX |
Yes | Yes | No |
Use these members to initiate the sending of hot link updates to DDE client applications.
![]() |
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.
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. |
Windows | OS/2 | AIX |
Yes | Yes | No |
Use these members to query information about the attributes of objects of this class.
![]() |
public:
IString application() const
Returns the name of the server application.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
public:
unsigned long conversationCount() const
Returns the number of conversations in which the topic server is currently engaged.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
public:
unsigned long hotLinkCount() const
Returns the number of hot links in which the topic server is currently engaged.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
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.
Windows | OS/2 | AIX |
Yes | Yes | No |
![]() |
public:
IString topic() const
Returns the name of the supported topic.
Windows | OS/2 | AIX |
Yes | Yes | No |
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