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