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