interface/sckipc.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        sckipc.h
   3 // Purpose:     interface of wxTCPServer
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxTCPServer
  11     @wxheader{sckipc.h}
  12
  13     A wxTCPServer object represents the server part of a client-server conversation.
  14     It emulates a DDE-style protocol, but uses TCP/IP which is available on most
  15     platforms.
  16
  17     A DDE-based implementation for Windows is available using wxDDEServer.
  18
  19     @library{wxnet}
  20     @category{FIXME}
  21
  22     @see wxTCPClient, wxTCPConnection, @ref overview_ipcoverview "IPC overview"
  23 */
  24 class wxTCPServer : public wxObject
  25 {
  26 public:
  27     /**
  28         Constructs a server object.
  29     */
  30     wxTCPServer();
  31
  32     /**
  33         Registers the server using the given service name. Under Unix, the
  34         string must contain an integer id which is used as an Internet port
  35         number. @false is returned if the call failed (for example, the port
  36         number is already in use).
  37     */
  38     bool Create(const wxString& service);
  39
  40     /**
  41         When a client calls @b MakeConnection, the server receives the
  42         message and this member is called. The application should derive a
  43         member to intercept this message and return a connection object of
  44         either the standard wxTCPConnection type, or of a user-derived type. If the
  45         topic is "STDIO'', the application may wish to refuse the connection.
  46         Under Unix, when a server is created the OnAcceptConnection message is
  47         always sent for standard input and output.
  48     */
  49     virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
  50 };
  51
  52
  53
  54 /**
  55     @class wxTCPClient
  56     @wxheader{sckipc.h}
  57
  58     A wxTCPClient object represents the client part of a client-server conversation.
  59     It emulates a DDE-style protocol, but uses TCP/IP which is available on most
  60     platforms.
  61
  62     A DDE-based implementation for Windows is available using wxDDEClient.
  63
  64     To create a client which can communicate with a suitable server,
  65     you need to derive a class from wxTCPConnection and another from wxTCPClient.
  66     The custom wxTCPConnection class will intercept communications in
  67     a 'conversation' with a server, and the custom wxTCPServer is required
  68     so that a user-overridden wxTCPClient::OnMakeConnection member can return
  69     a wxTCPConnection of the required class, when a connection is made.
  70
  71     @library{wxnet}
  72     @category{FIXME}
  73
  74     @see wxTCPServer, wxTCPConnection, @ref overview_ipcoverview "Interprocess
  75     communications overview"
  76 */
  77 class wxTCPClient : public wxObject
  78 {
  79 public:
  80     /**
  81         Constructs a client object.
  82     */
  83     wxTCPClient();
  84
  85     /**
  86         Tries to make a connection with a server specified by the host
  87         (a machine name under Unix), service name (must
  88         contain an integer port number under Unix), and a topic string. If the
  89         server allows a connection, a wxTCPConnection object will be returned.
  90         The type of wxTCPConnection returned can be altered by overriding
  91         the OnMakeConnection() member to return your own
  92         derived connection object.
  93     */
  94     wxConnectionBase* MakeConnection(const wxString& host,
  95                                      const wxString& service,
  96                                      const wxString& topic);
  97
  98     /**
  99         The type of wxTCPConnection returned from a MakeConnection() call can
 100         be altered by deriving the @b OnMakeConnection member to return your
 101         own derived connection object. By default, a wxTCPConnection
 102         object is returned.
 103         The advantage of deriving your own connection class is that it will
 104         enable you to intercept messages initiated by the server, such
 105         as wxTCPConnection::OnAdvise. You may also want to
 106         store application-specific data in instances of the new class.
 107     */
 108     wxConnectionBase* OnMakeConnection();
 109
 110     /**
 111         Returns @true if this is a valid host name, @false otherwise.
 112     */
 113     bool ValidHost(const wxString& host);
 114 };
 115
 116
 117
 118 /**
 119     @class wxTCPConnection
 120     @wxheader{sckipc.h}
 121
 122     A wxTCPClient object represents the connection between a client and a server.
 123     It emulates a DDE-style protocol, but uses TCP/IP which is available on most
 124     platforms.
 125
 126     A DDE-based implementation for Windows is available using wxDDEConnection.
 127
 128     A wxTCPConnection object can be created by making a connection using a
 129     wxTCPClient object, or by the acceptance of a connection by a
 130     wxTCPServer object. The bulk of a conversation is controlled by
 131     calling members in a @b wxTCPConnection object or by overriding its
 132     members.
 133
 134     An application should normally derive a new connection class from
 135     wxTCPConnection, in order to override the communication event handlers
 136     to do something interesting.
 137
 138     @library{wxnet}
 139     @category{FIXME}
 140
 141     @see wxTCPClient, wxTCPServer, @ref overview_ipcoverview "Interprocess
 142     communications overview"
 143 */
 144 class wxTCPConnection : public wxObject
 145 {
 146 public:
 147     //@{
 148     /**
 149         Constructs a connection object. If no user-defined connection object is
 150         to be derived from wxTCPConnection, then the constructor should not be
 151         called directly, since the default connection object will be provided on
 152         requesting (or accepting) a connection. However, if the user defines his
 153         or her own derived connection object, the wxTCPServer::OnAcceptConnection
 154         and/or wxTCPClient::OnMakeConnection members should be replaced by
 155         functions which construct the new connection object. If the arguments of
 156         the wxTCPConnection constructor are void, then a default buffer is
 157         associated with the connection. Otherwise, the programmer must provide a
 158         a buffer and size of the buffer for the connection object to use in
 159         transactions.
 160     */
 161     wxTCPConnection();
 162     wxTCPConnection(void* buffer, size_t size);
 163     //@}
 164
 165     //@{
 166     /**
 167         Called by the server application to advise the client of a change in
 168         the data associated with the given item. Causes the client
 169         connection's OnAdvise()
 170         member to be called. Returns @true if successful.
 171     */
 172     bool Advise(const wxString& item, const void* data, size_t size,
 173                 wxIPCFormat format = wxIPC_PRIVATE);
 174     bool Advise(const wxString& item, const char* data);
 175     bool Advise(const wxString& item, const wchar_t* data);
 176     bool Advise(const wxString& item, const wxString data);
 177     //@}
 178
 179     /**
 180         Called by the client or server application to disconnect from the other
 181         program; it causes the OnDisconnect() message
 182         to be sent to the corresponding connection object in the other
 183         program. The default behaviour of @b OnDisconnect is to delete the
 184         connection, but the calling application must explicitly delete its
 185         side of the connection having called @b Disconnect. Returns @true if
 186         successful.
 187     */
 188     bool Disconnect();
 189
 190     //@{
 191     /**
 192         Called by the client application to execute a command on the server. Can
 193         also be used to transfer arbitrary data to the server (similar
 194         to Poke() in that respect). Causes the
 195         server connection's OnExecute() member to be
 196         called. Returns @true if successful.
 197     */
 198     bool Execute(const void* data, size_t size,
 199                  wxIPCFormat format = wxIPC_PRIVATE);
 200     bool Execute(const char* data);
 201     bool Execute(const wchar_t* data);
 202     bool Execute(const wxString data);
 203     //@}
 204
 205     /**
 206         Message sent to the client application when the server notifies it of a
 207         change in the data associated with the given item.
 208     */
 209     virtual bool OnAdvise(const wxString& topic,
 210                           const wxString& item,
 211                           const void* data,
 212                           size_t size,
 213                           wxIPCFormat format);
 214
 215     /**
 216         Message sent to the client or server application when the other
 217         application notifies it to delete the connection. Default behaviour is
 218         to delete the connection object.
 219     */
 220     virtual bool OnDisconnect();
 221
 222     /**
 223         Message sent to the server application when the client notifies it to
 224         execute the given data. Note that there is no item associated with
 225         this message.
 226     */
 227     virtual bool OnExecute(const wxString& topic, const void* data,
 228                            size_t size,
 229                            wxIPCFormat format);
 230
 231     /**
 232         Message sent to the server application when the client notifies it to
 233         accept the given data.
 234     */
 235     virtual bool OnPoke(const wxString& topic, const wxString& item,
 236                         const void* data,
 237                         size_t size,
 238                         wxIPCFormat format);
 239
 240     /**
 241         Message sent to the server application when the client
 242         calls Request(). The server
 243         should respond by returning a character string from @b OnRequest,
 244         or @NULL to indicate no data.
 245     */
 246     virtual const void* OnRequest(const wxString& topic,
 247                                   const wxString& item,
 248                                   size_t* size,
 249                                   wxIPCFormat format);
 250
 251     /**
 252         Message sent to the server application by the client, when the client
 253         wishes to start an 'advise loop' for the given topic and item. The
 254         server can refuse to participate by returning @false.
 255     */
 256     virtual bool OnStartAdvise(const wxString& topic,
 257                                const wxString& item);
 258
 259     /**
 260         Message sent to the server application by the client, when the client
 261         wishes to stop an 'advise loop' for the given topic and item. The
 262         server can refuse to stop the advise loop by returning @false, although
 263         this doesn't have much meaning in practice.
 264     */
 265     virtual bool OnStopAdvise(const wxString& topic,
 266                               const wxString& item);
 267
 268     //@{
 269     /**
 270         Called by the client application to poke data into the server. Can be
 271         used to transfer arbitrary data to the server. Causes the server
 272         connection's OnPoke() member
 273         to be called. Returns @true if successful.
 274     */
 275     bool Poke(const wxString& item, const void* data, size_t size,
 276               wxIPCFormat format = wxIPC_PRIVATE);
 277     bool Poke(const wxString& item, const char* data);
 278     bool Poke(const wxString& item, const wchar_t* data);
 279     bool Poke(const wxString& item, const wxString data);
 280     //@}
 281
 282     /**
 283         Called by the client application to request data from the server. Causes
 284         the server connection's OnRequest() member to be called. Returns a
 285         character string (actually a pointer to the connection's buffer) if
 286         successful, @NULL otherwise.
 287     */
 288     const void* Request(const wxString& item, size_t* size,
 289                         wxIPCFormat format = wxIPC_TEXT);
 290
 291     /**
 292         Called by the client application to ask if an advise loop can be started
 293         with the server. Causes the server connection's OnStartAdvise()
 294         member to be called. Returns @true if the server okays it, @false
 295         otherwise.
 296     */
 297     bool StartAdvise(const wxString& item);
 298
 299     /**
 300         Called by the client application to ask if an advise loop can be
 301         stopped. Causes the server connection's OnStopAdvise() member
 302         to be called. Returns @true if the server okays it, @false otherwise.
 303     */
 304     bool StopAdvise(const wxString& item);
 305 };
 306