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