[wxWidgets.git] / interface / wx / sckipc.h

/////////////////////////////////////////////////////////////////////////////
// Name:        sckipc.h
// Purpose:     interface of wxTCPServer
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////


/**
    See wxTCPConnection.
*/
enum wxIPCFormat
{
  wxIPC_INVALID =          0,
  wxIPC_TEXT =             1,  /* CF_TEXT */
  wxIPC_BITMAP =           2,  /* CF_BITMAP */
  wxIPC_METAFILE =         3,  /* CF_METAFILEPICT */
  wxIPC_SYLK =             4,
  wxIPC_DIF =              5,
  wxIPC_TIFF =             6,
  wxIPC_OEMTEXT =          7,  /* CF_OEMTEXT */
  wxIPC_DIB =              8,  /* CF_DIB */
  wxIPC_PALETTE =          9,
  wxIPC_PENDATA =          10,
  wxIPC_RIFF =             11,
  wxIPC_WAVE =             12,
  wxIPC_UTF16TEXT =        13, /* CF_UNICODE */
  wxIPC_ENHMETAFILE =      14,
  wxIPC_FILENAME =         15, /* CF_HDROP */
  wxIPC_LOCALE =           16,
  wxIPC_UTF8TEXT =         17,
  wxIPC_UTF32TEXT =        18,
  wxIPC_UNICODETEXT,
  wxIPC_PRIVATE =          20
};


/**
    @class wxTCPServer

    A wxTCPServer object represents the server part of a client-server conversation.
    It emulates a DDE-style protocol, but uses TCP/IP which is available on most
    platforms.

    A DDE-based implementation for Windows is available using wxDDEServer.

    @library{wxnet}
    @category{net}

    @see wxTCPClient, wxTCPConnection, @ref overview_ipc
*/
class wxTCPServer : public wxObject
{
public:
    /**
        Constructs a server object.
    */
    wxTCPServer();

    /**
        Registers the server using the given service name.

        Under Unix, the string must contain an integer id which is used as an
        Internet port number. @false is returned if the call failed
        (for example, the port number is already in use).
    */
    virtual bool Create(const wxString& service);

    /**
        When a client calls @b MakeConnection, the server receives the
        message and this member is called.

        The application should derive a member to intercept this message and
        return a connection object of either the standard wxTCPConnection type,
        or of a user-derived type.
        If the topic is "STDIO", the application may wish to refuse the connection.
        Under Unix, when a server is created the OnAcceptConnection message is
        always sent for standard input and output.
    */
    virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
};


/**
    @class wxTCPClient

    A wxTCPClient object represents the client part of a client-server conversation.
    It emulates a DDE-style protocol, but uses TCP/IP which is available on most
    platforms.

    A DDE-based implementation for Windows is available using wxDDEClient.

    To create a client which can communicate with a suitable server, you need
    to derive a class from wxTCPConnection and another from wxTCPClient.
    The custom wxTCPConnection class will intercept communications in
    a 'conversation' with a server, and the custom wxTCPServer is required
    so that a user-overridden wxTCPClient::OnMakeConnection() member can return
    a wxTCPConnection of the required class, when a connection is made.

    @library{wxnet}
    @category{net}

    @see wxTCPServer, wxTCPConnection, @ref overview_ipc
*/
class wxTCPClient : public wxObject
{
public:
    /**
        Constructs a client object.
    */
    wxTCPClient();

    /**
        Tries to make a connection with a server specified by the host
        (a machine name under Unix), service name (must contain an integer
        port number under Unix), and a topic string.

        If the server allows a connection, a wxTCPConnection object will be returned.

        The type of wxTCPConnection returned can be altered by overriding
        the OnMakeConnection() member to return your own derived connection object.
    */
    virtual wxConnectionBase* MakeConnection(const wxString& host,
                                             const wxString& service,
                                             const wxString& topic);

    /**
        The type of wxTCPConnection returned from a MakeConnection() call can
        be altered by deriving the @b OnMakeConnection member to return your
        own derived connection object. By default, a wxTCPConnection
        object is returned.

        The advantage of deriving your own connection class is that it will
        enable you to intercept messages initiated by the server, such
        as wxTCPConnection::OnAdvise(). You may also want to store
        application-specific data in instances of the new class.
    */
    virtual wxConnectionBase* OnMakeConnection();

    /**
        Returns @true if this is a valid host name, @false otherwise.
    */
    virtual bool ValidHost(const wxString& host);
};


/**
    @class wxTCPConnection

    A wxTCPClient object represents the connection between a client and a server.
    It emulates a DDE-style protocol, but uses TCP/IP which is available on most
    platforms.

    A DDE-based implementation for Windows is available using wxDDEConnection.

    A wxTCPConnection object can be created by making a connection using a
    wxTCPClient object, or by the acceptance of a connection by a wxTCPServer object.
    The bulk of a conversation is controlled by calling members in a
    @b wxTCPConnection object or by overriding its members.

    An application should normally derive a new connection class from
    wxTCPConnection, in order to override the communication event handlers
    to do something interesting.

    @library{wxnet}
    @category{net}

    @see wxTCPClient, wxTCPServer, @ref overview_ipc
*/
class wxTCPConnection : public wxObject
{
public:
    //@{
    /**
        Constructs a connection object.

        If no user-defined connection object is to be derived from wxTCPConnection,
        then the constructor should not be called directly, since the default
        connection object will be provided on requesting (or accepting) a connection.

        However, if the user defines his or her own derived connection object,
        the wxTCPServer::OnAcceptConnection and/or wxTCPClient::OnMakeConnection
        members should be replaced by functions which construct the new connection object.

        If the arguments of the wxTCPConnection constructor are void, then a default
        buffer is associated with the connection. Otherwise, the programmer must
        provide a buffer and size of the buffer for the connection object to use in
        transactions.
    */
    wxTCPConnection();
    wxTCPConnection(void* buffer, size_t size);
    //@}

    //@{
    /**
        Called by the server application to advise the client of a change in
        the data associated with the given item.

        Causes the client connection's OnAdvise() member to be called.

        Returns @true if successful.
    */
    bool Advise(const wxString& item, const void* data, size_t size,
                wxIPCFormat format = wxIPC_PRIVATE);
    bool Advise(const wxString& item, const char* data);
    bool Advise(const wxString& item, const wchar_t* data);
    bool Advise(const wxString& item, const wxString data);
    //@}

    /**
        Called by the client or server application to disconnect from the other
        program; it causes the OnDisconnect() message to be sent to the
        corresponding connection object in the other program.

        The default behaviour of @b OnDisconnect is to delete the
        connection, but the calling application must explicitly delete its
        side of the connection having called @b Disconnect.

        Returns @true if successful.
    */
    virtual bool Disconnect();

    //@{
    /**
        Called by the client application to execute a command on the server.
        Can also be used to transfer arbitrary data to the server (similar
        to Poke() in that respect). Causes the server connection's OnExecute()
        member to be called.

        Returns @true if successful.
    */
    bool Execute(const void* data, size_t size,
                 wxIPCFormat format = wxIPC_PRIVATE);
    bool Execute(const char* data);
    bool Execute(const wchar_t* data);
    bool Execute(const wxString data);
    //@}

    /**
        Message sent to the client application when the server notifies it of a
        change in the data associated with the given item.
    */
    virtual bool OnAdvise(const wxString& topic,
                          const wxString& item,
                          const void* data,
                          size_t size,
                          wxIPCFormat format);

    /**
        Message sent to the client or server application when the other
        application notifies it to delete the connection.
        Default behaviour is to delete the connection object.
    */
    virtual bool OnDisconnect();

    /**
        Message sent to the server application when the client notifies it to
        execute the given data.
        Note that there is no item associated with this message.
    */
    virtual bool OnExecute(const wxString& topic, const void* data,
                           size_t size,
                           wxIPCFormat format);

    /**
        Message sent to the server application when the client notifies it to
        accept the given data.
    */
    virtual bool OnPoke(const wxString& topic, const wxString& item,
                        const void* data,
                        size_t size,
                        wxIPCFormat format);

    /**
        Message sent to the server application when the client calls Request().

        The server should respond by returning a character string from @b OnRequest,
        or @NULL to indicate no data.
    */
    virtual const void* OnRequest(const wxString& topic,
                                  const wxString& item,
                                  size_t* size,
                                  wxIPCFormat format);

    /**
        Message sent to the server application by the client, when the client
        wishes to start an 'advise loop' for the given topic and item.
        The server can refuse to participate by returning @false.
    */
    virtual bool OnStartAdvise(const wxString& topic,
                               const wxString& item);

    /**
        Message sent to the server application by the client, when the client
        wishes to stop an 'advise loop' for the given topic and item.
        The server can refuse to stop the advise loop by returning @false, although
        this doesn't have much meaning in practice.
    */
    virtual bool OnStopAdvise(const wxString& topic,
                              const wxString& item);

    //@{
    /**
        Called by the client application to poke data into the server.
        Can be used to transfer arbitrary data to the server. Causes the server
        connection's OnPoke() member to be called. Returns @true if successful.
    */
    bool Poke(const wxString& item, const void* data, size_t size,
              wxIPCFormat format = wxIPC_PRIVATE);
    bool Poke(const wxString& item, const char* data);
    bool Poke(const wxString& item, const wchar_t* data);
    bool Poke(const wxString& item, const wxString data);
    //@}

    /**
        Called by the client application to request data from the server.
        Causes the server connection's OnRequest() member to be called.

        Returns a character string (actually a pointer to the connection's buffer) if
        successful, @NULL otherwise.
    */
    virtual const void* Request(const wxString& item, size_t* size = 0,
                        wxIPCFormat format = wxIPC_TEXT);

    /**
        Called by the client application to ask if an advise loop can be started
        with the server.

        Causes the server connection's OnStartAdvise() member to be called.
        Returns @true if the server okays it, @false otherwise.
    */
    virtual bool StartAdvise(const wxString& item);

    /**
        Called by the client application to ask if an advise loop can be stopped.
        Causes the server connection's OnStopAdvise() member to be called.
        Returns @true if the server okays it, @false otherwise.
    */
    virtual bool StopAdvise(const wxString& item);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
23324ae1 FM	2	// Name: sckipc.h
e54c96f1	3	// Purpose: interface of wxTCPServer
23324ae1 FM	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
4876436a FM	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,
9a6fda22	34	wxIPC_UNICODETEXT,
4876436a FM	35	wxIPC_PRIVATE = 20
	36	};
	37
	38
23324ae1 FM	39	/**
23324ae1 FM	40	@class wxTCPServer
7c913512	41
23324ae1 FM	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.
7c913512	45
23324ae1	46	A DDE-based implementation for Windows is available using wxDDEServer.
7c913512	47
23324ae1	48	@library{wxnet}
4876436a	49	@category{net}
7c913512	50
4876436a	51	@see wxTCPClient, wxTCPConnection, @ref overview_ipc
23324ae1 FM	52	*/
	53	class wxTCPServer : public wxObject
	54	{
	55	public:
	56	/**
	57	Constructs a server object.
	58	*/
	59	wxTCPServer();
	60
	61	/**
4876436a FM	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).
23324ae1	67	*/
adaaa686	68	virtual bool Create(const wxString& service);
23324ae1 FM	69
	70	/**
	71	When a client calls @b MakeConnection, the server receives the
4876436a FM	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.
23324ae1 FM	78	Under Unix, when a server is created the OnAcceptConnection message is
	79	always sent for standard input and output.
	80	*/
4cc4bfaf	81	virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
23324ae1 FM	82	};
	83
	84
e54c96f1	85
23324ae1 FM	86	/**
23324ae1 FM	87	@class wxTCPClient
7c913512	88
23324ae1 FM	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.
7c913512	92
23324ae1	93	A DDE-based implementation for Windows is available using wxDDEClient.
7c913512	94
4876436a FM	95	To create a client which can communicate with a suitable server, you need
4876436a FM	96	to derive a class from wxTCPConnection and another from wxTCPClient.
23324ae1 FM	97	The custom wxTCPConnection class will intercept communications in
23324ae1 FM	98	a 'conversation' with a server, and the custom wxTCPServer is required
4876436a	99	so that a user-overridden wxTCPClient::OnMakeConnection() member can return
23324ae1	100	a wxTCPConnection of the required class, when a connection is made.
7c913512	101
23324ae1	102	@library{wxnet}
4876436a	103	@category{net}
7c913512	104
4876436a	105	@see wxTCPServer, wxTCPConnection, @ref overview_ipc
23324ae1 FM	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
4876436a FM	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
23324ae1	122	The type of wxTCPConnection returned can be altered by overriding
4876436a	123	the OnMakeConnection() member to return your own derived connection object.
23324ae1	124	*/
adaaa686 FM	125	virtual wxConnectionBase* MakeConnection(const wxString& host,
	126	const wxString& service,
	127	const wxString& topic);
23324ae1 FM	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.
4876436a	134
23324ae1 FM	135	The advantage of deriving your own connection class is that it will
23324ae1 FM	136	enable you to intercept messages initiated by the server, such
4876436a FM	137	as wxTCPConnection::OnAdvise(). You may also want to store
4876436a FM	138	application-specific data in instances of the new class.
23324ae1	139	*/
adaaa686	140	virtual wxConnectionBase* OnMakeConnection();
23324ae1 FM	141
	142	/**
	143	Returns @true if this is a valid host name, @false otherwise.
	144	*/
adaaa686	145	virtual bool ValidHost(const wxString& host);
23324ae1 FM	146	};
	147
	148
e54c96f1	149
23324ae1 FM	150	/**
23324ae1 FM	151	@class wxTCPConnection
7c913512	152
23324ae1 FM	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.
7c913512	156
23324ae1	157	A DDE-based implementation for Windows is available using wxDDEConnection.
7c913512	158
23324ae1	159	A wxTCPConnection object can be created by making a connection using a
4876436a FM	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.
7c913512	163
23324ae1 FM	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.
7c913512	167
23324ae1	168	@library{wxnet}
4876436a	169	@category{net}
7c913512	170
4876436a	171	@see wxTCPClient, wxTCPServer, @ref overview_ipc
23324ae1 FM	172	*/
	173	class wxTCPConnection : public wxObject
	174	{
	175	public:
	176	//@{
	177	/**
4876436a FM	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
23324ae1 FM	191	transactions.
	192	*/
	193	wxTCPConnection();
7c913512	194	wxTCPConnection(void* buffer, size_t size);
23324ae1 FM	195	//@}
	196
	197	//@{
	198	/**
	199	Called by the server application to advise the client of a change in
4876436a FM	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.
23324ae1 FM	205	*/
	206	bool Advise(const wxString& item, const void* data, size_t size,
	207	wxIPCFormat format = wxIPC_PRIVATE);
7c913512 FM	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);
23324ae1 FM	211	//@}
	212
	213	/**
	214	Called by the client or server application to disconnect from the other
4876436a FM	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
23324ae1	219	connection, but the calling application must explicitly delete its
4876436a FM	220	side of the connection having called @b Disconnect.
	221
	222	Returns @true if successful.
23324ae1	223	*/
adaaa686	224	virtual bool Disconnect();
23324ae1 FM	225
	226	//@{
	227	/**
4876436a FM	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.
23324ae1 FM	234	*/
	235	bool Execute(const void* data, size_t size,
	236	wxIPCFormat format = wxIPC_PRIVATE);
7c913512 FM	237	bool Execute(const char* data);
	238	bool Execute(const wchar_t* data);
	239	bool Execute(const wxString data);
23324ae1 FM	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
4876436a FM	254	application notifies it to delete the connection.
4876436a FM	255	Default behaviour is to delete the connection object.
23324ae1 FM	256	*/
	257	virtual bool OnDisconnect();
	258
	259	/**
	260	Message sent to the server application when the client notifies it to
4876436a FM	261	execute the given data.
4876436a FM	262	Note that there is no item associated with this message.
23324ae1 FM	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	/**
4876436a FM	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,
23324ae1 FM	281	or @NULL to indicate no data.
	282	*/
	283	virtual const void* OnRequest(const wxString& topic,
	284	const wxString& item,
4cc4bfaf	285	size_t* size,
23324ae1 FM	286	wxIPCFormat format);
	287
	288	/**
	289	Message sent to the server application by the client, when the client
4876436a FM	290	wishes to start an 'advise loop' for the given topic and item.
4876436a FM	291	The server can refuse to participate by returning @false.
23324ae1 FM	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
4876436a FM	298	wishes to stop an 'advise loop' for the given topic and item.
4876436a FM	299	The server can refuse to stop the advise loop by returning @false, although
23324ae1 FM	300	this doesn't have much meaning in practice.
	301	*/
	302	virtual bool OnStopAdvise(const wxString& topic,
	303	const wxString& item);
	304
	305	//@{
	306	/**
4876436a FM	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.
23324ae1 FM	310	*/
	311	bool Poke(const wxString& item, const void* data, size_t size,
	312	wxIPCFormat format = wxIPC_PRIVATE);
7c913512 FM	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);
23324ae1 FM	316	//@}
	317
	318	/**
4876436a FM	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
23324ae1 FM	323	successful, @NULL otherwise.
23324ae1 FM	324	*/
5267aefd	325	virtual const void* Request(const wxString& item, size_t* size = 0,
23324ae1 FM	326	wxIPCFormat format = wxIPC_TEXT);
	327
	328	/**
	329	Called by the client application to ask if an advise loop can be started
4876436a FM	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.
23324ae1	334	*/
adaaa686	335	virtual bool StartAdvise(const wxString& item);
23324ae1 FM	336
23324ae1 FM	337	/**
4876436a FM	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.
23324ae1	341	*/
adaaa686	342	virtual bool StopAdvise(const wxString& item);
23324ae1	343	};
e54c96f1	344