+\section{\class{wxConnection}}\label{wxddeconnection}
+
+A wxConnection object represents the connection between a client
+and a server. It is created by making a connection using a\rtfsp
+\helpref{wxClient}{wxddeclient} object, or by the acceptance of a
+connection by a\rtfsp \helpref{wxServer}{wxddeserver} object. The
+bulk of a DDE-like (Dynamic Data Exchange) conversation is
+controlled by calling members in a {\bf wxConnection} object or
+by overriding its members. The actual DDE-based implementation
+using wxDDEConnection is available on Windows only, but a
+platform-independent, socket-based version of this API is
+available using wxTCPConnection, which has the same API.
+
+An application should normally derive a new connection class from
+wxConnection, in order to override the communication event
+handlers to do something interesting.
+
+\wxheading{Derived from}
+
+wxConnectionBase\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/ipc.h>
+
+\wxheading{Types}
+
+\index{wxIPCFormat}wxIPCFormat is defined as follows:
+
+\begin{verbatim}
+enum wxIPCFormat
+{
+ wxIPC_INVALID = 0,
+ wxIPC_TEXT = 1, /* CF_TEXT */
+ wxIPC_BITMAP = 2, /* CF_BITMAP */
+ wxIPC_METAFILE = 3, /* CF_METAFILEPICT */
+ wxIPC_SYLK = 4,
+ wxIPC_DIF = 5,
+ wxIPC_TIFF = 6,
+ wxIPC_OEMTEXT = 7, /* CF_OEMTEXT */
+ wxIPC_DIB = 8, /* CF_DIB */
+ wxIPC_PALETTE = 9,
+ wxIPC_PENDATA = 10,
+ wxIPC_RIFF = 11,
+ wxIPC_WAVE = 12,
+ wxIPC_UNICODETEXT = 13,
+ wxIPC_ENHMETAFILE = 14,
+ wxIPC_FILENAME = 15, /* CF_HDROP */
+ wxIPC_LOCALE = 16,
+ wxIPC_PRIVATE = 20
+};
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxClient}{wxddeclient}, \helpref{wxServer}{wxddeserver},
+\helpref{Interprocess communications overview}{ipcoverview}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxConnection::wxConnection}
+
+\func{}{wxConnection}{\void}
+
+\func{}{wxConnection}{\param{char* }{buffer}, \param{int}{ size}}
+
+Constructs a connection object. If no user-defined connection
+object is to be derived from wxConnection, then the constructor
+should not be called directly, since the default connection
+object will be provided on requesting (or accepting) a
+connection. However, if the user defines his or her own derived
+connection object, the\helpref{wxServer::OnAcceptConnection}{wxddeserveronacceptconnection}\rtfsp
+and/or \helpref{wxClient::OnMakeConnection}{wxddeclientonmakeconnection}
+members should be replaced by functions which construct the new
+connection object.
+
+If the arguments of the wxConnection constructor are void then
+the wxConnection object manages its own connection buffer,
+allocating memory as needed. A programmer-supplied buffer cannot
+be increased if necessary, and the program will assert if it is
+not large enough. The programmer-supplied buffer is included
+mainly for backwards compatibility.
+
+\membersection{wxConnection::Advise}\label{wxddeconnectionadvise}
+
+\func{bool}{Advise}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
+
+Called by the server application to advise the client of a change
+in the data associated with the given item. Causes the client
+connection's \helpref{wxConnection::OnAdvise}{wxddeconnectiononadvise} member
+to be called. Returns TRUE if successful.
+
+\membersection{wxConnection::Execute}\label{wxddeconnectionexecute}
+
+\func{bool}{Execute}{\param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
+
+Called by the client application to execute a command on the
+server. Can also be used to transfer arbitrary data to the server
+(similar to \helpref{wxConnection::Poke}{wxddeconnectionpoke} in
+that respect). Causes the server connection's \helpref{wxConnection::OnExecute}{wxddeconnectiononexecute}
+member to be called. Returns TRUE if successful.
+
+\membersection{wxConnection::Disconnect}
+
+\func{bool}{Disconnect}{\void}
+
+Called by the client or server application to disconnect from the
+other program; it causes the \helpref{wxConnection::OnDisconnect}{wxddeconnectionondisconnect}
+message to be sent to the corresponding connection object in the
+other program. Returns TRUE if successful or already disconnected.
+The application that calls {\bf Disconnect} must explicitly delete
+its side of the connection.
+
+\membersection{wxConnection::OnAdvise}\label{wxddeconnectiononadvise}
+
+\func{virtual bool}{OnAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
+
+Message sent to the client application when the server notifies
+it of a change in the data associated with the given item, using
+\helpref{Advise}{wxddeconnectionadvise}.
+
+\membersection{wxConnection::OnDisconnect}\label{wxddeconnectionondisconnect}
+
+\func{virtual bool}{OnDisconnect}{\void}
+
+Message sent to the client or server application when the other
+application notifies it to end the connection. The default
+behaviour is to delete the connection object and return true, so
+applications should generally override {\bf OnDisconnect}
+(finally calling the inherited method as well) so that they know
+the connection object is no longer available.
+
+\membersection{wxConnection::OnExecute}\label{wxddeconnectiononexecute}
+
+\func{virtual bool}{OnExecute}{\param{const wxString\& }{topic}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
+
+Message sent to the server application when the client notifies
+it to execute the given data, using \helpref{Execute}{wxddeconnectionexecute}.
+Note that there is no item associated with this message.
+
+\membersection{wxConnection::OnPoke}\label{wxddeconnectiononpoke}
+
+\func{virtual bool}{OnPoke}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
+
+Message sent to the server application when the client notifies it to
+accept the given data.
+
+\membersection{wxConnection::OnRequest}\label{wxddeconnectiononrequest}
+
+\func{virtual char*}{OnRequest}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format}}
+
+Message sent to the server application when the client calls
+\helpref{wxConnection::Request}{wxddeconnectionrequest}. The
+server's \helpref{OnRequest}{wxddeconnectiononrequest} method
+should respond by returning a character string, or NULL to
+indicate no data, and setting *size. The character string must of
+course persist after the call returns.
+
+\membersection{wxConnection::OnStartAdvise}\label{wxddeconnectiononstartadvise}
+
+\func{virtual bool}{OnStartAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
+
+Message sent to the server application by the client, when the client
+wishes to start an `advise loop' for the given topic and item. The
+server can refuse to participate by returning FALSE.
+
+\membersection{wxConnection::OnStopAdvise}\label{wxddeconnectiononstopadvise}
+
+\func{virtual bool}{OnStopAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
+
+Message sent to the server application by the client, when the client
+wishes to stop an `advise loop' for the given topic and item. The
+server can refuse to stop the advise loop by returning FALSE, although
+this doesn't have much meaning in practice.
+
+\membersection{wxConnection::Poke}\label{wxddeconnectionpoke}
+
+\func{bool}{Poke}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
+
+Called by the client application to poke data into the server.
+Can be used to transfer arbitrary data to the server. Causes the
+server connection's \helpref{wxConnection::OnPoke}{wxddeconnectiononpoke} member to
+be called. If size is -1 the size is computed from the string
+length of data.
+
+Returns TRUE if successful.
+
+\membersection{wxConnection::Request}\label{wxddeconnectionrequest}
+
+\func{char*}{Request}{\param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format = wxIPC\_TEXT}}
+
+Called by the client application to request data from the server.
+Causes the server connection's \helpref{wxConnection::OnRequest}{wxddeconnectiononrequest}
+member to be called. Size may be NULL or a pointer to a variable
+to receive the size of the requested item.
+
+Returns a character string (actually a pointer to the
+connection's buffer) if successful, NULL otherwise. This buffer
+does not need to be deleted.
+
+\membersection{wxConnection::StartAdvise}\label{wxddeconnectionstartadvise}
+
+\func{bool}{StartAdvise}{\param{const wxString\& }{item}}
+
+Called by the client application to ask if an advise loop can be
+started with the server. Causes the server connection's
+\helpref{wxConnection::OnStartAdvise}{wxddeconnectiononstartadvise}\rtfsp
+member to be called. Returns TRUE if the server okays it, FALSE
+otherwise.
+
+\membersection{wxConnection::StopAdvise}\label{wxddeconnectionstopadvise}
+
+\func{bool}{StopAdvise}{\param{const wxString\& }{item}}
+
+Called by the client application to ask if an advise loop can be
+stopped. Causes the server connection's \helpref{wxConnection::OnStopAdvise}{wxddeconnectiononstopadvise}
+member to be called. Returns TRUE if the server okays it, FALSE
+otherwise.
+
projects / wxWidgets.git / commitdiff
