1\section{\class{wxTCPConnection}}\label{wxtcpconnection}
2
3A wxTCPClient object represents the connection between a client and a server.
4It emulates a DDE-style protocol, but uses TCP/IP which is available on most platforms.
5
6A DDE-based implementation for Windows is available using \helpref{wxDDEConnection}{wxddeconnection}.
7
8A wxTCPConnection object can be created by making a connection using a\rtfsp
9\helpref{wxTCPClient}{wxtcpclient} object, or by the acceptance of a connection by a\rtfsp
10\helpref{wxTCPServer}{wxtcpserver} object. The bulk of a conversation is controlled by
11calling members in a {\bf wxTCPConnection} object or by overriding its
12members.
13
14An application should normally derive a new connection class from
15wxTCPConnection, in order to override the communication event handlers
16to do something interesting.
17
18\wxheading{Derived from}
19
20wxConnectionBase\\
21\helpref{wxObject}{wxobject}
22
23\wxheading{Include files}
24
25<wx/sckipc.h>
26
27\wxheading{Types}
28
29\index{wxIPCFormat}wxIPCFormat is defined as follows:
30
31\begin{verbatim}
32enum wxIPCFormat
33{
34  wxIPC_INVALID =          0,
35  wxIPC_TEXT =             1,  /* CF_TEXT */
36  wxIPC_BITMAP =           2,  /* CF_BITMAP */
37  wxIPC_METAFILE =         3,  /* CF_METAFILEPICT */
38  wxIPC_SYLK =             4,
39  wxIPC_DIF =              5,
40  wxIPC_TIFF =             6,
41  wxIPC_OEMTEXT =          7,  /* CF_OEMTEXT */
42  wxIPC_DIB =              8,  /* CF_DIB */
43  wxIPC_PALETTE =          9,
44  wxIPC_PENDATA =          10,
45  wxIPC_RIFF =             11,
46  wxIPC_WAVE =             12,
47  wxIPC_UNICODETEXT =      13,
48  wxIPC_ENHMETAFILE =      14,
49  wxIPC_FILENAME =         15, /* CF_HDROP */
50  wxIPC_LOCALE =           16,
51  wxIPC_PRIVATE =          20
52};
53\end{verbatim}
54
55\wxheading{See also}
56
57\helpref{wxTCPClient}{wxtcpclient}, \helpref{wxTCPServer}{wxtcpserver}, \helpref{Interprocess communications overview}{ipcoverview}
58
59\latexignore{\rtfignore{\wxheading{Members}}}
60
61\membersection{wxTCPConnection::wxTCPConnection}\label{wxtcpconnectionctor}
62
63\func{}{wxTCPConnection}{\void}
64
65\func{}{wxTCPConnection}{\param{char* }{buffer}, \param{int}{ size}}
66
67Constructs a connection object. If no user-defined connection object is
68to be derived from wxTCPConnection, then the constructor should not be
69called directly, since the default connection object will be provided on
70requesting (or accepting) a connection. However, if the user defines his
71or her own derived connection object, the \helpref{wxTCPServer::OnAcceptConnection}{wxtcpserveronacceptconnection}\rtfsp
72and/or \helpref{wxTCPClient::OnMakeConnection}{wxtcpclientonmakeconnection} members should be replaced by
73functions which construct the new connection object. If the arguments of
74the wxTCPConnection constructor are void, then a default buffer is
75associated with the connection. Otherwise, the programmer must provide a
76a buffer and size of the buffer for the connection object to use in
77transactions.
78
79\membersection{wxTCPConnection::Advise}\label{wxtcpconnectionadvise}
80
81\func{bool}{Advise}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
82
83Called by the server application to advise the client of a change in
84the data associated with the given item. Causes the client
85connection's \helpref{wxTCPConnection::OnAdvise}{wxtcpconnectiononadvise} 
86member to be called. Returns true if successful.
87
88\membersection{wxTCPConnection::Execute}\label{wxtcpconnectionexecute}
89
90\func{bool}{Execute}{\param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
91
92Called by the client application to execute a command on the server. Can
93also be used to transfer arbitrary data to the server (similar
94to \helpref{wxTCPConnection::Poke}{wxtcpconnectionpoke} in that respect). Causes the
95server connection's \helpref{wxTCPConnection::OnExecute}{wxtcpconnectiononexecute} member to be
96called. Returns true if successful.
97
98\membersection{wxTCPConnection::Disconnect}\label{wxtcpconnectiondisconnect}
99
100\func{bool}{Disconnect}{\void}
101
102Called by the client or server application to disconnect from the other
103program; it causes the \helpref{wxTCPConnection::OnDisconnect}{wxtcpconnectionondisconnect} message
104to be sent to the corresponding connection object in the other
105program. The default behaviour of {\bf OnDisconnect} is to delete the
106connection, but the calling application must explicitly delete its
107side of the connection having called {\bf Disconnect}. Returns true if
108successful.
109
110\membersection{wxTCPConnection::OnAdvise}\label{wxtcpconnectiononadvise}
111
112\func{virtual bool}{OnAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
113
114Message sent to the client application when the server notifies it of a
115change in the data associated with the given item.
116
117\membersection{wxTCPConnection::OnDisconnect}\label{wxtcpconnectionondisconnect}
118
119\func{virtual bool}{OnDisconnect}{\void}
120
121Message sent to the client or server application when the other
122application notifies it to delete the connection. Default behaviour is
123to delete the connection object.
124
125\membersection{wxTCPConnection::OnExecute}\label{wxtcpconnectiononexecute}
126
127\func{virtual bool}{OnExecute}{\param{const wxString\& }{topic}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
128
129Message sent to the server application when the client notifies it to
130execute the given data. Note that there is no item associated with
131this message.
132
133\membersection{wxTCPConnection::OnPoke}\label{wxtcpconnectiononpoke}
134
135\func{virtual bool}{OnPoke}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
136
137Message sent to the server application when the client notifies it to
138accept the given data.
139
140\membersection{wxTCPConnection::OnRequest}\label{wxtcpconnectiononrequest}
141
142\func{virtual char*}{OnRequest}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format}}
143
144Message sent to the server application when the client
145calls \helpref{wxTCPConnection::Request}{wxtcpconnectionrequest}. The server
146should respond by returning a character string from {\bf OnRequest},
147or NULL to indicate no data.
148
149\membersection{wxTCPConnection::OnStartAdvise}\label{wxtcpconnectiononstartadvise}
150
151\func{virtual bool}{OnStartAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
152
153Message sent to the server application by the client, when the client
154wishes to start an `advise loop' for the given topic and item. The
155server can refuse to participate by returning false.
156
157\membersection{wxTCPConnection::OnStopAdvise}\label{wxtcpconnectiononstopadvise}
158
159\func{virtual bool}{OnStopAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
160
161Message sent to the server application by the client, when the client
162wishes to stop an `advise loop' for the given topic and item. The
163server can refuse to stop the advise loop by returning false, although
164this doesn't have much meaning in practice.
165
166\membersection{wxTCPConnection::Poke}\label{wxtcpconnectionpoke}
167
168\func{bool}{Poke}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
169
170Called by the client application to poke data into the server. Can be
171used to transfer arbitrary data to the server. Causes the server
172connection's \helpref{wxTCPConnection::OnPoke}{wxtcpconnectiononpoke} member
173to be called. Returns true if successful.
174
175\membersection{wxTCPConnection::Request}\label{wxtcpconnectionrequest}
176
177\func{char*}{Request}{\param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format = wxIPC\_TEXT}}
178
179Called by the client application to request data from the server. Causes
180the server connection's \helpref{wxTCPConnection::OnRequest}{wxtcpconnectiononrequest} member to be called. Returns a
181character string (actually a pointer to the connection's buffer) if
182successful, NULL otherwise.
183
184\membersection{wxTCPConnection::StartAdvise}\label{wxtcpconnectionstartadvise}
185
186\func{bool}{StartAdvise}{\param{const wxString\& }{item}}
187
188Called by the client application to ask if an advise loop can be started
189with the server. Causes the server connection's \helpref{wxTCPConnection::OnStartAdvise}{wxtcpconnectiononstartadvise}\rtfsp
190member to be called. Returns true if the server okays it, false
191otherwise.
192
193\membersection{wxTCPConnection::StopAdvise}\label{wxtcpconnectionstopadvise}
194
195\func{bool}{StopAdvise}{\param{const wxString\& }{item}}
196
197Called by the client application to ask if an advise loop can be
198stopped. Causes the server connection's \helpref{wxTCPConnection::OnStopAdvise}{wxtcpconnectiononstopadvise} member
199to be called. Returns true if the server okays it, false otherwise.
200
201