interface/wx/ipc.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        ipc.h
   3 // Purpose:     interface of wxConnection
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxConnection
  11
  12     A wxConnection object represents the connection between a client and a server.
  13     It is created by making a connection using a wxClient object, or by the acceptance
  14     of a connection by a wxServer object.
  15
  16     The bulk of a DDE-like (Dynamic Data Exchange) conversation is controlled by
  17     calling members in a @b wxConnection object or by overriding its members.
  18     The actual DDE-based implementation using wxDDEConnection is available on
  19     Windows only, but a platform-independent, socket-based version of this API is
  20     available using wxTCPConnection, which has the same API.
  21
  22     An application should normally derive a new connection class from wxConnection,
  23     in order to override the communication event handlers to do something interesting.
  24
  25     @library{wxbase}
  26     @category{ipc}
  27
  28     @see wxClient, wxServer, @ref overview_ipc
  29 */
  30 class wxConnection : public wxObject
  31 {
  32 public:
  33     //@{
  34     /**
  35         Constructs a connection object.
  36
  37         If no user-defined connection object is to be derived from wxConnection,
  38         then the constructor should not be called directly, since the default connection
  39         object will be provided on requesting (or accepting) a connection.
  40
  41         However, if the user defines his or her own derived connection object,
  42         the wxServer::OnAcceptConnection and/or wxClient::OnMakeConnection
  43         members should be replaced by functions which construct the new
  44         connection object.
  45
  46         If the arguments of the wxConnection constructor are void then
  47         the wxConnection object manages its own connection buffer,
  48         allocating memory as needed. A programmer-supplied buffer cannot
  49         be increased if necessary, and the program will assert if it is
  50         not large enough.
  51
  52         The programmer-supplied buffer is included mainly for backwards compatibility.
  53     */
  54     wxConnection();
  55     wxConnection(void* buffer, size_t size);
  56     //@}
  57
  58     //@{
  59     /**
  60         Called by the server application to advise the client of a change
  61         in the data associated with the given item. Causes the client
  62         connection's OnAdvise() member to be called.
  63
  64         @return @true if successful.
  65     */
  66     bool Advise(const wxString& item, const void* data, size_t size,
  67                 wxIPCFormat format = wxIPC_PRIVATE);
  68     bool Advise(const wxString& item, const char* data);
  69     bool Advise(const wxString& item, const wchar_t* data);
  70     bool Advise(const wxString& item, const wxString data);
  71     //@}
  72
  73     /**
  74         Called by the client or server application to disconnect from the
  75         other program; it causes the OnDisconnect() message to be sent to the
  76         corresponding connection object in the other program.
  77
  78         Returns @true if successful or already disconnected.
  79         The application that calls Disconnect() must explicitly delete
  80         its side of the connection.
  81     */
  82     bool Disconnect();
  83
  84     //@{
  85     /**
  86         Called by the client application to execute a command on the server.
  87         Can also be used to transfer arbitrary data to the server (similar to
  88         Poke() in that respect). Causes the server connection's OnExec()
  89         member to be called. Returns @true if successful.
  90     */
  91     bool Execute(const void* data, size_t size,
  92                  wxIPCFormat format = wxIPC_PRIVATE);
  93     bool Execute(const char* data);
  94     bool Execute(const wchar_t* data);
  95     bool Execute(const wxString data);
  96     //@}
  97
  98     /**
  99         Message sent to the client application when the server notifies it of a
 100         change in the data associated with the given item, using Advise().
 101     */
 102     virtual bool OnAdvise(const wxString& topic,
 103                           const wxString& item,
 104                           const void* data,
 105                           size_t size,
 106                           wxIPCFormat format);
 107
 108     /**
 109         Message sent to the client or server application when the other
 110         application notifies it to end the connection.
 111
 112         The default behaviour is to delete the connection object and return @true,
 113         so applications should generally override OnDisconnect() (finally calling
 114         the inherited method as well) so that they know the connection object is
 115         no longer available.
 116     */
 117     virtual bool OnDisconnect();
 118
 119     /**
 120         Message sent to the server application when the client notifies
 121         it to execute the given data, using Execute().
 122
 123         Note that there is no item associated with this message.
 124     */
 125     virtual bool OnExec(const wxString& topic, const wxString& data);
 126
 127     /**
 128         Message sent to the server application when the client notifies it to
 129         accept the given data.
 130     */
 131     virtual bool OnPoke(const wxString& topic, const wxString& item,
 132                         const void* data,
 133                         size_t size,
 134                         wxIPCFormat format);
 135
 136     /**
 137         Message sent to the server application when the client calls Request().
 138         The server's OnRequest() method should respond by returning a character
 139         string, or @NULL to indicate no data, and setting *size.
 140
 141         The character string must of course persist after the call returns.
 142     */
 143     virtual const void* OnRequest(const wxString& topic,
 144                                   const wxString& item,
 145                                   size_t* size,
 146                                   wxIPCFormat format);
 147
 148     /**
 149         Message sent to the server application by the client, when the client
 150         wishes to start an 'advise loop' for the given topic and item.
 151         The server can refuse to participate by returning @false.
 152     */
 153     virtual bool OnStartAdvise(const wxString& topic,
 154                                const wxString& item);
 155
 156     /**
 157         Message sent to the server application by the client, when the client
 158         wishes to stop an 'advise loop' for the given topic and item.
 159         The server can refuse to stop the advise loop by returning @false, although
 160         this doesn't have much meaning in practice.
 161     */
 162     virtual bool OnStopAdvise(const wxString& topic,
 163                               const wxString& item);
 164
 165     //@{
 166     /**
 167         Called by the client application to poke data into the server.
 168         Can be used to transfer arbitrary data to the server.
 169         Causes the server connection's OnPoke() member to be called.
 170         If size is -1 the size is computed from the string length of data.
 171
 172         Returns @true if successful.
 173     */
 174     bool Poke(const wxString& item, const void* data, size_t size,
 175               wxIPCFormat format = wxIPC_PRIVATE);
 176     bool Poke(const wxString& item, const char* data);
 177     bool Poke(const wxString& item, const wchar_t* data);
 178     bool Poke(const wxString& item, const wxString data);
 179     //@}
 180
 181     /**
 182         Called by the client application to request data from the server.
 183         Causes the server connection's OnRequest() member to be called.
 184         Size may be @NULL or a pointer to a variable to receive the size of the
 185         requested item.
 186
 187         Returns a character string (actually a pointer to the connection's buffer)
 188         if successful, @NULL otherwise. This buffer does not need to be deleted.
 189     */
 190     const void* Request(const wxString& item, size_t* size,
 191                         wxIPCFormat format = wxIPC_TEXT);
 192
 193     /**
 194         Called by the client application to ask if an advise loop can be started
 195         with the server. Causes the server connection's OnStartAdvise()
 196         member to be called.
 197         Returns @true if the server okays it, @false otherwise.
 198     */
 199     bool StartAdvise(const wxString& item);
 200
 201     /**
 202         Called by the client application to ask if an advise loop can be stopped.
 203         Causes the server connection's OnStopAdvise() member to be called.
 204         Returns @true if the server okays it, @false otherwise.
 205     */
 206     bool StopAdvise(const wxString& item);
 207
 208     /**
 209         Returns true if the format is one of the text formats.
 210
 211         The text formats are wxIPC_TEXT, wxIPC_UNICODETEXT and wxIPC_UTF8TEXT.
 212      */
 213     static bool IsTextFormat(wxIPCFormat format);
 214
 215     /**
 216         Returns the data in any of the text formats as string.
 217
 218         @param data
 219             The raw data pointer as used with any of the other methods of this
 220             class.
 221         @param size
 222             The size of the data buffer pointed to by @a data.
 223         @param format
 224             The format of the data. It must be a text one, i.e. such that
 225             IsTextFormat() returns @true for it.
 226         @return
 227             The string representation of the data. If the format is not text,
 228             an assertion failure is triggered and empty string is returned.
 229      */
 230     static wxString
 231     GetTextFromData(const void *data, size_t size, wxIPCFormat format);
 232 };
 233
 234
 235
 236 /**
 237     @class wxClient
 238
 239     A wxClient object represents the client part of a client-server
 240     DDE-like (Dynamic Data Exchange) conversation.
 241     The actual DDE-based implementation using wxDDEClient is available on Windows
 242     only, but a platform-independent, socket-based version of this API is available
 243     using wxTCPClient, which has the same API.
 244
 245     To create a client which can communicate with a suitable server, you need to
 246     derive a class from wxConnection and another from wxClient.
 247     The custom wxConnection class will intercept communications in a 'conversation'
 248     with a server, and the custom wxClient is required so that a user-overridden
 249     wxClient::OnMakeConnection member can return a wxConnection of the required
 250     class, when a connection is made.
 251
 252     Look at the IPC sample and the @ref overview_ipc for an example of how to do this.
 253
 254     @library{wxbase}
 255     @category{ipc}
 256
 257     @see wxServer, wxConnection, @ref overview_ipc
 258 */
 259 class wxClient : public wxObject
 260 {
 261 public:
 262     /**
 263         Constructs a client object.
 264     */
 265     wxClient();
 266
 267     /**
 268         Tries to make a connection with a server by host (machine name
 269         under UNIX - use 'localhost' for same machine; ignored when using
 270         native DDE in Windows), service name and topic string.
 271
 272         If the server allows a connection, a wxConnection object will be returned.
 273         The type of wxConnection returned can be altered by overriding the
 274         OnMakeConnection() member to return your own derived connection object.
 275
 276         Under Unix, the service name may be either an integer port
 277         identifier in which case an Internet domain socket will be used
 278         for the communications, or a valid file name (which shouldn't
 279         exist and will be deleted afterwards) in which case a Unix domain
 280         socket is created.
 281
 282         @note Using Internet domain sockets if extremely insecure for IPC as
 283               there is absolutely no access control for them, use Unix domain
 284               sockets whenever possible!
 285     */
 286     wxConnectionBase* MakeConnection(const wxString& host,
 287                                      const wxString& service,
 288                                      const wxString& topic);
 289
 290     /**
 291         Called by MakeConnection(), by default this simply returns a new wxConnection
 292         object. Override this method to return a wxConnection descendant customised
 293         for the application.
 294
 295         The advantage of deriving your own connection class is that it will enable
 296         you to intercept messages initiated by the server, such as wxConnection::OnAdvise.
 297         You  may also want to store application-specific data in instances of
 298         the new class.
 299     */
 300     wxConnectionBase* OnMakeConnection();
 301
 302     /**
 303         Returns @true if this is a valid host name, @false otherwise.
 304         This always returns @true under MS Windows.
 305     */
 306     bool ValidHost(const wxString& host);
 307 };
 308
 309
 310
 311 /**
 312     @class wxServer
 313
 314     A wxServer object represents the server part of a client-server DDE-like
 315     (Dynamic Data Exchange) conversation. The actual DDE-based implementation
 316     using wxDDEServer is available on Windows only, but a platform-independent,
 317     socket-based version of this API is available using wxTCPServer, which has
 318     the same API.
 319
 320     To create a server which can communicate with a suitable client, you need to
 321     derive a class from wxConnection and another from wxServer.
 322     The custom wxConnection class will intercept communications in a 'conversation'
 323     with a client, and the custom wxServer is required so that a user-overridden
 324     wxServer::OnAcceptConnection member can return a wxConnection of the required
 325     class, when a connection is made.
 326     Look at the IPC sample and the @ref overview_ipc for an example of how to do this.
 327
 328     @library{wxbase}
 329     @category{ipc}
 330
 331     @see wxClient, wxConnection, IPC, @ref overview_ipc
 332 */
 333 class wxServer
 334 {
 335 public:
 336     /**
 337         Constructs a server object.
 338     */
 339     wxServer();
 340
 341     /**
 342         Registers the server using the given service name.
 343         Under Unix, the service name may be either an integer port identifier in
 344         which case an Internet domain socket will be used for the communications,
 345         or a valid file name (which shouldn't exist and will be deleted afterwards)
 346         in which case a Unix domain socket is created.
 347
 348         @false is returned if the call failed (for example, the port number is
 349         already in use).
 350     */
 351     bool Create(const wxString& service);
 352
 353     /**
 354         When a client calls @b MakeConnection, the server receives the
 355         message and this member is called. The application should derive a
 356         member to intercept this message and return a connection object of
 357         either the standard wxConnection type, or (more likely) of a
 358         user-derived type.
 359
 360         If the topic is @b STDIO, the application may wish to refuse the
 361         connection. Under UNIX, when a server is created the OnAcceptConnection()
 362         message is always sent for standard input and output, but in the context
 363         of DDE messages it doesn't make a lot of sense.
 364     */
 365     virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
 366 };
 367