interface/dde.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dde.h
   3 // Purpose:     interface of wxDDEConnection
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxDDEConnection
  11     @wxheader{dde.h}
  12
  13     A wxDDEConnection object represents the connection between a client and a
  14     server. It can be created by making a connection using a
  15     wxDDEClient object, or by the acceptance of a connection by a
  16     wxDDEServer object. The bulk of a DDE (Dynamic Data Exchange)
  17     conversation is controlled by
  18     calling members in a @b wxDDEConnection object or by overriding its
  19     members.
  20
  21     An application should normally derive a new connection class from
  22     wxDDEConnection, in order to override the communication event handlers
  23     to do something interesting.
  24
  25     This DDE-based implementation is available on Windows only,
  26     but a platform-independent, socket-based version
  27     of this API is available using wxTCPConnection.
  28
  29     @library{wxbase}
  30     @category{FIXME}
  31
  32     @see wxDDEClient, wxDDEServer, @ref overview_ipcoverview "Interprocess
  33     communications overview"
  34 */
  35 class wxDDEConnection : public wxObject
  36 {
  37 public:
  38     //@{
  39     /**
  40         Constructs a connection object. If no user-defined connection object is
  41         to be derived from wxDDEConnection, then the constructor should not be
  42         called directly, since the default connection object will be provided on
  43         requesting (or accepting) a connection. However, if the user defines his
  44         or her own derived connection object, the wxDDEServer::OnAcceptConnection
  45         and/or wxDDEClient::OnMakeConnection members should be replaced by
  46         functions which construct the new connection object. If the arguments of
  47         the wxDDEConnection constructor are void, then a default buffer is
  48         associated with the connection. Otherwise, the programmer must provide a
  49         a buffer and size of the buffer for the connection object to use in
  50         transactions.
  51     */
  52     wxDDEConnection();
  53     wxDDEConnection(void* buffer, size_t size);
  54     //@}
  55
  56     //@{
  57     /**
  58         Called by the server application to advise the client of a change in
  59         the data associated with the given item. Causes the client
  60         connection's OnAdvise()
  61         member to be called. Returns @true if successful.
  62     */
  63     bool Advise(const wxString& item, const void* data, size_t size,
  64                 wxIPCFormat format = wxIPC_PRIVATE);
  65     bool Advise(const wxString& item, const char* data);
  66     bool Advise(const wxString& item, const wchar_t* data);
  67     bool Advise(const wxString& item, const wxString data);
  68     //@}
  69
  70     /**
  71         Called by the client or server application to disconnect from the other
  72         program; it causes the OnDisconnect() message
  73         to be sent to the corresponding connection object in the other
  74         program. The default behaviour of @b OnDisconnect is to delete the
  75         connection, but the calling application must explicitly delete its
  76         side of the connection having called @b Disconnect. Returns @true if
  77         successful.
  78     */
  79     bool Disconnect();
  80
  81     //@{
  82     /**
  83         Called by the client application to execute a command on the server. Can
  84         also be used to transfer arbitrary data to the server (similar
  85         to Poke() in that respect). Causes the
  86         server connection's OnExecute() member to be
  87         called. Returns @true if successful.
  88     */
  89     bool Execute(const void* data, size_t size,
  90                  wxIPCFormat format = wxIPC_PRIVATE);
  91     bool Execute(const char* data);
  92     bool Execute(const wchar_t* data);
  93     bool Execute(const wxString data);
  94     //@}
  95
  96     /**
  97         Message sent to the client application when the server notifies it of a
  98         change in the data associated with the given item.
  99     */
 100     virtual bool OnAdvise(const wxString& topic,
 101                           const wxString& item,
 102                           const void* data,
 103                           size_t size,
 104                           wxIPCFormat format);
 105
 106     /**
 107         Message sent to the client or server application when the other
 108         application notifies it to delete the connection. Default behaviour is
 109         to delete the connection object.
 110     */
 111     virtual bool OnDisconnect();
 112
 113     /**
 114         Message sent to the server application when the client notifies it to
 115         execute the given data. Note that there is no item associated with
 116         this message.
 117     */
 118     virtual bool OnExecute(const wxString& topic, const void* data,
 119                            size_t size,
 120                            wxIPCFormat format);
 121
 122     /**
 123         Message sent to the server application when the client notifies it to
 124         accept the given data.
 125     */
 126     virtual bool OnPoke(const wxString& topic, const wxString& item,
 127                         const void* data,
 128                         size_t size,
 129                         wxIPCFormat format);
 130
 131     /**
 132         Message sent to the server application when the client
 133         calls Request(). The server
 134         should respond by returning a character string from @b OnRequest,
 135         or @NULL to indicate no data.
 136     */
 137     virtual const void* OnRequest(const wxString& topic,
 138                                   const wxString& item,
 139                                   size_t* size,
 140                                   wxIPCFormat format);
 141
 142     /**
 143         Message sent to the server application by the client, when the client
 144         wishes to start an 'advise loop' for the given topic and item. The
 145         server can refuse to participate by returning @false.
 146     */
 147     virtual bool OnStartAdvise(const wxString& topic,
 148                                const wxString& item);
 149
 150     /**
 151         Message sent to the server application by the client, when the client
 152         wishes to stop an 'advise loop' for the given topic and item. The
 153         server can refuse to stop the advise loop by returning @false, although
 154         this doesn't have much meaning in practice.
 155     */
 156     virtual bool OnStopAdvise(const wxString& topic,
 157                               const wxString& item);
 158
 159     //@{
 160     /**
 161         Called by the client application to poke data into the server. Can be
 162         used to transfer arbitrary data to the server. Causes the server
 163         connection's OnPoke() member
 164         to be called. Returns @true if successful.
 165     */
 166     bool Poke(const wxString& item, const void* data, size_t size,
 167               wxIPCFormat format = wxIPC_PRIVATE);
 168     bool Poke(const wxString& item, const char* data);
 169     bool Poke(const wxString& item, const wchar_t* data);
 170     bool Poke(const wxString& item, const wxString data);
 171     //@}
 172
 173     /**
 174         Called by the client application to request data from the server. Causes
 175         the server connection's OnRequest() member to be called. Returns a
 176         character string (actually a pointer to the connection's buffer) if
 177         successful, @NULL otherwise.
 178     */
 179     const void* Request(const wxString& item, size_t* size,
 180                         wxIPCFormat format = wxIPC_TEXT);
 181
 182     /**
 183         Called by the client application to ask if an advise loop can be started
 184         with the server. Causes the server connection's OnStartAdvise()
 185         member to be called. Returns @true if the server okays it, @false
 186         otherwise.
 187     */
 188     bool StartAdvise(const wxString& item);
 189
 190     /**
 191         Called by the client application to ask if an advise loop can be
 192         stopped. Causes the server connection's OnStopAdvise() member
 193         to be called. Returns @true if the server okays it, @false otherwise.
 194     */
 195     bool StopAdvise(const wxString& item);
 196 };
 197
 198
 199
 200 /**
 201     @class wxDDEClient
 202     @wxheader{dde.h}
 203
 204     A wxDDEClient object represents the client part of a client-server DDE
 205     (Dynamic Data Exchange) conversation.
 206
 207     To create a client which can communicate with a suitable server,
 208     you need to derive a class from wxDDEConnection and another from wxDDEClient.
 209     The custom wxDDEConnection class will intercept communications in
 210     a 'conversation' with a server, and the custom wxDDEServer is required
 211     so that a user-overridden wxDDEClient::OnMakeConnection member can return
 212     a wxDDEConnection of the required class, when a connection is made.
 213
 214     This DDE-based implementation is
 215     available on Windows only, but a platform-independent, socket-based version
 216     of this API is available using wxTCPClient.
 217
 218     @library{wxbase}
 219     @category{FIXME}
 220
 221     @see wxDDEServer, wxDDEConnection, @ref overview_ipcoverview "Interprocess
 222     communications overview"
 223 */
 224 class wxDDEClient : public wxObject
 225 {
 226 public:
 227     /**
 228         Constructs a client object.
 229     */
 230     wxDDEClient();
 231
 232     /**
 233         Tries to make a connection with a server specified by the host
 234         (machine name under UNIX, ignored under Windows), service name (must
 235         contain an integer port number under UNIX), and topic string. If the
 236         server allows a connection, a wxDDEConnection object will be returned.
 237         The type of wxDDEConnection returned can be altered by overriding
 238         the OnMakeConnection() member to return your own
 239         derived connection object.
 240     */
 241     wxConnectionBase* MakeConnection(const wxString& host,
 242                                      const wxString& service,
 243                                      const wxString& topic);
 244
 245     /**
 246         The type of wxDDEConnection returned from a MakeConnection() call can
 247         be altered by deriving the @b OnMakeConnection member to return your
 248         own derived connection object. By default, a wxDDEConnection
 249         object is returned.
 250         The advantage of deriving your own connection class is that it will
 251         enable you to intercept messages initiated by the server, such
 252         as wxDDEConnection::OnAdvise. You may also want to
 253         store application-specific data in instances of the new class.
 254     */
 255     wxConnectionBase* OnMakeConnection();
 256
 257     /**
 258         Returns @true if this is a valid host name, @false otherwise. This always
 259         returns @true under MS Windows.
 260     */
 261     bool ValidHost(const wxString& host);
 262 };
 263
 264
 265
 266 /**
 267     @class wxDDEServer
 268     @wxheader{dde.h}
 269
 270     A wxDDEServer object represents the server part of a client-server DDE
 271     (Dynamic Data Exchange) conversation.
 272
 273     This DDE-based implementation is
 274     available on Windows only, but a platform-independent, socket-based version
 275     of this API is available using wxTCPServer.
 276
 277     @library{wxbase}
 278     @category{FIXME}
 279
 280     @see wxDDEClient, wxDDEConnection, @ref overview_ipcoverview "IPC overview"
 281 */
 282 class wxDDEServer
 283 {
 284 public:
 285     /**
 286         Constructs a server object.
 287     */
 288     wxDDEServer();
 289
 290     /**
 291         Registers the server using the given service name. Under UNIX, the
 292         string must contain an integer id which is used as an Internet port
 293         number. @false is returned if the call failed (for example, the port
 294         number is already in use).
 295     */
 296     bool Create(const wxString& service);
 297
 298     /**
 299         When a client calls @b MakeConnection, the server receives the
 300         message and this member is called. The application should derive a
 301         member to intercept this message and return a connection object of
 302         either the standard wxDDEConnection type, or of a user-derived type. If the
 303         topic is "STDIO'', the application may wish to refuse the connection.
 304         Under UNIX, when a server is created the OnAcceptConnection message is
 305         always sent for standard input and output, but in the context of DDE
 306         messages it doesn't make a lot of sense.
 307     */
 308     virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
 309 };
 310
 311
 312
 313 // ============================================================================
 314 // Global functions/macros
 315 // ============================================================================
 316
 317 /** @ingroup group_funcmacro_misc */
 318 //@{
 319
 320 /**
 321     Called when wxWidgets exits, to clean up the DDE system. This no longer
 322     needs to be called by the application.
 323
 324     @see wxDDEInitialize()
 325
 326     @header{wx/dde.h}
 327 */
 328 void wxDDECleanUp();
 329
 330 /**
 331     Initializes the DDE system. May be called multiple times without harm.
 332
 333     This no longer needs to be called by the application: it will be called by
 334     wxWidgets if necessary.
 335
 336     @see wxDDEServer, wxDDEClient, wxDDEConnection, wxDDECleanUp()
 337
 338     @header{wx/dde.h}
 339 */
 340 void wxDDEInitialize();
 341
 342 //@}
 343