docs/latex/wx/tipc.tex

   1 \section{Interprocess communication overview}\label{ipcoverview}
   2
   3 Classes: \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEConnection}{wxddeconnection},
   4 \rtfsp\helpref{wxDDEClient}{wxddeclient}.
   5
   6 TODO: rewrite.
   7
   8 The following describes how wxWindows implements DDE.  The following
   9 three classes are central.
  10
  11 \begin{enumerate}\itemsep=0pt
  12 \item wxDDEClient. This represents the client application, and is used
  13 only within a client program.
  14 \item wxDDEServer. This represents the server application, and is used
  15 only within a server program.
  16 \item wxDDEConnection. This represents the connection from the current
  17 client or server to the other application (server or client), and can be used
  18 in both server and client programs. Most DDE
  19 transactions operate on this object.
  20 \end{enumerate}
  21
  22 Messages between applications are usually identified by three variables:
  23 connection object, topic name and item name.  A data string is a fourth
  24 element of some messages. To create a connection (a conversation in
  25 Windows parlance), the client application sends the message
  26 MakeConnection to the client object, with a string service name to
  27 identify the server and a topic name to identify the topic for the
  28 duration of the connection. Under UNIX, the service name must contain an
  29 integer port identifier.
  30
  31 The server then responds and either vetos the connection or allows it.
  32 If allowed, a connection object is created which persists until the
  33 connection is closed.  The connection object is then used for subsequent
  34 messages between client and server.
  35
  36 To create a working server, the programmer must:
  37
  38 \begin{enumerate}\itemsep=0pt
  39 \item Derive a class from wxDDEServer.
  40 \item Override the handler OnAcceptConnection for accepting or rejecting a connection,
  41 on the basis of the topic argument. This member must create and return a connection
  42 object if the connection is accepted.
  43 \item Create an instance of your server object, and call Create to
  44 activate it, giving it a service name.
  45 \item Derive a class from wxDDEConnection.
  46 \item Provide handlers for various messages that are sent to the server
  47 side of a wxDDEConnection.
  48 \end{enumerate}
  49
  50 To create a working client, the programmer must:
  51
  52 \begin{enumerate}\itemsep=0pt
  53 \item Derive a class from wxDDEClient.
  54 \item Override the handler OnMakeConnection to create and return
  55 an appropriate connection object.
  56 \item Create an instance of your client object.
  57 \item Derive a class from wxDDEConnection.
  58 \item Provide handlers for various messages that are sent to the client
  59 side of a wxDDEConnection.
  60 \item When appropriate, create a new connection by sending a MakeConnection
  61 message to the client object, with arguments host name (processed in UNIX only),
  62 service name, and topic name for this connection. The client object will call OnMakeConnection
  63 to create a connection object of the desired type.
  64 \item Use the wxDDEConnection member functions to send messages to the server.
  65 \end{enumerate}
  66
  67 \subsection{Data transfer}
  68
  69 These are the ways that data can be transferred from one application to
  70 another.
  71
  72 \begin{itemize}\itemsep=0pt
  73 \item {\bf Execute:} the client calls the server with a data string representing
  74 a command to be executed. This succeeds or fails, depending on the
  75 server's willingness to answer. If the client wants to find the result
  76 of the Execute command other than success or failure, it has to explicitly
  77 call Request.
  78 \item {\bf Request:} the client asks the server for a particular data string
  79 associated with a given item string. If the server is unwilling to
  80 reply, the return value is NULL. Otherwise, the return value is a string
  81 (actually a pointer to the connection buffer, so it should not be
  82 deallocated by the application).
  83 \item {\bf Poke:} The client sends a data string associated with an item
  84 string directly to the server. This succeeds or fails.
  85 \item {\bf Advise:} The client asks to be advised of any change in data
  86 associated with a particular item. If the server agrees, the server will
  87 send an OnAdvise message to the client along with the item and data.
  88 \end{itemize}
  89
  90 The default data type is wxCF\_TEXT (ASCII text), and the default data
  91 size is the length of the null-terminated string. Windows-specific data
  92 types could also be used on the PC.
  93
  94 \subsection{Examples}
  95
  96 See the sample programs {\it server}\/ and {\it client}\/ in the IPC
  97 samples directory.  Run the server, then the client. This demonstrates
  98 using the Execute, Request, and Poke commands from the client, together
  99 with an Advise loop: selecting an item in the server list box causes
 100 that item to be highlighted in the client list box.
 101
 102 See also the source for wxHelp, which is a DDE server, and the files
 103 wx\_help.h and wx\_help.cc which implement the client interface to
 104 wxHelp.
 105
 106 \subsection{More DDE details}
 107
 108 A wxDDEClient object represents the client part of a client-server DDE
 109 (Dynamic Data Exchange) conversation (available in both
 110 Windows and UNIX).
 111
 112 To create a client which can communicate with a suitable server,
 113 you need to derive a class from wxDDEConnection and another from wxDDEClient.
 114 The custom wxDDEConnection class will intercept communications in
 115 a `conversation' with a server, and the custom wxDDEServer is required
 116 so that a user-overriden \helpref{wxDDEClient::OnMakeConnection}{wxddeclientonmakeconnection} member can return
 117 a wxDDEConnection of the required class, when a connection is made.
 118
 119 For example:
 120
 121 \begin{verbatim}
 122 class MyConnection: public wxDDEConnection
 123 {
 124  public:
 125   MyConnection(void)::wxDDEConnection(ipc_buffer, 3999) {}
 126   ~MyConnection(void) { }
 127   Bool OnAdvise(char *topic, char *item, char *data, int size, int format)
 128   { wxMessageBox(topic, data); }
 129 };
 130
 131 class MyClient: public wxDDEClient
 132 {
 133  public:
 134   MyClient(void) {}
 135   wxDDEConnection *OnMakeConnection(void) { return new MyConnection; }
 136 };
 137
 138 \end{verbatim}
 139
 140 Here, {\bf MyConnection} will respond to \helpref{OnAdvise}{wxddeconnectiononadvise} messages sent
 141 by the server.
 142
 143 When the client application starts, it must first call \helpref{wxIPCInitialize}{wxipcinitialize}\rtfsp
 144 before creating an instance of the derived wxDDEClient. In the following, command line
 145 arguments are used to pass the host name (the name of the machine the server is running
 146 on) and the server name (identifying the server process). Calling \helpref{wxDDEClient::MakeConnection}{wxddeclientmakeconnection}\rtfsp
 147 implicitly creates an instance of {\bf MyConnection} if the request for a
 148 connection is accepted, and the client then requests an {\it Advise} loop
 149 from the server, where the server calls the client when data has changed.
 150
 151 \begin{verbatim}
 152   wxIPCInitialize();
 153
 154   char *server = "4242";
 155   char hostName[256];
 156   wxGetHostName(hostName, sizeof(hostName));
 157
 158   char *host = hostName;
 159
 160   if (argc > 1)
 161     server = argv[1];
 162   if (argc > 2)
 163     host = argv[2];
 164
 165   // Create a new client
 166   MyClient *client = new MyClient;
 167   the_connection = (MyConnection *)client->MakeConnection(host, server, "IPC TEST");
 168
 169   if (!the_connection)
 170   {
 171     wxMessageBox("Failed to make connection to server", "Client Demo Error");
 172     return NULL;
 173   }
 174   the_connection->StartAdvise("Item");
 175 \end{verbatim}
 176
 177