interface/sckipc.h

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