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