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