interface/dde.h

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