1\section{\class{wxConnection}}\label{wxconnection}
2
3A wxConnection object represents the connection between a client
4and a server. It is created by making a connection using a\rtfsp
5\helpref{wxClient}{wxclient} object, or by the acceptance of a
6connection by a\rtfsp \helpref{wxServer}{wxserver} object. The
7bulk of a DDE-like (Dynamic Data Exchange) conversation is
8controlled by calling members in a {\bf wxConnection} object or
9by overriding its members. The actual DDE-based implementation
10using wxDDEConnection is available on Windows only, but a
11platform-independent, socket-based version of this API is
12available using wxTCPConnection, which has the same API.
13
14An application should normally derive a new connection class from
15wxConnection, in order to override the communication event
16handlers to do something interesting.
17
18\wxheading{Derived from}
19
20wxConnectionBase\\
21\helpref{wxObject}{wxobject}
22
23\wxheading{Include files}
24
25<wx/ipc.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{wxClient}{wxclient}, \helpref{wxServer}{wxserver},
58\helpref{Interprocess communications overview}{ipcoverview}
59
60\latexignore{\rtfignore{\wxheading{Members}}}
61
62\membersection{wxConnection::wxConnection}\label{wxconnectionctor}
63
64\func{}{wxConnection}{\void}
65
66\func{}{wxConnection}{\param{char* }{buffer}, \param{int}{ size}}
67
68Constructs a connection object. If no user-defined connection
69object is to be derived from wxConnection, then the constructor
70should not be called directly, since the default connection
71object will be provided on requesting (or accepting) a
72connection. However, if the user defines his or her own derived
73connection object, the \helpref{wxServer::OnAcceptConnection}{wxserveronacceptconnection}\rtfsp
74and/or \helpref{wxClient::OnMakeConnection}{wxclientonmakeconnection} 
75members should be replaced by functions which construct the new
76connection object.
77
78If the arguments of the wxConnection constructor are void then
79the wxConnection object manages its own connection buffer,
80allocating memory as needed. A programmer-supplied buffer cannot
81be increased if necessary, and the program will assert if it is
82not large enough. The programmer-supplied buffer is included
83mainly for backwards compatibility.
84
85\membersection{wxConnection::Advise}\label{wxconnectionadvise}
86
87\func{bool}{Advise}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
88
89Called by the server application to advise the client of a change
90in the data associated with the given item. Causes the client
91connection's \helpref{wxConnection::OnAdvise}{wxconnectiononadvise} member
92to be called. Returns true if successful.
93
94\membersection{wxConnection::Execute}\label{wxconnectionexecute}
95
96\func{bool}{Execute}{\param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
97
98Called by the client application to execute a command on the
99server. Can also be used to transfer arbitrary data to the server
100(similar to \helpref{wxConnection::Poke}{wxconnectionpoke} in
101that respect). Causes the server connection's \helpref{wxConnection::OnExecute}{wxconnectiononexecute} 
102member to be called. Returns true if successful.
103
104\membersection{wxConnection::Disconnect}\label{wxconnectiondisconnect}
105
106\func{bool}{Disconnect}{\void}
107
108Called by the client or server application to disconnect from the
109other program; it causes the \helpref{wxConnection::OnDisconnect}{wxconnectionondisconnect} 
110message to be sent to the corresponding connection object in the
111other program. Returns true if successful or already disconnected.
112The application that calls {\bf Disconnect} must explicitly delete
113its side of the connection.
114
115\membersection{wxConnection::OnAdvise}\label{wxconnectiononadvise}
116
117\func{virtual bool}{OnAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
118
119Message sent to the client application when the server notifies
120it of a change in the data associated with the given item, using
121\helpref{Advise}{wxconnectionadvise}.
122
123\membersection{wxConnection::OnDisconnect}\label{wxconnectionondisconnect}
124
125\func{virtual bool}{OnDisconnect}{\void}
126
127Message sent to the client or server application when the other
128application notifies it to end the connection. The default
129behaviour is to delete the connection object and return true, so
130applications should generally override {\bf OnDisconnect}
131(finally calling the inherited method as well) so that they know
132the connection object is no longer available.
133
134\membersection{wxConnection::OnExecute}\label{wxconnectiononexecute}
135
136\func{virtual bool}{OnExecute}{\param{const wxString\& }{topic}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
137
138Message sent to the server application when the client notifies
139it to execute the given data, using \helpref{Execute}{wxconnectionexecute}.
140Note that there is no item associated with this message.
141
142\membersection{wxConnection::OnPoke}\label{wxconnectiononpoke}
143
144\func{virtual bool}{OnPoke}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
145
146Message sent to the server application when the client notifies it to
147accept the given data.
148
149\membersection{wxConnection::OnRequest}\label{wxconnectiononrequest}
150
151\func{virtual char*}{OnRequest}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format}}
152
153Message sent to the server application when the client calls 
154\helpref{wxConnection::Request}{wxconnectionrequest}. The
155server's \helpref{OnRequest}{wxconnectiononrequest} method
156should respond by returning a character string, or NULL to
157indicate no data, and setting *size. The character string must of
158course persist after the call returns.
159
160\membersection{wxConnection::OnStartAdvise}\label{wxconnectiononstartadvise}
161
162\func{virtual bool}{OnStartAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
163
164Message sent to the server application by the client, when the client
165wishes to start an `advise loop' for the given topic and item. The
166server can refuse to participate by returning false.
167
168\membersection{wxConnection::OnStopAdvise}\label{wxconnectiononstopadvise}
169
170\func{virtual bool}{OnStopAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
171
172Message sent to the server application by the client, when the client
173wishes to stop an `advise loop' for the given topic and item. The
174server can refuse to stop the advise loop by returning false, although
175this doesn't have much meaning in practice.
176
177\membersection{wxConnection::Poke}\label{wxconnectionpoke}
178
179\func{bool}{Poke}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
180
181Called by the client application to poke data into the server.
182Can be used to transfer arbitrary data to the server. Causes the
183server connection's \helpref{wxConnection::OnPoke}{wxconnectiononpoke} member to
184be called. If size is -1 the size is computed from the string
185length of data.
186
187Returns true if successful.
188
189\membersection{wxConnection::Request}\label{wxconnectionrequest}
190
191\func{char*}{Request}{\param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format = wxIPC\_TEXT}}
192
193Called by the client application to request data from the server.
194Causes the server connection's \helpref{wxConnection::OnRequest}{wxconnectiononrequest} 
195member to be called. Size may be NULL or a pointer to a variable
196to receive the size of the requested item.
197
198Returns a character string (actually a pointer to the
199connection's buffer) if successful, NULL otherwise. This buffer
200does not need to be deleted.
201
202\membersection{wxConnection::StartAdvise}\label{wxconnectionstartadvise}
203
204\func{bool}{StartAdvise}{\param{const wxString\& }{item}}
205
206Called by the client application to ask if an advise loop can be
207started with the server. Causes the server connection's 
208\helpref{wxConnection::OnStartAdvise}{wxconnectiononstartadvise}\rtfsp
209member to be called. Returns true if the server okays it, false
210otherwise.
211
212\membersection{wxConnection::StopAdvise}\label{wxconnectionstopadvise}
213
214\func{bool}{StopAdvise}{\param{const wxString\& }{item}}
215
216Called by the client application to ask if an advise loop can be
217stopped. Causes the server connection's \helpref{wxConnection::OnStopAdvise}{wxconnectiononstopadvise} 
218member to be called. Returns true if the server okays it, false
219otherwise.
220
221