interface/wx/dde.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dde.h
   3 // Purpose:     interface of wxDDEConnection
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxDDEConnection
  10
  11     A wxDDEConnection object represents the connection between a client and a
  12     server. It can be created by making a connection using a wxDDEClient
  13     object, or by the acceptance of a connection by a wxDDEServer object.
  14     The bulk of a DDE (Dynamic Data Exchange) conversation is controlled by calling
  15     members in a wxDDEConnection object or by overriding its members.
  16
  17     An application should normally derive a new connection class from
  18     wxDDEConnection, in order to override the communication event handlers to
  19     do something interesting.
  20
  21     This DDE-based implementation is available on Windows only, but a
  22     platform-independent, socket-based version of this API is available using
  23     wxTCPConnection.
  24
  25     @library{wxbase}
  26     @category{ipc}
  27     @onlyfor{wxmsw}
  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     @onlyfor{wxmsw}
 226
 227     @see wxDDEServer, wxDDEConnection, @ref overview_ipc
 228 */
 229 class wxDDEClient : public wxObject
 230 {
 231 public:
 232     /**
 233         Constructs a client object.
 234     */
 235     wxDDEClient();
 236
 237     /**
 238         Tries to make a connection with a server specified by the host (machine
 239         name under UNIX, ignored under Windows), service name (must contain an
 240         integer port number under UNIX), and topic string. If the server allows
 241         a connection, a wxDDEConnection object will be returned.
 242
 243         The type of wxDDEConnection returned can be altered by overriding the
 244         OnMakeConnection() member to return your own derived connection object.
 245     */
 246     wxConnectionBase* MakeConnection(const wxString& host,
 247                                      const wxString& service,
 248                                      const wxString& topic);
 249
 250     /**
 251         The type of wxDDEConnection returned from a MakeConnection() call can
 252         be altered by deriving the OnMakeConnection() member to return your own
 253         derived connection object. By default, a wxDDEConnection object is
 254         returned.
 255
 256         The advantage of deriving your own connection class is that it will
 257         enable you to intercept messages initiated by the server, such as
 258         wxDDEConnection::OnAdvise(). You may also want to store
 259         application-specific data in instances of the new class.
 260     */
 261     wxConnectionBase* OnMakeConnection();
 262
 263     /**
 264         Returns @true if this is a valid host name, @false otherwise. This
 265         always returns @true under MS Windows.
 266     */
 267     bool ValidHost(const wxString& host);
 268 };
 269
 270
 271
 272 /**
 273     @class wxDDEServer
 274
 275     A wxDDEServer object represents the server part of a client-server DDE
 276     (Dynamic Data Exchange) conversation.
 277
 278     This DDE-based implementation is available on Windows only, but a
 279     platform-independent, socket-based version of this API is available using
 280     wxTCPServer.
 281
 282     @library{wxbase}
 283     @category{ipc}
 284     @onlyfor{wxmsw}
 285
 286     @see wxDDEClient, wxDDEConnection, @ref overview_ipc
 287 */
 288 class wxDDEServer
 289 {
 290 public:
 291     /**
 292         Constructs a server object.
 293     */
 294     wxDDEServer();
 295
 296     /**
 297         Registers the server using the given service name. Under UNIX, the
 298         string must contain an integer id which is used as an Internet port
 299         number. @false is returned if the call failed (for example, if the port
 300         number is already in use).
 301     */
 302     bool Create(const wxString& service);
 303
 304     /**
 305         When a client calls wxDDEClient::MakeConnection(), the server receives
 306         the message and this member is called. The application should derive a
 307         member to intercept this message and return a connection object of
 308         either the standard wxDDEConnection type, or of a user-derived type.
 309
 310         If the @a topic is "STDIO", the application may wish to refuse the
 311         connection. Under UNIX, when a server is created the
 312         OnAcceptConnection() message is always sent for standard input and
 313         output, but in the context of DDE messages it doesn't make a lot of
 314         sense.
 315     */
 316     virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
 317 };
 318
 319
 320
 321 // ============================================================================
 322 // Global functions/macros
 323 // ============================================================================
 324
 325 /** @addtogroup group_funcmacro_misc */
 326 //@{
 327
 328 /**
 329     Called when wxWidgets exits, to clean up the DDE system. This no longer
 330     needs to be called by the application.
 331
 332     @see wxDDEInitialize()
 333
 334     @header{wx/dde.h}
 335 */
 336 void wxDDECleanUp();
 337
 338 /**
 339     Initializes the DDE system. May be called multiple times without harm.
 340
 341     This no longer needs to be called by the application: it will be called by
 342     wxWidgets if necessary.
 343
 344     @see wxDDEServer, wxDDEClient, wxDDEConnection, wxDDECleanUp()
 345
 346     @header{wx/dde.h}
 347 */
 348 void wxDDEInitialize();
 349
 350 //@}
 351