home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
cset21v1.zip
/
IBMCPP
/
IBMCLASS
/
IDDETSRV.HPP
< prev
next >
Wrap
C/C++ Source or Header
|
1993-10-22
|
27KB
|
438 lines
#ifndef _IDDETSRV_
#define _IDDETSRV_
/*******************************************************************************
* FILE NAME: iddetsrv.hpp *
* *
* DESCRIPTION: *
* Declaration of the class(es): *
* IDDETopicServer - Defines a DDE Server on a single topic. *
* *
* COPYRIGHT: *
* Licensed Materials - Property of IBM *
* (C) Copyright IBM Corporation 1992, 1993 *
* All Rights Reserved *
* US Government Users Restricted Rights - Use, duplication, or disclosure *
* restricted by GSA ADP Schedule Contract with IBM Corp. *
* *
*******************************************************************************/
#ifndef _ISTRING_
#include <istring.hpp>
#endif
#ifndef _IHANDLER_
#include <ihandler.hpp>
#endif
#ifndef _IHANDLE_
#include <ihandle.hpp>
#endif
#ifndef _IDDEEVT_
#include <iddeevt.hpp>
#endif
/*----------------------------------------------------------------------------*/
/* Align classes on four byte boundary. */
/*----------------------------------------------------------------------------*/
#pragma pack(4)
// Forward declarations for other classes:
class IObjectWindow;
class IFrameWindow;
class IThread;
class IDDEServerConversationSet;
class IDDEServerHotLinkItemSet;
class IDDEFormatSet;
class IDDETopicServer : protected IHandler {
typedef IHandler
Inherited;
/*******************************************************************************
* The IDDETopicServer class adds dynamic data exchange (DDE) server function *
* to an application. *
* *
* An instance of this class is created for each topic supported by a DDE *
* server application. All window, shared memory, and atom table processing is *
* managed by the class. *
* *
* This class uses a window to communicate. Therefore, window message *
* processing must occur. This means that ICurrentThread::processMsgs must *
* be invoked. There are several ways for this to occur. Normally, this is *
* accomplished by invoking IApplication::current().run(). *
* *
* NOTE: Applications using this class must be compiled with the multithreaded *
* library. *
* *
* Example: *
* *
* This example creates an IDDETopicServer subclass instance as required to *
* provide an implementation for the 'requestData()' callback function. *
* *
* class MyDDETopicServer : public IDDETopicServer { *
* public: *
* virtual Boolean *
* requestData ( unsigned long conversationId, *
* IDDERequestDataEvent& event) *
* { *
* IString item = event.item(); *
* IString format = event.format(); *
* IString myData = itemData(item, format); // some function to *
* if (myData.size()) // retrieve the data for *
* { // this item and format *
* event.setData(myData); *
* return true; *
* } *
* return false; // return false if unable to provide data *
* } *
* }; // MyDDETopicServer *
* *
* myTopicServer = new MyDDETopicServer( "Quote Server", *
* "Famous Quotes"); *
* *
*******************************************************************************/
public:
/*------------------------- Constructor ----------------------------------------
| There is one way to construct instances of this class. The constructor
| takes two required arguments and two optional arguments:
| |
| - The name of the application the topic server belongs to |
|
| - The name of the topic the topic server supports |
|
| - The third argument is optional, but highly recommended if the
| application has a main frame window. IDDETopicServer creates an
| instance of IFrameWindow, which must be destructed in order 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 instances of IDDETopicServer
| are deleted prior to attempting to end the application. |
|
| - The fourth argument is optional, but also highly recommended if the |
| application must do any extensive processing, or intends to interact
| with the end user during any of the callback functions. Specifying
| true allows IDDETopicServer to create a secondary thread to process
| incoming events. This prevents problems with window message
| processing since the thread is created without a message queue. If
| false is specified, no secondary thread will be created and care must
| be taken to return promptly from all callback functions. |
------------------------------------------------------------------------------*/
IDDETopicServer ( const char* applicationName,
const char* supportedTopic,
IFrameWindow* owner = 0,
Boolean useEventThread = true );
virtual
~IDDETopicServer ( );
/*------------------------------- Transactions ---------------------------------
| Use the following functions to communicate with client applications: |
| |
| beginConversation - This is provided along with the serverHandle |
| function to allow a topic server to get in |
| conversation with a client without engaging in the |
| normal conversation initialization. |
| |
| This function 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. |
| endConversation - Ends a conversation with a DDE client. |
| hotLinkUpdate - 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. |
| IDDEServer::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 acknowledgement for a hot |
| link, the notification will not be sent to the client |
| to which the hot link belongs. When the |
| acknowledgement is satisfied, a notification will be |
| sent to the client with the most current data if it |
| is a data hot link. |
------------------------------------------------------------------------------*/
virtual IDDETopicServer
&beginConversation ( const IWindowHandle& clientHandle ),
&endConversation ( unsigned long conversationId );
unsigned long
hotLinkUpdate ( const char* item );
/*-------------------------------- Callbacks -----------------------------------
| The following functions are called to notify the server of transactions |
| initiated by a client. If true is specified for the useEventThread |
| argument of the IDDETopicServer constructor, all of these callbacks except |
| for acceptConversation and in some cases requestHotLinkData will be invoked |
| on a secondary thread: |
| |
| requestData - Informs the server that a client is requesting data |
| for an item in a specified format. If the request |
| is for an item and format the application supports, |
| it should provide the data using the setData |
| function of the IDDERequestDataEvent instance and |
| return true. (The application can also request an |
| acknowledgement from the client when it has |
| received the data using the requestAck function of |
| IDDERequestDataEvent.) If the application cannot |
| provide the data, it can indicate one of several |
| reasons using the appropriate functions of |
| IDDERequestDataEvent and return false. This will |
| cause the topic server to send the client a negative |
| acknowledgement. This function is pure virtual and |
| must be overridden. |
| pokeData - Informs the server 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, it |
| should return true and the topic server will send |
| the client a positive acknowledgment. If the |
| application is unable to honor the request, it |
| should use any appropriate functions of the |
| IDDEPokeEvent instance to indicate the reason and |
| return false. This will cause the topic server to |
| send a negative acknowledgment to the client. The |
| default behavior is to return false. |
| beginHotLink - Informs the server 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, it should return true and the topic server |
| will send the client a positive acknowledgement. |
| The hotLinkUpdate function is provided in |
| IDDETopicServer 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 functions of |
| the IDDEServerHotLinkEvent instance to indicate |
| the reason and return false. This will cause the |
| topic server to send a negative acknowledgement to |
| the client. The default behavior is to return |
| false. |
| executeCommands - Informs the server 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, it should |
| return true and the topic server will send the |
| client a positive acknowledgement. If the |
| application cannot honor this request, it should use |
| any appropriate functions of the IDDEExecuteEvent |
| instance to indicate the reason and return false. |
| This will cause the topic server to send a negative |
| acknowledgement to the client. The default behavior |
| is to return false. |
| acceptConversation - Informs the server that a client is asking to begin |
| a conversation. The topic server will call this |
| function if the application and topic match, |
| ignoring mismatches due to different cases. The |
| application should return promptly from this |
| function because the request is sent, not posted, |
| by the client application. Therefore, this |
| function will always be invoked in the main thread. |
| |
| The application should return true if the |
| conversation is accepted. (The application can |
| indicate it enforces case sensitivity by using the |
| setCaseSensitive function of the IDDEBeginEvent |
| instance.) If the conversation request is |
| rejected, the application should return false and |
| the topic server will not accept the conversation. |
| The default behavior is to return true. |
| requestHotLinkData - Informs the server that data is required for a |
| an item in a specified format. This function is |
| called once for each format that has an active hot |
| link that requires data when the server invokes |
| the hotLinkUpdate function for an item. The |
| server invokes the hotLinkUpdate function when an |
| item with active hot links changes. |
| |
| There is no need for this function to invoke the |
| requestAck function of IDDERequestDataEvent |
| because the topic server will do this |
| automatically for all hot links that have pacing |
| active. (The server can request an |
| acknowledgement even if pacing is not active.) |
| For hot links that have pacing active and an |
| outstanding acknowledgment, the update is not |
| sent. |
| |
| When the acknowledgement is received, the topic |
| server will request the latest update if the data |
| has changed while the acknowledgement was |
| outstanding. In these cases, if true is specified |
| for the useEventThread argument of the |
| IDDETopicServer constructor, this function will be |
| invoked on a secondary thread; otherwise, it is |
| invoked in the main thread. |
| NOTE: The hotLinkUpdate and endConversation |
| functions must not be invoked from this |
| function. Otherwise, a dead-lock can occur. |
| hotLinkEnded - Informs the server 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. |
| acknowledged - Informs the server that a client has acknowledged |
| the receipt of data or notification of changed hot |
| link data. |
| NOTE: The hotLinkUpdate and endConversation |
| functions must not be invoked from this |
| function. Otherwise, a dead-lock can occur. |
| conversationEnded - Notifies the server that the conversation is ending |
| or ended. The conversation end can be initiated by |
| either the client or the server and can also be |
| caused by an error condition in the |
| IDDEClientConversation. |
------------------------------------------------------------------------------*/
virtual Boolean
requestData ( unsigned long conversationId,
IDDERequestDataEvent& event ) = 0,
pokeData ( unsigned long conversationId,
IDDEPokeEvent& event ),
beginHotLink ( unsigned long conversationId,
IDDEServerHotLinkEvent& event ),
executeCommands ( unsigned long conversationId,
IDDEExecuteEvent& event ),
acceptConversation ( unsigned long conversationId,
IDDEBeginEvent& event );
virtual void
requestHotLinkData ( IDDERequestDataEvent& event ),
hotLinkEnded ( unsigned long conversationId,
IDDEEvent& event ),
acknowledged ( unsigned long conversationId,
IDDEServerAcknowledgeEvent& event ),
conversationEnded ( unsigned long conversationId,
IDDEEndEvent& event );
/*-------------------------------- Accessors -----------------------------------
| Use the following functions to get the accessible attributes |
| of instances of this class: |
| |
| conversationCount - Returns the number of conversations in which the |
| topic server is currently engaged. |
| hotLinkCount - Returns the number of hot links in which the topic |
| server is currently engaged. |
| application - Returns the name of the server application. |
| topic - Returns the name of the supported topic. |
| serverHandle - Returns the window handle of the topic server. This |
| is provided along with the beginConversation |
| function 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. |
------------------------------------------------------------------------------*/
unsigned long
conversationCount ( ) const,
hotLinkCount ( ) const;
IString
application ( ) const,
topic ( ) const;
IWindowHandle
serverHandle ( ) const;
protected:
/*-------------------------------- Overrides -----------------------------------
| This class overrides the following inherited function, typically there is no |
| need for a subclass to override this function: |
| |
| dispatchHandlerEvent - This function is overridden to process |
| DDE specific messages sent to the topic server. |
------------------------------------------------------------------------------*/
virtual Boolean
dispatchHandlerEvent ( IEvent& event );
/*--------------------- Implementation Handler Functions -----------------------
| The dispatchHandlerEvent function calls the following functions to process |
| DDE-specific messages sent to the topic server. Typically, there is no |
| need to override these functions: |
| |
| handleAck - Handles acknowledgements from client applications. |
| handleAdvise - Handles beginHotLink requests from client applications. |
| handleExecute - Handles executeCommands requests from client |
| applications. |
| handleInitiate - Handles begin requests from client applications. |
| handlePoke - Handles pokeData requests from client applications. |
| handleRequest - Handles requestData requests from client applications. |
| handleTerminate - Handles end requests from client applications. |
| handleUnadvise - Handles hotLinkEnded requests from client applications. |
------------------------------------------------------------------------------*/
virtual void
handleAck ( const IEvent& ackEvent ),
handleAdvise ( const IEvent& adviseEvent ),
handleExecute ( const IEvent& executeEvent ),
handleInitiate ( const IEvent& initiateEvent ),
handlePoke ( const IEvent& pokeEvent ),
handleRequest ( const IEvent& requestEvent ),
handleTerminate ( const IEvent& terminateEvent ),
handleUnadvise ( const IEvent& unadviseEvent );
/*-------------------- Implementation Hot Link Function ------------------------
| The following function processes hot link activity. Typically, there is no |
| need to override this function: |
| |
| removeLink - Called by the handleUnadvise function to update hot link |
| information when a client ends a hot link. |
------------------------------------------------------------------------------*/
virtual Boolean
removeLink ( IString item,
IString format,
unsigned long conversationId );
private:
/*--------------------------------- PRIVATE ----------------------------------*/
IDDETopicServer ( const IDDETopicServer& aTopicServer );
IDDETopicServer&
operator=( const IDDETopicServer& aTopicServer );
IDDEServerHotLinkItemSet
&hotLinkItems ( ) const;
IDDEServerConversationSet
&closedConversations ( ) const,
&conversations ( ) const;
IDDEFormatSet
&formats ( ) const;
unsigned long
queueHandle ( ) const;
void
dispatchEventFromQueue ( );
void
*buildDDEStruct ( const char* itemName,
const char* dataFormat,
unsigned short status,
const void* xferData,
unsigned long dataLength );
unsigned long
ulClQHandle;
IThread
*pThreadCl;
Boolean
fClHdrActive,
fClPostMsgFail;
IWindowHandle
wndhClServer;
IObjectWindow
*pwndClServer;
IString
strClTopic,
strClApplication;
IDDEServerConversationSet
*pConvSetCl;
IDDEServerHotLinkItemSet
*pHLItemSetCl;
IDDEServerConversationSet
*pClsdConvSetCl;
IDDEFormatSet
*pFormatSetCl;
}; // IDDETopicServer
/*----------------------------------------------------------------------------*/
/* Resume compiler default packing. */
/*----------------------------------------------------------------------------*/
#pragma pack()
/*--------------------------------- INLINES ----------------------------------*/
#ifndef I_NO_INLINES
#include <iddetsrv.inl>
#endif
#endif /* _IDDETSRV_ */
