docs/doxygen/overviews/ipc.h

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