interface/wx/sckipc.h

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