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 must contain an
  52 integer port identifier.
  53
  54 The server then responds and either vetos the connection or allows it.
  55 If allowed, a connection object is created which persists until the
  56 connection is closed.  The connection object is then used for subsequent
  57 messages between client and server.
  58
  59 To create a working server, the programmer must:
  60
  61 \begin{enumerate}\itemsep=0pt
  62 \item Derive a class from wxDDEServer.
  63 \item Override the handler OnAcceptConnection for accepting or rejecting a connection,
  64 on the basis of the topic argument. This member must create and return a connection
  65 object if the connection is accepted.
  66 \item Create an instance of your server object, and call Create to
  67 activate it, giving it a service name.
  68 \item Derive a class from wxDDEConnection.
  69 \item Provide handlers for various messages that are sent to the server
  70 side of a wxDDEConnection.
  71 \end{enumerate}
  72
  73 To create a working client, the programmer must:
  74
  75 \begin{enumerate}\itemsep=0pt
  76 \item Derive a class from wxDDEClient.
  77 \item Override the handler OnMakeConnection to create and return
  78 an appropriate connection object.
  79 \item Create an instance of your client object.
  80 \item Derive a class from wxDDEConnection.
  81 \item Provide handlers for various messages that are sent to the client
  82 side of a wxDDEConnection.
  83 \item When appropriate, create a new connection by sending a MakeConnection
  84 message to the client object, with arguments host name (processed in Unix only),
  85 service name, and topic name for this connection. The client object will call OnMakeConnection
  86 to create a connection object of the desired type.
  87 \item Use the wxDDEConnection member functions to send messages to the server.
  88 \end{enumerate}
  89
  90 \subsection{Data transfer}
  91
  92 These are the ways that data can be transferred from one application to
  93 another.
  94
  95 \begin{itemize}\itemsep=0pt
  96 \item {\bf Execute:} the client calls the server with a data string representing
  97 a command to be executed. This succeeds or fails, depending on the
  98 server's willingness to answer. If the client wants to find the result
  99 of the Execute command other than success or failure, it has to explicitly
 100 call Request.
 101 \item {\bf Request:} the client asks the server for a particular data string
 102 associated with a given item string. If the server is unwilling to
 103 reply, the return value is NULL. Otherwise, the return value is a string
 104 (actually a pointer to the connection buffer, so it should not be
 105 deallocated by the application).
 106 \item {\bf Poke:} The client sends a data string associated with an item
 107 string directly to the server. This succeeds or fails.
 108 \item {\bf Advise:} The client asks to be advised of any change in data
 109 associated with a particular item. If the server agrees, the server will
 110 send an OnAdvise message to the client along with the item and data.
 111 \end{itemize}
 112
 113 The default data type is wxCF\_TEXT (ASCII text), and the default data
 114 size is the length of the null-terminated string. Windows-specific data
 115 types could also be used on the PC.
 116
 117 \subsection{Examples}
 118
 119 See the sample programs {\it server}\/ and {\it client}\/ in the IPC
 120 samples directory.  Run the server, then the client. This demonstrates
 121 using the Execute, Request, and Poke commands from the client, together
 122 with an Advise loop: selecting an item in the server list box causes
 123 that item to be highlighted in the client list box.
 124
 125 \subsection{More DDE details}
 126
 127 A wxDDEClient object represents the client part of a client-server DDE
 128 (Dynamic Data Exchange) conversation (available in both
 129 Windows and Unix).
 130
 131 To create a client which can communicate with a suitable server,
 132 you need to derive a class from wxDDEConnection and another from wxDDEClient.
 133 The custom wxDDEConnection class will intercept communications in
 134 a `conversation' with a server, and the custom wxDDEServer is required
 135 so that a user-overriden \helpref{wxDDEClient::OnMakeConnection}{wxddeclientonmakeconnection} member can return
 136 a wxDDEConnection of the required class, when a connection is made.
 137
 138 For example:
 139
 140 \begin{verbatim}
 141 class MyConnection: public wxDDEConnection
 142 {
 143  public:
 144   MyConnection(void)::wxDDEConnection(ipc_buffer, 3999) {}
 145   ~MyConnection(void) { }
 146   bool OnAdvise(const wxString& topic, const wxString& item, char *data, int size, wxIPCFormat format)
 147   { wxMessageBox(topic, data); }
 148 };
 149
 150 class MyClient: public wxDDEClient
 151 {
 152  public:
 153   MyClient(void) {}
 154   wxConnectionBase *OnMakeConnection(void) { return new MyConnection; }
 155 };
 156
 157 \end{verbatim}
 158
 159 Here, {\bf MyConnection} will respond to \helpref{OnAdvise}{wxddeconnectiononadvise} messages sent
 160 by the server.
 161
 162 When the client application starts, it must create an instance of the derived wxDDEClient. In the following, command line
 163 arguments are used to pass the host name (the name of the machine the server is running
 164 on) and the server name (identifying the server process). Calling \helpref{wxDDEClient::MakeConnection}{wxddeclientmakeconnection}\rtfsp
 165 implicitly creates an instance of {\bf MyConnection} if the request for a
 166 connection is accepted, and the client then requests an {\it Advise} loop
 167 from the server, where the server calls the client when data has changed.
 168
 169 \begin{verbatim}
 170   wxString server = "4242";
 171   wxString hostName;
 172   wxGetHostName(hostName);
 173
 174   // Create a new client
 175   MyClient *client = new MyClient;
 176   connection = (MyConnection *)client->MakeConnection(hostName, server, "IPC TEST");
 177
 178   if (!connection)
 179   {
 180     wxMessageBox("Failed to make connection to server", "Client Demo Error");
 181     return NULL;
 182   }
 183   connection->StartAdvise("Item");
 184 \end{verbatim}
 185
 186 Note that it is no longer necessary to call wxDDEInitialize or wxDDECleanUp, since
 187 wxWindows will do this itself if necessary.
 188