[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,
#if SIZEOF_WCHAR_T == 2
  wxIPC_UNICODETEXT = wxIPC_UTF16TEXT,
#elif SIZEOF_WCHAR_T == 4
  wxIPC_UNICODETEXT = wxIPC_UTF32TEXT,
#else
#  error "Unknown wchar_t size"
#endif
  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,
	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
23324ae1 FM	45	/**
23324ae1 FM	46	@class wxTCPServer
7c913512	47
23324ae1 FM	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.
7c913512	51
23324ae1	52	A DDE-based implementation for Windows is available using wxDDEServer.
7c913512	53
23324ae1	54	@library{wxnet}
4876436a	55	@category{net}
7c913512	56
4876436a	57	@see wxTCPClient, wxTCPConnection, @ref overview_ipc
23324ae1 FM	58	*/
	59	class wxTCPServer : public wxObject
	60	{
	61	public:
	62	/**
	63	Constructs a server object.
	64	*/
	65	wxTCPServer();
	66
	67	/**
4876436a FM	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).
23324ae1	73	*/
adaaa686	74	virtual bool Create(const wxString& service);
23324ae1 FM	75
	76	/**
	77	When a client calls @b MakeConnection, the server receives the
4876436a FM	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.
23324ae1 FM	84	Under Unix, when a server is created the OnAcceptConnection message is
	85	always sent for standard input and output.
	86	*/
4cc4bfaf	87	virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
23324ae1 FM	88	};
	89
	90
e54c96f1	91
23324ae1 FM	92	/**
23324ae1 FM	93	@class wxTCPClient
7c913512	94
23324ae1 FM	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.
7c913512	98
23324ae1	99	A DDE-based implementation for Windows is available using wxDDEClient.
7c913512	100
4876436a FM	101	To create a client which can communicate with a suitable server, you need
4876436a FM	102	to derive a class from wxTCPConnection and another from wxTCPClient.
23324ae1 FM	103	The custom wxTCPConnection class will intercept communications in
23324ae1 FM	104	a 'conversation' with a server, and the custom wxTCPServer is required
4876436a	105	so that a user-overridden wxTCPClient::OnMakeConnection() member can return
23324ae1	106	a wxTCPConnection of the required class, when a connection is made.
7c913512	107
23324ae1	108	@library{wxnet}
4876436a	109	@category{net}
7c913512	110
4876436a	111	@see wxTCPServer, wxTCPConnection, @ref overview_ipc
23324ae1 FM	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
4876436a FM	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
23324ae1	128	The type of wxTCPConnection returned can be altered by overriding
4876436a	129	the OnMakeConnection() member to return your own derived connection object.
23324ae1	130	*/
adaaa686 FM	131	virtual wxConnectionBase* MakeConnection(const wxString& host,
	132	const wxString& service,
	133	const wxString& topic);
23324ae1 FM	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.
4876436a	140
23324ae1 FM	141	The advantage of deriving your own connection class is that it will
23324ae1 FM	142	enable you to intercept messages initiated by the server, such
4876436a FM	143	as wxTCPConnection::OnAdvise(). You may also want to store
4876436a FM	144	application-specific data in instances of the new class.
23324ae1	145	*/
adaaa686	146	virtual wxConnectionBase* OnMakeConnection();
23324ae1 FM	147
	148	/**
	149	Returns @true if this is a valid host name, @false otherwise.
	150	*/
adaaa686	151	virtual bool ValidHost(const wxString& host);
23324ae1 FM	152	};
	153
	154
e54c96f1	155
23324ae1 FM	156	/**
23324ae1 FM	157	@class wxTCPConnection
7c913512	158
23324ae1 FM	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.
7c913512	162
23324ae1	163	A DDE-based implementation for Windows is available using wxDDEConnection.
7c913512	164
23324ae1	165	A wxTCPConnection object can be created by making a connection using a
4876436a FM	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.
7c913512	169
23324ae1 FM	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.
7c913512	173
23324ae1	174	@library{wxnet}
4876436a	175	@category{net}
7c913512	176
4876436a	177	@see wxTCPClient, wxTCPServer, @ref overview_ipc
23324ae1 FM	178	*/
	179	class wxTCPConnection : public wxObject
	180	{
	181	public:
	182	//@{
	183	/**
4876436a FM	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
23324ae1 FM	197	transactions.
	198	*/
	199	wxTCPConnection();
7c913512	200	wxTCPConnection(void* buffer, size_t size);
23324ae1 FM	201	//@}
	202
	203	//@{
	204	/**
	205	Called by the server application to advise the client of a change in
4876436a FM	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.
23324ae1 FM	211	*/
	212	bool Advise(const wxString& item, const void* data, size_t size,
	213	wxIPCFormat format = wxIPC_PRIVATE);
7c913512 FM	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);
23324ae1 FM	217	//@}
	218
	219	/**
	220	Called by the client or server application to disconnect from the other
4876436a FM	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
23324ae1	225	connection, but the calling application must explicitly delete its
4876436a FM	226	side of the connection having called @b Disconnect.
	227
	228	Returns @true if successful.
23324ae1	229	*/
adaaa686	230	virtual bool Disconnect();
23324ae1 FM	231
	232	//@{
	233	/**
4876436a FM	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.
23324ae1 FM	240	*/
	241	bool Execute(const void* data, size_t size,
	242	wxIPCFormat format = wxIPC_PRIVATE);
7c913512 FM	243	bool Execute(const char* data);
	244	bool Execute(const wchar_t* data);
	245	bool Execute(const wxString data);
23324ae1 FM	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
4876436a FM	260	application notifies it to delete the connection.
4876436a FM	261	Default behaviour is to delete the connection object.
23324ae1 FM	262	*/
	263	virtual bool OnDisconnect();
	264
	265	/**
	266	Message sent to the server application when the client notifies it to
4876436a FM	267	execute the given data.
4876436a FM	268	Note that there is no item associated with this message.
23324ae1 FM	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	/**
4876436a FM	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,
23324ae1 FM	287	or @NULL to indicate no data.
	288	*/
	289	virtual const void* OnRequest(const wxString& topic,
	290	const wxString& item,
4cc4bfaf	291	size_t* size,
23324ae1 FM	292	wxIPCFormat format);
	293
	294	/**
	295	Message sent to the server application by the client, when the client
4876436a FM	296	wishes to start an 'advise loop' for the given topic and item.
4876436a FM	297	The server can refuse to participate by returning @false.
23324ae1 FM	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
4876436a FM	304	wishes to stop an 'advise loop' for the given topic and item.
4876436a FM	305	The server can refuse to stop the advise loop by returning @false, although
23324ae1 FM	306	this doesn't have much meaning in practice.
	307	*/
	308	virtual bool OnStopAdvise(const wxString& topic,
	309	const wxString& item);
	310
	311	//@{
	312	/**
4876436a FM	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.
23324ae1 FM	316	*/
	317	bool Poke(const wxString& item, const void* data, size_t size,
	318	wxIPCFormat format = wxIPC_PRIVATE);
7c913512 FM	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);
23324ae1 FM	322	//@}
	323
	324	/**
4876436a FM	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
23324ae1 FM	329	successful, @NULL otherwise.
23324ae1 FM	330	*/
5267aefd	331	virtual const void* Request(const wxString& item, size_t* size = 0,
23324ae1 FM	332	wxIPCFormat format = wxIPC_TEXT);
	333
	334	/**
	335	Called by the client application to ask if an advise loop can be started
4876436a FM	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.
23324ae1	340	*/
adaaa686	341	virtual bool StartAdvise(const wxString& item);
23324ae1 FM	342
23324ae1 FM	343	/**
4876436a FM	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.
23324ae1	347	*/
adaaa686	348	virtual bool StopAdvise(const wxString& item);
23324ae1	349	};
e54c96f1	350