wxExecute may only be called from the main thread

[wxWidgets.git] / docs / latex / wx / ddeconn.tex

\section{\class{wxDDEConnection}}\label{wxddeconnection}

A wxDDEConnection object represents the connection between a client and a
server. It can be created by making a connection using a\rtfsp
\helpref{wxDDEClient}{wxddeclient} object, or by the acceptance of a connection by a\rtfsp
\helpref{wxDDEServer}{wxddeserver} object. The bulk of a DDE (Dynamic Data Exchange)
conversation is controlled by
calling members in a {\bf wxDDEConnection} object or by overriding its
members.

An application should normally derive a new connection class from
wxDDEConnection, in order to override the communication event handlers
to do something interesting.

This DDE-based implementation is available on Windows only,
but a platform-independent, socket-based version
of this API is available using \helpref{wxTCPConnection}{wxtcpconnection}.

\wxheading{Derived from}

wxConnectionBase\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/dde.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{wxDDEClient}{wxddeclient}, \helpref{wxDDEServer}{wxddeserver}, \helpref{Interprocess communications overview}{ipcoverview}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDDEConnection::wxDDEConnection}

\func{}{wxDDEConnection}{\void}

\func{}{wxDDEConnection}{\param{char* }{buffer}, \param{int}{ size}}

Constructs a connection object. If no user-defined connection object is
to be derived from wxDDEConnection, 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{wxDDEServer::OnAcceptConnection}{wxddeserveronacceptconnection}\rtfsp
and/or \helpref{wxDDEClient::OnMakeConnection}{wxddeclientonmakeconnection} members should be replaced by
functions which construct the new connection object. If the arguments of
the wxDDEConnection constructor are void, then a default buffer is
associated with the connection. Otherwise, the programmer must provide a
a buffer and size of the buffer for the connection object to use in
transactions.

\membersection{wxDDEConnection::Advise}

\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{wxDDEConnection::OnAdvise}{wxddeconnectiononadvise}
member to be called. Returns true if successful.

\membersection{wxDDEConnection::Execute}

\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{wxDDEConnection::Poke}{wxddeconnectionpoke} in that respect). Causes the
server connection's \helpref{wxDDEConnection::OnExecute}{wxddeconnectiononexecute} member to be
called. Returns true if successful.

\membersection{wxDDEConnection::Disconnect}

\func{bool}{Disconnect}{\void}

Called by the client or server application to disconnect from the other
program; it causes the \helpref{wxDDEConnection::OnDisconnect}{wxddeconnectionondisconnect} message
to be sent to the corresponding connection object in the other
program. The default behaviour of {\bf OnDisconnect} is to delete the
connection, but the calling application must explicitly delete its
side of the connection having called {\bf Disconnect}. Returns true if
successful.

\membersection{wxDDEConnection::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.

\membersection{wxDDEConnection::OnDisconnect}\label{wxddeconnectionondisconnect}

\func{virtual bool}{OnDisconnect}{\void}

Message sent to the client or server application when the other
application notifies it to delete the connection. Default behaviour is
to delete the connection object.

\membersection{wxDDEConnection::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. Note that there is no item associated with
this message.

\membersection{wxDDEConnection::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{wxDDEConnection::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{wxDDEConnection::Request}{wxddeconnectionrequest}. The server
should respond by returning a character string from {\bf OnRequest},
or NULL to indicate no data.

\membersection{wxDDEConnection::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{wxDDEConnection::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{wxDDEConnection::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{wxDDEConnection::OnPoke}{wxddeconnectiononpoke} member
to be called. Returns true if successful.

\membersection{wxDDEConnection::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{wxDDEConnection::OnRequest}{wxddeconnectiononrequest} member to be called. Returns a
character string (actually a pointer to the connection's buffer) if
successful, NULL otherwise.

\membersection{wxDDEConnection::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{wxDDEConnection::OnStartAdvise}{wxddeconnectiononstartadvise}\rtfsp
member to be called. Returns true if the server okays it, false
otherwise.

\membersection{wxDDEConnection::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{wxDDEConnection::OnStopAdvise}{wxddeconnectiononstopadvise} member
to be called. Returns true if the server okays it, false otherwise.