--- /dev/null
+\section{\class{wxClient}}\label{wxddeclient}
+
+A wxClient object represents the client part of a client-server
+DDE-like (Dynamic Data Exchange) conversation. The actual
+DDE-based implementation using wxDDEClient is available on Windows
+only, but a platform-independent, socket-based version of this
+API is available using wxTCPClient, which has the same API.
+
+To create a client which can communicate with a suitable server,
+you need to derive a class from wxConnection and another from
+wxClient. The custom wxConnection class will intercept
+communications in a `conversation' with a server, and the custom
+wxClient is required so that a user-overridden
+\helpref{wxClient::OnMakeConnection}{wxddeclientonmakeconnection}
+member can return a wxConnection of the required class, when a
+connection is made. Look at the IPC sample and the
+\helpref{Interprocess communications overview}{ipcoverview} for
+an example of how to do this.
+
+\wxheading{Derived from}
+
+wxClientBase\\
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/ipc.h>
+
+\wxheading{See also}
+
+\helpref{wxServer}{wxddeserver},
+\helpref{wxConnection}{wxddeconnection}, \helpref{Interprocess communications overview}{ipcoverview}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxClient::wxClient}
+
+\func{}{wxClient}{\void}
+
+Constructs a client object.
+
+\membersection{wxClient::MakeConnection}\label{wxddeclientmakeconnection}
+
+\func{wxConnectionBase *}{MakeConnection}{\param{const wxString\& }{host}, \param{const wxString\& }{service}, \param{const wxString\& }{topic}}
+
+Tries to make a connection with a server by host (machine name
+under UNIX - use 'localhost' for same machine; ignored when using
+native DDE in Windows), service name and topic string. If the
+server allows a connection, a wxConnection object will be
+returned. The type of wxConnection returned can be altered by
+overriding the
+\helpref{wxClient::OnMakeConnection}{wxddeclientonmakeconnection}
+member to return your own derived connection object.
+
+Under Unix, the service name may be either an integer port
+identifier in which case an Internet domain socket will be used
+for the communications, or a valid file name (which shouldn't
+exist and will be deleted afterwards) in which case a Unix domain
+socket is created.
+
+{\bf SECURITY NOTE:} Using Internet domain sockets if extremely
+insecure for IPC as there is absolutely no access control for
+them, use Unix domain sockets whenever possible!
+
+\membersection{wxClient::OnMakeConnection}\label{wxddeclientonmakeconnection}
+
+\func{wxConnectionBase *}{OnMakeConnection}{\void}
+
+Called by \helpref{wxClient::MakeConnection}{wxddeclientmakeconnection}, by
+default this simply returns a new wxConnection object. Override
+this method to return a wxConnection descendant customised for the
+application.
+
+The advantage of deriving your own connection class is that it
+will enable you to intercept messages initiated by the server,
+such as \helpref{wxConnection::OnAdvise}{wxddeconnectiononadvise}. You
+may also want to store application-specific data in instances of
+the new class.
+
+\membersection{wxClient::ValidHost}
+
+\func{bool}{ValidHost}{\param{const wxString\& }{host}}
+
+Returns TRUE if this is a valid host name, FALSE otherwise. This always
+returns TRUE under MS Windows.
+
--- /dev/null
+\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.
+
--- /dev/null
+\section{\class{wxServer}}\label{wxddeserver}
+
+A wxServer object represents the server part of a client-server
+DDE-like (Dynamic Data Exchange) conversation. The actual
+DDE-based implementation using wxDDEServer is available on Windows
+only, but a platform-independent, socket-based version of this
+API is available using wxTCPServer, which has the same API.
+
+To create a server which can communicate with a suitable client,
+you need to derive a class from wxConnection and another from
+wxServer. The custom wxConnection class will intercept
+communications in a `conversation' with a client, and the custom
+wxServer is required so that a user-overridden \helpref{wxServer::OnAcceptConnection}{wxddeserveronacceptconnection}
+member can return a wxConnection of the required class, when a
+connection is made. Look at the IPC sample and the \helpref{Interprocess communications overview}{ipcoverview} for
+an example of how to do this.
+
+\wxheading{Derived from}
+
+wxServerBase
+
+\wxheading{Include files}
+
+<wx/ipc.h>
+
+\wxheading{See also}
+
+\helpref{wxClient}{wxddeclient},
+\helpref{wxConnection}{wxddeconnection}, \helpref{IPC
+overview}{ipcoverview}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxServer::wxServer}
+
+\func{}{wxServer}{\void}
+
+Constructs a server object.
+
+\membersection{wxServer::Create}
+
+\func{bool}{Create}{\param{const wxString\& }{service}}
+
+Registers the server using the given service name. Under Unix,
+the service name may be either an integer port identifier in
+which case an Internet domain socket will be used for the
+communications, or a valid file name (which shouldn't exist and
+will be deleted afterwards) in which case a Unix domain socket is
+created. FALSE is returned if the call failed (for example, the
+port number is already in use).
+
+\membersection{wxServer::OnAcceptConnection}\label{wxddeserveronacceptconnection}
+
+\func{virtual wxConnectionBase *}{OnAcceptConnection}{\param{const wxString\& }{topic}}
+
+When a client calls {\bf MakeConnection}, the server receives the
+message and this member is called. The application should derive a
+member to intercept this message and return a connection object of
+either the standard wxConnection type, or (more likely) of a
+user-derived type.
+
+If the topic is {\bf STDIO}, the application may wish to refuse the
+connection. Under UNIX, when a server is created the
+OnAcceptConnection message is always sent for standard input and
+output, but in the context of DDE messages it doesn't make a lot
+of sense.
+
projects / wxWidgets.git / commitdiff
