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

/////////////////////////////////////////////////////////////////////////////
// Name:        sckipc.h
// Purpose:     interface of wxTCPServer
// Author:      wxWidgets team
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////


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