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