interface/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     @wxheader{ipc.h}
  12
  13     A wxConnection object represents the connection between a client
  14     and a server. It is created by making a connection using a
  15     wxClient object, or by the acceptance of a
  16     connection by a wxServer object. The
  17     bulk of a DDE-like (Dynamic Data Exchange) conversation is
  18     controlled by calling members in a @b wxConnection object or
  19     by overriding its members. The actual DDE-based implementation
  20     using wxDDEConnection is available on Windows only, but a
  21     platform-independent, socket-based version of this API is
  22     available using wxTCPConnection, which has the same API.
  23
  24     An application should normally derive a new connection class from
  25     wxConnection, in order to override the communication event
  26     handlers to do something interesting.
  27
  28     @library{wxbase}
  29     @category{FIXME}
  30
  31     @see wxClient, wxServer, @ref overview_ipcoverview "Interprocess communications
  32     overview"
  33 */
  34 class wxConnection : public wxObject
  35 {
  36 public:
  37     //@{
  38     /**
  39         Constructs a connection object. If no user-defined connection
  40         object is to be derived from wxConnection, then the constructor
  41         should not be called directly, since the default connection
  42         object will be provided on requesting (or accepting) a
  43         connection. However, if the user defines his or her own derived
  44         connection object, the wxServer::OnAcceptConnection
  45         and/or wxClient::OnMakeConnection
  46         members should be replaced by functions which construct the new
  47         connection object.
  48         If the arguments of the wxConnection constructor are void then
  49         the wxConnection object manages its own connection buffer,
  50         allocating memory as needed. A programmer-supplied buffer cannot
  51         be increased if necessary, and the program will assert if it is
  52         not large enough. The programmer-supplied buffer is included
  53         mainly for backwards compatibility.
  54     */
  55     wxConnection();
  56     wxConnection(void* buffer, size_t size);
  57     //@}
  58
  59     //@{
  60     /**
  61         Called by the server application to advise the client of a change
  62         in the data associated with the given item. Causes the client
  63         connection's OnAdvise() member
  64         to be called. Returns @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()
  76         message to be sent to the corresponding connection object in the
  77         other program. Returns @true if successful or already disconnected.
  78         The application that calls @b 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
  86         server. Can also be used to transfer arbitrary data to the server
  87         (similar to Poke() in
  88         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
 100         it of a change in the data associated with the given item, using
 101         Advise().
 102     */
 103     virtual bool OnAdvise(const wxString& topic,
 104                           const wxString& item,
 105                           const void* data,
 106                           size_t size,
 107                           wxIPCFormat format);
 108
 109     /**
 110         Message sent to the client or server application when the other
 111         application notifies it to end the connection. The default
 112         behaviour is to delete the connection object and return @true, so
 113         applications should generally override @b OnDisconnect
 114         (finally calling the inherited method as well) so that they know
 115         the connection object is 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         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
 137         Request(). The
 138         server's OnRequest() method
 139         should respond by returning a character string, or @NULL to
 140         indicate no data, and setting *size. The character string must of
 141         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. The
 151         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. The
 159         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. Causes the
 169         server connection's OnPoke() member to
 170         be called. If size is -1 the size is computed from the string
 171         length of data.
 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()
 184         member to be called. Size may be @NULL or a pointer to a variable
 185         to receive the size of the requested item.
 186         Returns a character string (actually a pointer to the
 187         connection's buffer) if successful, @NULL otherwise. This buffer
 188         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
 195         started with the server. Causes the server connection's
 196         OnStartAdvise()
 197         member to be called. Returns @true if the server okays it, @false
 198         otherwise.
 199     */
 200     bool StartAdvise(const wxString& item);
 201
 202     /**
 203         Called by the client application to ask if an advise loop can be
 204         stopped. Causes the server connection's OnStopAdvise()
 205         member to be called. Returns @true if the server okays it, @false
 206         otherwise.
 207     */
 208     bool StopAdvise(const wxString& item);
 209 };
 210
 211
 212
 213 /**
 214     @class wxClient
 215     @wxheader{ipc.h}
 216
 217     A wxClient object represents the client part of a client-server
 218     DDE-like (Dynamic Data Exchange) conversation. The actual
 219     DDE-based implementation using wxDDEClient is available on Windows
 220     only, but a platform-independent, socket-based version of this
 221     API is available using wxTCPClient, which has the same API.
 222
 223     To create a client which can communicate with a suitable server,
 224     you need to derive a class from wxConnection and another from
 225     wxClient. The custom wxConnection class will intercept
 226     communications in a 'conversation' with a server, and the custom
 227     wxClient is required so that a user-overridden
 228     wxClient::OnMakeConnection
 229     member can return a wxConnection of the required class, when a
 230     connection is made. Look at the IPC sample and the
 231     @ref overview_ipcoverview "Interprocess communications overview" for
 232     an example of how to do this.
 233
 234     @library{wxbase}
 235     @category{FIXME}
 236
 237     @see wxServer, wxConnection, @ref overview_ipcoverview "Interprocess
 238     communications overview"
 239 */
 240 class wxClient : public wxObject
 241 {
 242 public:
 243     /**
 244         Constructs a client object.
 245     */
 246     wxClient();
 247
 248     /**
 249         Tries to make a connection with a server by host (machine name
 250         under UNIX - use 'localhost' for same machine; ignored when using
 251         native DDE in Windows), service name and topic string. If the
 252         server allows a connection, a wxConnection object will be
 253         returned. The type of wxConnection returned can be altered by
 254         overriding the
 255         OnMakeConnection()
 256         member to return your own derived connection object.
 257         Under Unix, the service name may be either an integer port
 258         identifier in which case an Internet domain socket will be used
 259         for the communications, or a valid file name (which shouldn't
 260         exist and will be deleted afterwards) in which case a Unix domain
 261         socket is created.
 262         @b SECURITY NOTE: Using Internet domain sockets if extremely
 263         insecure for IPC as there is absolutely no access control for
 264         them, use Unix domain sockets whenever possible!
 265     */
 266     wxConnectionBase* MakeConnection(const wxString& host,
 267                                      const wxString& service,
 268                                      const wxString& topic);
 269
 270     /**
 271         Called by MakeConnection(), by
 272         default this simply returns a new wxConnection object. Override
 273         this method to return a wxConnection descendant customised for the
 274         application.
 275         The advantage of deriving your own connection class is that it
 276         will enable you to intercept messages initiated by the server,
 277         such as wxConnection::OnAdvise. You
 278         may also want to store application-specific data in instances of
 279         the new class.
 280     */
 281     wxConnectionBase* OnMakeConnection();
 282
 283     /**
 284         Returns @true if this is a valid host name, @false otherwise. This always
 285         returns @true under MS Windows.
 286     */
 287     bool ValidHost(const wxString& host);
 288 };
 289
 290
 291
 292 /**
 293     @class wxServer
 294     @wxheader{ipc.h}
 295
 296     A wxServer object represents the server part of a client-server
 297     DDE-like (Dynamic Data Exchange) conversation. The actual
 298     DDE-based implementation using wxDDEServer is available on Windows
 299     only, but a platform-independent, socket-based version of this
 300     API is available using wxTCPServer, which has the same API.
 301
 302     To create a server which can communicate with a suitable client,
 303     you need to derive a class from wxConnection and another from
 304     wxServer. The custom wxConnection class will intercept
 305     communications in a 'conversation' with a client, and the custom
 306     wxServer is required so that a user-overridden wxServer::OnAcceptConnection
 307     member can return a wxConnection of the required class, when a
 308     connection is made. Look at the IPC sample and the @ref overview_ipcoverview
 309     "Interprocess communications overview" for
 310     an example of how to do this.
 311
 312     @library{wxbase}
 313     @category{FIXME}
 314
 315     @see wxClient, wxConnection, IPC, overview()
 316 */
 317 class wxServer
 318 {
 319 public:
 320     /**
 321         Constructs a server object.
 322     */
 323     wxServer();
 324
 325     /**
 326         Registers the server using the given service name. Under Unix,
 327         the service name may be either an integer port identifier in
 328         which case an Internet domain socket will be used for the
 329         communications, or a valid file name (which shouldn't exist and
 330         will be deleted afterwards) in which case a Unix domain socket is
 331         created. @false is returned if the call failed (for example, the
 332         port number is already in use).
 333     */
 334     bool Create(const wxString& service);
 335
 336     /**
 337         When a client calls @b MakeConnection, the server receives the
 338         message and this member is called. The application should derive a
 339         member to intercept this message and return a connection object of
 340         either the standard wxConnection type, or (more likely) of a
 341         user-derived type.
 342         If the topic is @b STDIO, the application may wish to refuse the
 343         connection. Under UNIX, when a server is created the
 344         OnAcceptConnection message is always sent for standard input and
 345         output, but in the context of DDE messages it doesn't make a lot
 346         of sense.
 347     */
 348     virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
 349 };
 350