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