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