interface/wx/ipc.h

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