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         The advantage of deriving your own connection class is that it will
 252         enable you to intercept messages initiated by the server, such
 253         as wxDDEConnection::OnAdvise. You may also want to
 254         store application-specific data in instances of the new class.
 255     */
 256     wxConnectionBase* OnMakeConnection();
 257
 258     /**
 259         Returns @true if this is a valid host name, @false otherwise. This always
 260         returns @true under MS Windows.
 261     */
 262     bool ValidHost(const wxString& host);
 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     @seealso
 281     wxDDEClient, wxDDEConnection, @ref overview_ipcoverview "IPC overview"
 282 */
 283 class wxDDEServer
 284 {
 285 public:
 286     /**
 287         Constructs a server object.
 288     */
 289     wxDDEServer();
 290
 291     /**
 292         Registers the server using the given service name. Under UNIX, the
 293         string must contain an integer id which is used as an Internet port
 294         number. @false is returned if the call failed (for example, the port
 295         number is already in use).
 296     */
 297     bool Create(const wxString& service);
 298
 299     /**
 300         When a client calls @b MakeConnection, the server receives the
 301         message and this member is called. The application should derive a
 302         member to intercept this message and return a connection object of
 303         either the standard wxDDEConnection type, or of a user-derived type. If the
 304         topic is "STDIO'', the application may wish to refuse the connection.
 305         Under UNIX, when a server is created the OnAcceptConnection message is
 306         always sent for standard input and output, but in the context of DDE
 307         messages it doesn't make a lot of sense.
 308     */
 309     virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
 310 };
 311
 312
 313 // ============================================================================
 314 // Global functions/macros
 315 // ============================================================================
 316
 317 /**
 318     Called when wxWidgets exits, to clean up the DDE system. This no longer needs
 319     to be
 320     called by the application.
 321     See also wxDDEInitialize.
 322 */
 323 void wxDDECleanUp();
 324
 325 /**
 326     Initializes the DDE system. May be called multiple times without harm.
 327     This no longer needs to be called by the application: it will be called
 328     by wxWidgets if necessary.
 329     See also wxDDEServer, wxDDEClient, wxDDEConnection,
 330     wxDDECleanUp.
 331 */
 332 void wxDDEInitialize();
 333