docs/latex/wx/tipc.tex

   1 \section{Interprocess communication overview}\label{ipcoverview}
   2
   3 Classes: \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEConnection}{wxddeconnection},
   4 \helpref{wxDDEClient}{wxddeclient},
   5 \helpref{wxTCPServer}{wxtcpserver}, \helpref{wxTCPConnection}{wxtcpconnection},
   6 \helpref{wxTCPClient}{wxtcpclient}
   7
   8 wxWindows has a number of different classes to help with interprocess communication
   9 and network programming. This section only discusses one family of classes - the DDE-like
  10 protocol - but here's a list of other useful classes:
  11
  12 \begin{itemize}\itemsep=0pt
  13 \item \helpref{wxSocketEvent}{wxsocketevent},
  14 \helpref{wxSocketBase}{wxsocketbase},
  15 \helpref{wxSocketClient}{wxsocketclient},
  16 \helpref{wxSocketServer}{wxsocketserver}: classes for the low-level TCP/IP API.
  17 \item \helpref{wxProtocol}{wxprotocol}, \helpref{wxURL}{wxurl}, \helpref{wxFTP}{wxftp}, wxHTTP: classes
  18 for programming popular Internet protocols.
  19 \end{itemize}
  20
  21 Further information on these classes will be available in due course.
  22
  23 Notice that by including {\tt <wx/ipc.h>} you may define convnient synonyms for
  24 the IPC classes: {\tt wxServer} for either {\tt wxDDEServer} or
  25 {\tt wxTCPServer} depending on whether DDE-based or socket-based implementation
  26 is used and the same thing for {\tt wxClient} and {\tt wxConnection}. By
  27 default, DDE implementation is used under Windows. If you want to use IPC
  28 between the different workstations you should define {\tt wxUSE\_DDE\_FOR\_IPC}
  29 as $0$ before including this header -- this will force using TCP/IP
  30 implementation even under Windows.
  31
  32
  33 wxWindows has a high-level protocol based on Windows DDE.
  34 There are two implementations of this DDE-like protocol:
  35 one using real DDE running on Windows only, and another using TCP/IP (sockets) that runs
  36 on most platforms. Since the API is the same apart from the names of the classes, you
  37 should find it easy to switch between the two implementations.
  38
  39 The following description refers to 'DDE' but remember that the equivalent wxTCP... classes
  40 can be used in much the same way.
  41
  42 Three classes are central to the DDE API:
  43
  44 \begin{enumerate}\itemsep=0pt
  45 \item wxDDEClient. This represents the client application, and is used
  46 only within a client program.
  47 \item wxDDEServer. This represents the server application, and is used
  48 only within a server program.
  49 \item wxDDEConnection. This represents the connection from the current
  50 client or server to the other application (server or client), and can be used
  51 in both server and client programs. Most DDE
  52 transactions operate on this object.
  53 \end{enumerate}
  54
  55 Messages between applications are usually identified by three variables:
  56 connection object, topic name and item name.  A data string is a fourth
  57 element of some messages. To create a connection (a conversation in
  58 Windows parlance), the client application sends the message
  59 MakeConnection to the client object, with a string service name to
  60 identify the server and a topic name to identify the topic for the
  61 duration of the connection. Under Unix, the service name may be either an
  62 integer port identifier in which case an Internet domain socket will be used
  63 for the communications or a valid file name (which shouldn't exist and will be
  64 deleted afterwards) in which case a Unix domain socket is created.
  65
  66 {\bf SECURITY NOTE:} Using Internet domain sockets if extremely insecure for
  67 IPC as there is absolutely no access control for them, use Unix domain sockets
  68 whenever possible!
  69
  70 The server then responds and either vetoes the connection or allows it.
  71 If allowed, a connection object is created which persists until the
  72 connection is closed.  The connection object is then used for subsequent
  73 messages between client and server.
  74
  75 To create a working server, the programmer must:
  76
  77 \begin{enumerate}\itemsep=0pt
  78 \item Derive a class from wxDDEServer.
  79 \item Override the handler OnAcceptConnection for accepting or rejecting a connection,
  80 on the basis of the topic argument. This member must create and return a connection
  81 object if the connection is accepted.
  82 \item Create an instance of your server object, and call Create to
  83 activate it, giving it a service name.
  84 \item Derive a class from wxDDEConnection.
  85 \item Provide handlers for various messages that are sent to the server
  86 side of a wxDDEConnection.
  87 \end{enumerate}
  88
  89 To create a working client, the programmer must:
  90
  91 \begin{enumerate}\itemsep=0pt
  92 \item Derive a class from wxDDEClient.
  93 \item Override the handler OnMakeConnection to create and return
  94 an appropriate connection object.
  95 \item Create an instance of your client object.
  96 \item Derive a class from wxDDEConnection.
  97 \item Provide handlers for various messages that are sent to the client
  98 side of a wxDDEConnection.
  99 \item When appropriate, create a new connection by sending a MakeConnection
 100 message to the client object, with arguments host name (processed in Unix only),
 101 service name, and topic name for this connection. The client object will call OnMakeConnection
 102 to create a connection object of the desired type.
 103 \item Use the wxDDEConnection member functions to send messages to the server.
 104 \end{enumerate}
 105
 106 \subsection{Data transfer}
 107
 108 These are the ways that data can be transferred from one application to
 109 another.
 110
 111 \begin{itemize}\itemsep=0pt
 112 \item {\bf Execute:} the client calls the server with a data string representing
 113 a command to be executed. This succeeds or fails, depending on the
 114 server's willingness to answer. If the client wants to find the result
 115 of the Execute command other than success or failure, it has to explicitly
 116 call Request.
 117 \item {\bf Request:} the client asks the server for a particular data string
 118 associated with a given item string. If the server is unwilling to
 119 reply, the return value is NULL. Otherwise, the return value is a string
 120 (actually a pointer to the connection buffer, so it should not be
 121 deallocated by the application).
 122 \item {\bf Poke:} The client sends a data string associated with an item
 123 string directly to the server. This succeeds or fails.
 124 \item {\bf Advise:} The client asks to be advised of any change in data
 125 associated with a particular item. If the server agrees, the server will
 126 send an OnAdvise message to the client along with the item and data.
 127 \end{itemize}
 128
 129 The default data type is wxCF\_TEXT (ASCII text), and the default data
 130 size is the length of the null-terminated string. Windows-specific data
 131 types could also be used on the PC.
 132
 133 \subsection{Examples}
 134
 135 See the sample programs {\it server}\/ and {\it client}\/ in the IPC
 136 samples directory.  Run the server, then the client. This demonstrates
 137 using the Execute, Request, and Poke commands from the client, together
 138 with an Advise loop: selecting an item in the server list box causes
 139 that item to be highlighted in the client list box.
 140
 141 \subsection{More DDE details}
 142
 143 A wxDDEClient object represents the client part of a client-server DDE
 144 (Dynamic Data Exchange) conversation (available in both
 145 Windows and Unix).
 146
 147 To create a client which can communicate with a suitable server,
 148 you need to derive a class from wxDDEConnection and another from wxDDEClient.
 149 The custom wxDDEConnection class will intercept communications in
 150 a `conversation' with a server, and the custom wxDDEServer is required
 151 so that a user-overridden \helpref{wxDDEClient::OnMakeConnection}{wxddeclientonmakeconnection} member can return
 152 a wxDDEConnection of the required class, when a connection is made.
 153
 154 For example:
 155
 156 \begin{verbatim}
 157 class MyConnection: public wxDDEConnection
 158 {
 159  public:
 160   MyConnection(void)::wxDDEConnection(ipc_buffer, 3999) {}
 161   ~MyConnection(void) { }
 162   bool OnAdvise(const wxString& topic, const wxString& item, char *data, int size, wxIPCFormat format)
 163   { wxMessageBox(topic, data); }
 164 };
 165
 166 class MyClient: public wxDDEClient
 167 {
 168  public:
 169   MyClient(void) {}
 170   wxConnectionBase *OnMakeConnection(void) { return new MyConnection; }
 171 };
 172
 173 \end{verbatim}
 174
 175 Here, {\bf MyConnection} will respond to \helpref{OnAdvise}{wxddeconnectiononadvise} messages sent
 176 by the server.
 177
 178 When the client application starts, it must create an instance of the derived wxDDEClient. In the following, command line
 179 arguments are used to pass the host name (the name of the machine the server is running
 180 on) and the server name (identifying the server process). Calling \helpref{wxDDEClient::MakeConnection}{wxddeclientmakeconnection}\rtfsp
 181 implicitly creates an instance of {\bf MyConnection} if the request for a
 182 connection is accepted, and the client then requests an {\it Advise} loop
 183 from the server, where the server calls the client when data has changed.
 184
 185 \begin{verbatim}
 186   wxString server = "4242";
 187   wxString hostName;
 188   wxGetHostName(hostName);
 189
 190   // Create a new client
 191   MyClient *client = new MyClient;
 192   connection = (MyConnection *)client->MakeConnection(hostName, server, "IPC TEST");
 193
 194   if (!connection)
 195   {
 196     wxMessageBox("Failed to make connection to server", "Client Demo Error");
 197     return NULL;
 198   }
 199   connection->StartAdvise("Item");
 200 \end{verbatim}
 201
 202 Note that it is no longer necessary to call wxDDEInitialize or wxDDECleanUp, since
 203 wxWindows will do this itself if necessary.
 204