+\section{\class{wxTCPConnection}}\label{wxtcpconnection}
+
+A wxTCPClient object represents the connection between a client and a server.
+It emulates a DDE-style protocol, but uses TCP/IP which is available on most platforms.
+
+A DDE-based implementation for Windows is available using \helpref{wxDDEConnection}{wxddeconnection}.
+
+A wxTCPConnection object can be created by making a connection using a\rtfsp
+\helpref{wxTCPClient}{wxtcpclient} object, or by the acceptance of a connection by a\rtfsp
+\helpref{wxTCPServer}{wxtcpserver} object. The bulk of a conversation is controlled by
+calling members in a {\bf wxTCPConnection} object or by overriding its
+members.
+
+An application should normally derive a new connection class from
+wxTCPConnection, in order to override the communication event handlers
+to do something interesting.
+
+\wxheading{Derived from}
+
+wxConnectionBase\\
+\helpref{wxObject}{wxobject}
+
+\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{wxTCPClient}{wxtcpclient}, \helpref{wxTCPServer}{wxtcpserver}, \helpref{Interprocess communications overview}{ipcoverview}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxTCPConnection::wxTCPConnection}
+
+\func{}{wxTCPConnection}{\void}
+
+\func{}{wxTCPConnection}{\param{char* }{buffer}, \param{int}{ size}}
+
+Constructs a connection object. If no user-defined connection object is
+to be derived from wxTCPConnection, 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{wxTCPServer::OnAcceptConnection}{wxtcpserveronacceptconnection}\rtfsp
+and/or \helpref{wxTCPClient::OnMakeConnection}{wxtcpclientonmakeconnection} members should be replaced by
+functions which construct the new connection object. If the arguments of
+the wxTCPConnection 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{wxTCPConnection::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{wxTCPConnection::OnAdvise}{wxtcpconnectiononadvise}
+member to be called. Returns TRUE if successful.
+
+\membersection{wxTCPConnection::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{wxTCPConnection::Poke}{wxtcpconnectionpoke} in that respect). Causes the
+server connection's \helpref{wxTCPConnection::OnExecute}{wxtcpconnectiononexecute} member to be
+called. Returns TRUE if successful.
+
+\membersection{wxTCPConnection::Disconnect}
+
+\func{bool}{Disconnect}{\void}
+
+Called by the client or server application to disconnect from the other
+program; it causes the \helpref{wxTCPConnection::OnDisconnect}{wxtcpconnectionondisconnect} 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{wxTCPConnection::OnAdvise}\label{wxtcpconnectiononadvise}
+
+\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{wxTCPConnection::OnDisconnect}\label{wxtcpconnectionondisconnect}
+
+\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{wxTCPConnection::OnExecute}\label{wxtcpconnectiononexecute}
+
+\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{wxTCPConnection::OnPoke}\label{wxtcpconnectiononpoke}
+
+\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{wxTCPConnection::OnRequest}\label{wxtcpconnectiononrequest}
+
+\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{wxTCPConnection::Request}{wxtcpconnectionrequest}. The server
+should respond by returning a character string from {\bf OnRequest},
+or NULL to indicate no data.
+
+\membersection{wxTCPConnection::OnStartAdvise}\label{wxtcpconnectiononstartadvise}
+
+\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{wxTCPConnection::OnStopAdvise}\label{wxtcpconnectiononstopadvise}
+
+\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{wxTCPConnection::Poke}\label{wxtcpconnectionpoke}
+
+\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{wxTCPConnection::OnPoke}{wxtcpconnectiononpoke} member
+to be called. Returns TRUE if successful.
+
+\membersection{wxTCPConnection::Request}\label{wxtcpconnectionrequest}
+
+\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{wxTCPConnection::OnRequest}{wxtcpconnectiononrequest} member to be called. Returns a
+character string (actually a pointer to the connection's buffer) if
+successful, NULL otherwise.
+
+\membersection{wxTCPConnection::StartAdvise}\label{wxtcpconnectionstartadvise}
+
+\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{wxTCPConnection::OnStartAdvise}{wxtcpconnectiononstartadvise}\rtfsp
+member to be called. Returns TRUE if the server okays it, FALSE
+otherwise.
+
+\membersection{wxTCPConnection::StopAdvise}\label{wxtcpconnectionstopadvise}
+
+\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{wxTCPConnection::OnStopAdvise}{wxtcpconnectiononstopadvise} member
+to be called. Returns TRUE if the server okays it, FALSE otherwise.
+
projects / wxWidgets.git / commitdiff
