From: Julian Smart Date: Fri, 6 Sep 2002 22:38:25 +0000 (+0000) Subject: Added missing rejigged IPC Latex files X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/47610ec22ab01dbc09307a88ab67c1c95f6ee3b1?ds=inline Added missing rejigged IPC Latex files git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@17033 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/docs/latex/wx/ipcclint.tex b/docs/latex/wx/ipcclint.tex new file mode 100644 index 0000000000..8aeda255fe --- /dev/null +++ b/docs/latex/wx/ipcclint.tex @@ -0,0 +1,86 @@ +\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} + + + +\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. + diff --git a/docs/latex/wx/ipcconn.tex b/docs/latex/wx/ipcconn.tex new file mode 100644 index 0000000000..a369c052d9 --- /dev/null +++ b/docs/latex/wx/ipcconn.tex @@ -0,0 +1,220 @@ +\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} + + + +\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. + diff --git a/docs/latex/wx/ipcservr.tex b/docs/latex/wx/ipcservr.tex new file mode 100644 index 0000000000..6657e20ea8 --- /dev/null +++ b/docs/latex/wx/ipcservr.tex @@ -0,0 +1,67 @@ +\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} + + + +\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. +