home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
cset21v1.zip
/
IBMCPP
/
IBMCLASS
/
IDDECCNV.HPP
< prev
next >
Wrap
C/C++ Source or Header
|
1993-10-22
|
27KB
|
450 lines
#ifndef _IDDECCNV_
#define _IDDECCNV_
/*******************************************************************************
* FILE NAME: iddeccnv.hpp *
* *
* DESCRIPTION: *
* Declaration of the class(es): *
* IDDEClientConversation - Defines a client DDE conversation. *
* *
* NOTE: IDDEActiveServer, IDDEActiveServerSet and IDDEClientHotLinkSet *
* are defined in iddecset.hpp. *
* *
* 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 _IHANDLE_
#include <ihandle.hpp>
#endif
#ifndef _IHANDLER_
#include <ihandler.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 IDDEClosedConversationSet;
class IDDETransactionQueue;
class IDDEActiveServerSet;
class IDDEClientHotLinkSet;
class IDDEFormatSet;
class IThread;
class IDDEClientConversation : protected IHandler {
typedef IHandler
Inherited;
/*******************************************************************************
* The IDDEClientConversation class adds dynamic data exchange (DDE) client *
* function to an application. *
* *
* An instance of this class is created for each conversation an application *
* initiates with a server. When a conversation with a server ends, the *
* IDDEClientConversation instance can initiate another conversation with that *
* server or any other server. An instance of this class can find all topics *
* supported by all DDE server applications on the system. 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 IDDEClientConversation subclass instance as *
* required to provide an implementation for the 'data()' callback function. *
* *
* class MyConversation : public IDDEClientConversation { *
* public: *
* virtual Boolean *
* data ( IDDEDataEvent& event ) *
* { *
* IString item = event.item(); *
* IString format = event.format(); *
* Boolean bVal = validate(item, format); // some function to *
* if (bVal) // ensure this is the *
* { // data we requested *
* IString myData = event.data(); *
* // do something with the requested data! *
* return true; *
* } *
* return false; // return false if data is not what *
* } // was expected... *
* }; // MyConversation *
* *
* MyConversation* myConversation = new MYConversation(); *
* if ( begin("Quote Server", // requested application *
* "Famous Quotes") ) // requested topic *
* myConversation->requestData("Albert Einstein"); // requested item *
* *
*******************************************************************************/
public:
/*------------------------ Constructors and Destructor -------------------------
| There are two ways to construct instances of this class. Both constructors |
| have an optional Boolean argument, useEventThread. This 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 IDDEClientConversation 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. |
| |
| Default constructor - This constructor initializes the instance, but does |
| not start a conversation. |
| |
| Alternate constructor - This constructor takes 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. |
------------------------------------------------------------------------------*/
IDDEClientConversation ( Boolean useEventThread = true );
IDDEClientConversation ( const char* applicationName,
const char* topicName,
Boolean useEventThread = true );
virtual
~IDDEClientConversation ( );
/*------------------------- Initiation/Termination -----------------------------
| Use the following functions to begin and end conversations: |
| |
| begin - Attempts to initiate a conversation with the requested server |
| application on the requested topic. The primary version of this |
| overloaded function takes 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 takes a server handle is provided along with the |
| clientHandle function to allow an instance of this class to |
| converse with a server without engaging in the normal conversation |
| initialization. |
| end - Ends the current conversation. |
------------------------------------------------------------------------------*/
virtual Boolean
begin ( const char* applicationName,
const char* topicName );
virtual IDDEClientConversation
&begin ( const IWindowHandle& serverHandle ),
&end ( );
/*------------------------------- Transactions ---------------------------------
| Use the following functions to initiate transactions with the server. Most |
| of the functions take a format string that identifies the format in which |
| the data is rendered. The default is "#1" which specifies text format. |
| Formats are standardized by various vendors, who describe them in their |
| operating system or application documentation. |
| |
| requestData - Requests the value of the item rendered in the specified |
| format from the server. |
| pokeData - Requests the server to set the specified item to the |
| value of the data provided. |
| beginHotLink - 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 acknowledgement from the |
| client before sending a subsequent notification. |
| endHotLink - Requests the server to end a hot link on the specified |
| item and format. |
| endHotLinks - 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. |
| executeCommands - Requests the server to execute one or more commands. |
------------------------------------------------------------------------------*/
virtual IDDEClientConversation
&requestData ( const char* item,
const char* format = "#1" ),
&pokeData ( const char* item,
const void* data,
unsigned long dataLength,
const char* format = "#1" ),
&beginHotLink ( const char* item,
const char* format = "#1",
Boolean sendData = true,
Boolean pacing = false ),
&endHotLink ( const char* item,
const char* format = "#1" ),
&endHotLinks ( const char* item = 0),
&executeCommands ( const void* commands,
unsigned long commandLength );
/*-------------------------------- Callbacks -----------------------------------
| The following functions are called to provide information to the |
| application whenever the server sends information to the client conversation.|
| To obtain information provided by any of the following functions, provide a |
| specialized implementation in the subclass. All of the functions except for |
| data have default behaviors, which is pure virtual and requires this |
| class to be subclassed. If true is specified for the useEventThread |
| argument of the IDDEClientConversation constructor, all of these callbacks |
| will be invoked on a secondary thread: |
| |
| data - Provides data sent from the server. The data can be |
| from an active hot link or as the result of the |
| requestData function being invoked. If the server |
| has requested an acknowledgement, the |
| IDDEClientConversation instance will use the return |
| value from this function to determine if it should |
| send a positive or negative acknowledgement. If the |
| data is for a valid item and in the correct format, |
| the function should return true; otherwise, false |
| should be returned. This function is pure virtual |
| and must be overridden. |
| hotLinkInform - Notifies the client that the value of an item in the |
| server for which the client has a hot link has |
| changed. If the server has requested an |
| acknowledgement, the IDDEClientConversation instance |
| will use the return value from this function to |
| determine if it should send a positive or negative |
| acknowledgement. If the client has an active hot |
| link for this item and has requested that only |
| notifications be sent, the function should return |
| true; otherwise, false should be returned. The |
| default behavior is to return true. |
| acknowledged - Provides generic acknowledgment from the server to |
| a client initiated transaction. A positive |
| acknowledgement can be sent in response to a |
| beginHotLink or endHotLink function. A negative |
| acknowledgement can be sent in response to the |
| same two functions, as well as to a requestData |
| function. |
| executeAcknowledged - Returns positive or negative acknowledgement from |
| the server as the result of the executeCommands |
| function being invoked. |
| pokeAcknowledged - Returns positive or negative acknowledgement from |
| the server as the result of the pokeData function |
| being invoked. |
| conversationEnded - Notifies the client 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
data ( IDDEDataEvent& event) = 0,
hotLinkInform ( IDDEClientHotLinkEvent& event);
virtual void
acknowledged ( IDDEClientAcknowledgeEvent& event ),
executeAcknowledged ( IDDEAcknowledgeExecuteEvent& event ),
pokeAcknowledged ( IDDEAcknowledgePokeEvent& event ),
conversationEnded ( IDDEClientEndEvent& event );
/*------------------------------- Accessors ------------------------------------
| Use the following functions to get the accessible attributes |
| of instances of this class: |
| |
| application - Returns the name of the server application |
| with which the client is conversing. |
| topic - Returns the name of the topic about which |
| the client is conversing. |
| isCaseSensitive - Returns true if the server has indicated it |
| enforces case sensitivity. |
| inConversation - Returns true if the client is currently in |
| conversation with a server; otherwise, it |
| returns false. |
| hotLinks - 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. |
| hotLinkCount - Returns a count of the number of hot links. |
| outstandingTransactionCount - Returns the number of transactions initiated |
| by the client to which the server has not |
| responded. |
| clientHandle - Returns the window handle of the client |
| conversation. This is provided, along with |
| the begin function, to allow an instance of |
| this class to converse with a server without |
| engaging in the normal conversation |
| initialization. |
------------------------------------------------------------------------------*/
IString
application ( ) const,
topic ( ) const;
Boolean
isCaseSensitive ( ) const,
inConversation ( ) const;
IDDEClientConversation
&hotLinks ( IDDEClientHotLinkSet& hotLinkSet );
unsigned long
hotLinkCount ( ) const,
outstandingTransactionCount ( ) const;
IWindowHandle
clientHandle ( ) const;
/*-------------------------------- Broadcasts ----------------------------------
| Use the following functions to get information from active DDE servers about |
| topics they support: |
| |
| NOTE: Include the iddecset.hpp header file when you use these functions. |
| |
| supportedTopics - Adds IDDEActiveServer instances 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. |
| supportingApplications - Adds IDDEActiveServer instances that represent |
| DDE server applications that support the |
| specified topic to the IDDEActiveServerSet passed |
| in as the first argument. |
|-----------------------------------------------------------------------------*/
virtual IDDEClientConversation
&supportedTopics ( IDDEActiveServerSet& activeServerSet,
const char* applicationName = 0 ),
&supportingApplications ( IDDEActiveServerSet& activeServerSet,
const char* topicName );
protected:
/*-------------------------------- Overrides -----------------------------------
| This class overrides the following inherited function, typically there is no |
| need for a subclass to override this function: |
| |
| dispatchHandlerEvent - Overridden to allow the processing of DDE-specific |
| messages that are sent to the client conversation. |
------------------------------------------------------------------------------*/
virtual Boolean
dispatchHandlerEvent ( IEvent& event );
/*--------------------- Implementation Handler Functions -----------------------
| The following functions are called by the 'dispatchHandlerEvent' function to |
| process DDE-specific messages that are sent to the client conversation. |
| Typically there is no need to override these functions: |
| |
| handleAck - Handles acknowledgements from server applications. |
| handleData - Handles data sent from server applications. |
| handleInitiateAck - Handles acknowledgements from server applications to |
| begin requests. |
| handleTerminate - Handles endConversation requests from server |
| applications. |
------------------------------------------------------------------------------*/
virtual void
handleAck ( const IEvent& ackEvent ),
handleData ( const IEvent& dataEvent ),
handleInitiateAck ( const IEvent& initiateAckEvent ),
handleTerminate ( const IEvent& terminateEvent );
/*------------------ Miscellaneous Implementation Functions --------------------
| The following functions perform specialized tasks that deal with instance |
| data. Typically there is no need to override these functions: |
| |
| endAllHotLinks - Called by the endHotLinks function to update hot link |
| instance data when one or more hot links are ending. |
| The first version of this overloaded function is called |
| when all hot links on an item are ending. The other |
| version, which takes no arguments, is used when all hot |
| links are ending. |
| findTransaction - Called by any of the handle functions, such as |
| handleAck and handleData, when it is suspected that |
| the server is not sending acknowledgements when it |
| should. If this function determines that the suspicion |
| is correct, it will simulate acknowledgements for the |
| transactions that are waiting for these |
| acknowledgements. |
------------------------------------------------------------------------------*/
virtual void
endAllHotLinks ( const char* item ),
endAllHotLinks ( );
virtual Boolean
findTransaction ( const IEvent& event,
Boolean removeMatch = false );
private:
/*--------------------------------- Private ----------------------------------*/
IDDEClientConversation ( const IDDEClientConversation& rhs);
IDDEClientConversation&
operator=(const IDDEClientConversation& rhs);
IWindowHandle
serverHandle ( ) const;
IDDEClientHotLinkSet
&hotLinksForUpdate ( ) const;
IDDEClosedConversationSet
&closedConversations ( ) const;
IDDETransactionQueue
&transactions ( ) 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;
IWindowHandle
wndhClServer,
wndhClClient;
IObjectWindow
*pwndClClient;
Boolean
fClBrdcstInPrgrs,
fClHdrActive,
fClPostMsgFail,
fClCaseSensitive;
IString
strClTopic,
strClApplication;
IDDEActiveServerSet
*pActServSetCl;
IDDEClosedConversationSet
*pClsdConvSetCl;
IDDEClientHotLinkSet
*pHLSetCl;
IDDETransactionQueue
*pTransQCl;
IDDEFormatSet
*pFormatSetCl;
}; // IDDEClientConversation
/*----------------------------------------------------------------------------*/
/* Resume compiler default packing. */
/*----------------------------------------------------------------------------*/
#pragma pack()
/*--------------------------------- Inlines ----------------------------------*/
#ifndef I_NO_INLINES
#include <iddeccnv.inl>
#endif
#endif /* _IDDECCNV_ */
