X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0dbfd66d0b35352a0f60e7190b72815052b3d2d4..aaa6f9ba6bd0be1fe6a34800e6f753ffdc49900c:/docs/latex/wx/tipc.tex diff --git a/docs/latex/wx/tipc.tex b/docs/latex/wx/tipc.tex index d2c74699d7..9edd9836bd 100644 --- a/docs/latex/wx/tipc.tex +++ b/docs/latex/wx/tipc.tex @@ -1,102 +1,127 @@ \section{Interprocess communication overview}\label{ipcoverview} -Classes: \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEConnection}{wxddeconnection}, -\helpref{wxDDEClient}{wxddeclient}, -\helpref{wxTCPServer}{wxtcpserver}, \helpref{wxTCPConnection}{wxtcpconnection}, -\helpref{wxTCPClient}{wxtcpclient} +Classes: \helpref{wxServer}{wxserver}, +\helpref{wxConnection}{wxddeconnection}, +\helpref{wxClient}{wxclient} +%\helpref{wxTCPServer}{wxtcpserver}, \helpref{wxTCPConnection}{wxtcpconnection}, +%\helpref{wxTCPClient}{wxtcpclient} -wxWindows has a number of different classes to help with interprocess communication -and network programming. This section only discusses one family of classes - the DDE-like -protocol - but here's a list of other useful classes: +wxWidgets has a number of different classes to help with +interprocess communication and network programming. This section +only discusses one family of classes -- the DDE-like protocol -- +but here's a list of other useful classes: \begin{itemize}\itemsep=0pt -\item \helpref{wxSocketEvent}{wxsocketevent}, -\helpref{wxSocketBase}{wxsocketbase}, -\helpref{wxSocketClient}{wxsocketclient}, +\item \helpref{wxSocketEvent}{wxsocketevent}, +\helpref{wxSocketBase}{wxsocketbase}, +\helpref{wxSocketClient}{wxsocketclient}, \helpref{wxSocketServer}{wxsocketserver}: classes for the low-level TCP/IP API. -\item \helpref{wxProtocol}{wxprotocol}, \helpref{wxURL}{wxurl}, \helpref{wxFTP}{wxftp}, wxHTTP: classes +\item \helpref{wxProtocol}{wxprotocol}, \helpref{wxURL}{wxurl}, \helpref{wxFTP}{wxftp}, \helpref{wxHTTP}{wxhttp}: classes for programming popular Internet protocols. \end{itemize} -Further information on these classes will be available in due course. +wxWidgets' DDE-like protocol is a high-level protocol based on +Windows DDE. There are two implementations of this DDE-like +protocol: one using real DDE running on Windows only, and another +using TCP/IP (sockets) that runs on most platforms. Since the API +and virtually all of the behaviour is the same apart from the +names of the classes, you should find it easy to switch between +the two implementations. -wxWindows has a high-level protocol based on Windows DDE. -There are two implementations of this DDE-like protocol: -one using real DDE running on Windows only, and another using TCP/IP (sockets) that runs -on most platforms. Since the API is the same apart from the names of the classes, you -should find it easy to switch between the two implementations. +Notice that by including {\tt } you may define +convenient synonyms for the IPC classes: {\tt wxServer} for either +{\tt wxDDEServer} or {\tt wxTCPServer} depending on whether +DDE-based or socket-based implementation is used and the same +thing for {\tt wxClient} and {\tt wxConnection}. -The following description refers to 'DDE' but remember that the equivalent wxTCP... classes -can be used in much the same way. +By default, the DDE implementation is used under Windows. DDE works +within one computer only. If you want to use IPC between +different workstations you should define {\tt +wxUSE\_DDE\_FOR\_IPC} as $0$ before including this header -- this +will force using TCP/IP implementation even under Windows. -Three classes are central to the DDE API: +The following description refers to wx... but remember that the +equivalent wxTCP... and wxDDE... classes can be used in much the +same way. + +Three classes are central to the DDE-like API: \begin{enumerate}\itemsep=0pt -\item wxDDEClient. This represents the client application, and is used +\item wxClient. This represents the client application, and is used only within a client program. -\item wxDDEServer. This represents the server application, and is used +\item wxServer. This represents the server application, and is used only within a server program. -\item wxDDEConnection. This represents the connection from the current -client or server to the other application (server or client), and can be used -in both server and client programs. Most DDE -transactions operate on this object. +\item wxConnection. This represents the connection from the +client to the server - both the client and the server use an +instance of this class, one per connection. Most DDE transactions +operate on this object. \end{enumerate} -Messages between applications are usually identified by three variables: -connection object, topic name and item name. A data string is a fourth -element of some messages. To create a connection (a conversation in -Windows parlance), the client application sends the message -MakeConnection to the client object, with a string service name to -identify the server and a topic name to identify the topic for the -duration of the connection. 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 +Messages between applications are usually identified by three +variables: connection object, topic name and item name. A data +string is a fourth element of some messages. To create a +connection (a conversation in Windows parlance), the client +application uses wxClient::MakeConnection to send a message to the +server object, with a string service name to identify the server +and a topic name to identify the topic for the duration of the +connection. 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 is extremely insecure for IPC as there is absolutely no access control for them, use Unix domain sockets whenever possible! -The server then responds and either vetoes the connection or allows it. -If allowed, a connection object is created which persists until the -connection is closed. The connection object is then used for subsequent -messages between client and server. +The server then responds and either vetoes the connection or +allows it. If allowed, both the server and client objects create +wxConnection objects which persist until the connection is +closed. The connection object is then used for sending and +receiving subsequent messages between client and server - +overriding virtual functions in your class derived from +wxConnection allows you to handle the DDE messages. To create a working server, the programmer must: \begin{enumerate}\itemsep=0pt -\item Derive a class from wxDDEServer. -\item Override the handler OnAcceptConnection for accepting or rejecting a connection, -on the basis of the topic argument. This member must create and return a connection -object if the connection is accepted. -\item Create an instance of your server object, and call Create to +\item Derive a class from wxConnection, providing handlers for various messages sent to the server +side of a wxConnection (e.g. OnExecute, OnRequest, OnPoke). Only +the handlers actually required by the application need to be +overridden. +\item Derive a class from wxServer, overriding OnAcceptConnection +to accept or reject a connection on the basis of the topic +argument. This member must create and return an instance of the +derived connection class if the connection is accepted. +\item Create an instance of your server object and call Create to activate it, giving it a service name. -\item Derive a class from wxDDEConnection. -\item Provide handlers for various messages that are sent to the server -side of a wxDDEConnection. \end{enumerate} To create a working client, the programmer must: \begin{enumerate}\itemsep=0pt -\item Derive a class from wxDDEClient. -\item Override the handler OnMakeConnection to create and return -an appropriate connection object. +\item Derive a class from wxConnection, providing handlers for various +messages sent to the client side of a wxConnection (e.g. +OnAdvise). Only the handlers actually required by the application +need to be overridden. +\item Derive a class from wxClient, overriding OnMakeConnection to +create and return an instance of the derived connection class. \item Create an instance of your client object. -\item Derive a class from wxDDEConnection. -\item Provide handlers for various messages that are sent to the client -side of a wxDDEConnection. -\item When appropriate, create a new connection by sending a MakeConnection -message to the client object, with arguments host name (processed in Unix only), -service name, and topic name for this connection. The client object will call OnMakeConnection -to create a connection object of the desired type. -\item Use the wxDDEConnection member functions to send messages to the server. +\item When appropriate, create a new connection using +\helpref{wxClient::MakeConnection}{wxclientmakeconnection}, +with arguments host name (processed in Unix only, use `localhost' +for local computer), service name, and topic name for this +connection. The client object will call +\helpref{OnMakeConnection}{wxddeclientonmakeconnection} to create +a connection object of the derived class if the connection is +successful. +\item Use the wxConnection member functions to send messages to the server. \end{enumerate} -\subsection{Data transfer} +\subsection{Data transfer}\label{datatransfer} -These are the ways that data can be transferred from one application to -another. +These are the ways that data can be transferred from one +application to another. These are methods of wxConnection. \begin{itemize}\itemsep=0pt \item {\bf Execute:} the client calls the server with a data string representing @@ -120,7 +145,7 @@ The default data type is wxCF\_TEXT (ASCII text), and the default data size is the length of the null-terminated string. Windows-specific data types could also be used on the PC. -\subsection{Examples} +\subsection{Examples}\label{ipcexamples} See the sample programs {\it server}\/ and {\it client}\/ in the IPC samples directory. Run the server, then the client. This demonstrates @@ -128,33 +153,33 @@ using the Execute, Request, and Poke commands from the client, together with an Advise loop: selecting an item in the server list box causes that item to be highlighted in the client list box. -\subsection{More DDE details} +\subsection{More DDE details}\label{ddedetails} -A wxDDEClient object represents the client part of a client-server DDE -(Dynamic Data Exchange) conversation (available in both +A wxClient object initiates the client part of a client-server +DDE-like (Dynamic Data Exchange) conversation (available in both Windows and Unix). To create a client which can communicate with a suitable server, -you need to derive a class from wxDDEConnection and another from wxDDEClient. -The custom wxDDEConnection class will intercept communications in -a `conversation' with a server, and the custom wxDDEServer is required -so that a user-overridden \helpref{wxDDEClient::OnMakeConnection}{wxddeclientonmakeconnection} member can return -a wxDDEConnection of the required class, when a connection is made. +you need to derive a class from wxConnection and another from +wxClient. The custom wxConnection class will receive +communications in a `conversation' with a server. and the custom +wxServer 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. For example: \begin{verbatim} -class MyConnection: public wxDDEConnection -{ +class MyConnection: public wxConnection { public: - MyConnection(void)::wxDDEConnection(ipc_buffer, 3999) {} + MyConnection(void)::wxConnection() {} ~MyConnection(void) { } bool OnAdvise(const wxString& topic, const wxString& item, char *data, int size, wxIPCFormat format) { wxMessageBox(topic, data); } }; -class MyClient: public wxDDEClient -{ +class MyClient: public wxClient { public: MyClient(void) {} wxConnectionBase *OnMakeConnection(void) { return new MyConnection; } @@ -162,15 +187,20 @@ class MyClient: public wxDDEClient \end{verbatim} -Here, {\bf MyConnection} will respond to \helpref{OnAdvise}{wxddeconnectiononadvise} messages sent -by the server. - -When the client application starts, it must create an instance of the derived wxDDEClient. In the following, command line -arguments are used to pass the host name (the name of the machine the server is running -on) and the server name (identifying the server process). Calling \helpref{wxDDEClient::MakeConnection}{wxddeclientmakeconnection}\rtfsp -implicitly creates an instance of {\bf MyConnection} if the request for a -connection is accepted, and the client then requests an {\it Advise} loop -from the server, where the server calls the client when data has changed. +Here, {\bf MyConnection} will respond to +\helpref{OnAdvise}{wxddeconnectiononadvise} messages sent by the +server by displaying a message box. + +When the client application starts, it must create an instance of +the derived wxClient. In the following, command line arguments +are used to pass the host name (the name of the machine the +server is running on) and the server name (identifying the server +process). Calling +\helpref{wxClient::MakeConnection}{wxddeclientmakeconnection}\rtfsp +implicitly creates an instance of {\bf MyConnection} if the +request for a connection is accepted, and the client then +requests an {\it Advise} loop from the server (an Advise loop is +where the server calls the client when data has changed). \begin{verbatim} wxString server = "4242"; @@ -189,6 +219,3 @@ from the server, where the server calls the client when data has changed. connection->StartAdvise("Item"); \end{verbatim} -Note that it is no longer necessary to call wxDDEInitialize or wxDDECleanUp, since -wxWindows will do this itself if necessary. -