[wxWidgets.git] / docs / latex / wx / ipcclint.tex

\section{\class{wxClient}}\label{wxddeclient}

A wxClient object represents the client part of a client-server
DDE-like (Dynamic Data Exchange) conversation. The actual
DDE-based implementation using wxDDEClient is available on Windows
only, but a platform-independent, socket-based version of this
API is available using wxTCPClient, which has the same API.

To create a client which can communicate with a suitable server,
you need to derive a class from wxConnection and another from
wxClient. The custom wxConnection class will intercept
communications in a `conversation' with a server, and the custom
wxClient is required so that a user-overridden
\helpref{wxClient::OnMakeConnection}{wxddeclientonmakeconnection} 
member can return a wxConnection of the required class, when a
connection is made. Look at the IPC sample and the 
\helpref{Interprocess communications overview}{ipcoverview} for
an example of how to do this.

\wxheading{Derived from}

wxClientBase\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/ipc.h>

\wxheading{See also}

\helpref{wxServer}{wxddeserver}, 
\helpref{wxConnection}{wxddeconnection}, \helpref{Interprocess communications overview}{ipcoverview}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxClient::wxClient}

\func{}{wxClient}{\void}

Constructs a client object.

\membersection{wxClient::MakeConnection}\label{wxddeclientmakeconnection}

\func{wxConnectionBase *}{MakeConnection}{\param{const wxString\& }{host}, \param{const wxString\& }{service}, \param{const wxString\& }{topic}}

Tries to make a connection with a server by host (machine name
under UNIX - use 'localhost' for same machine; ignored when using
native DDE in Windows), service name and topic string. If the
server allows a connection, a wxConnection object will be
returned. The type of wxConnection returned can be altered by
overriding the 
\helpref{wxClient::OnMakeConnection}{wxddeclientonmakeconnection} 
member to return your own derived connection object.

Under Unix, the service name may be either an integer port
identifier in which case an Internet domain socket will be used
for the communications, or a valid file name (which shouldn't
exist and will be deleted afterwards) in which case a Unix domain
socket is created.

{\bf SECURITY NOTE:} Using Internet domain sockets if extremely
insecure for IPC as there is absolutely no access control for
them, use Unix domain sockets whenever possible!

\membersection{wxClient::OnMakeConnection}\label{wxddeclientonmakeconnection}

\func{wxConnectionBase *}{OnMakeConnection}{\void}

Called by \helpref{wxClient::MakeConnection}{wxddeclientmakeconnection}, by
default this simply returns a new wxConnection object. Override
this method to return a wxConnection descendant customised for the
application.

The advantage of deriving your own connection class is that it
will enable you to intercept messages initiated by the server,
such as \helpref{wxConnection::OnAdvise}{wxddeconnectiononadvise}. You
may also want to store application-specific data in instances of
the new class.

\membersection{wxClient::ValidHost}

\func{bool}{ValidHost}{\param{const wxString\& }{host}}

Returns true if this is a valid host name, false otherwise. This always
returns true under MS Windows.
Commit	Line	Data
47610ec2 JS	1	\section{\class{wxClient}}\label{wxddeclient}
	2
	3	A wxClient object represents the client part of a client-server
	4	DDE-like (Dynamic Data Exchange) conversation. The actual
	5	DDE-based implementation using wxDDEClient is available on Windows
	6	only, but a platform-independent, socket-based version of this
	7	API is available using wxTCPClient, which has the same API.
	8
	9	To create a client which can communicate with a suitable server,
	10	you need to derive a class from wxConnection and another from
	11	wxClient. The custom wxConnection class will intercept
	12	communications in a `conversation' with a server, and the custom
	13	wxClient is required so that a user-overridden
	14	\helpref{wxClient::OnMakeConnection}{wxddeclientonmakeconnection}
	15	member can return a wxConnection of the required class, when a
	16	connection is made. Look at the IPC sample and the
	17	\helpref{Interprocess communications overview}{ipcoverview} for
	18	an example of how to do this.
	19
	20	\wxheading{Derived from}
	21
	22	wxClientBase\\
	23	\helpref{wxObject}{wxobject}
	24
	25	\wxheading{Include files}
	26
	27	<wx/ipc.h>
	28
	29	\wxheading{See also}
	30
	31	\helpref{wxServer}{wxddeserver},
	32	\helpref{wxConnection}{wxddeconnection}, \helpref{Interprocess communications overview}{ipcoverview}
	33
	34	\latexignore{\rtfignore{\wxheading{Members}}}
	35
	36	\membersection{wxClient::wxClient}
	37
	38	\func{}{wxClient}{\void}
	39
	40	Constructs a client object.
	41
	42	\membersection{wxClient::MakeConnection}\label{wxddeclientmakeconnection}
	43
	44	\func{wxConnectionBase *}{MakeConnection}{\param{const wxString\& }{host}, \param{const wxString\& }{service}, \param{const wxString\& }{topic}}
	45
	46	Tries to make a connection with a server by host (machine name
	47	under UNIX - use 'localhost' for same machine; ignored when using
	48	native DDE in Windows), service name and topic string. If the
	49	server allows a connection, a wxConnection object will be
	50	returned. The type of wxConnection returned can be altered by
	51	overriding the
	52	\helpref{wxClient::OnMakeConnection}{wxddeclientonmakeconnection}
	53	member to return your own derived connection object.
	54
	55	Under Unix, the service name may be either an integer port
	56	identifier in which case an Internet domain socket will be used
	57	for the communications, or a valid file name (which shouldn't
	58	exist and will be deleted afterwards) in which case a Unix domain
	59	socket is created.
	60
	61	{\bf SECURITY NOTE:} Using Internet domain sockets if extremely
	62	insecure for IPC as there is absolutely no access control for
	63	them, use Unix domain sockets whenever possible!
	64
65	\membersection{wxClient::OnMakeConnection}\label{wxddeclientonmakeconnection}
66
67	\func{wxConnectionBase *}{OnMakeConnection}{\void}
68
69	Called by \helpref{wxClient::MakeConnection}{wxddeclientmakeconnection}, by
70	default this simply returns a new wxConnection object. Override
71	this method to return a wxConnection descendant customised for the
72	application.
73
74	The advantage of deriving your own connection class is that it
75	will enable you to intercept messages initiated by the server,
76	such as \helpref{wxConnection::OnAdvise}{wxddeconnectiononadvise}. You
77	may also want to store application-specific data in instances of
78	the new class.
79
80	\membersection{wxClient::ValidHost}
81
82	\func{bool}{ValidHost}{\param{const wxString\& }{host}}
83
cc81d32f VS	84	Returns true if this is a valid host name, false otherwise. This always
cc81d32f VS	85	returns true under MS Windows.
47610ec2	86