docs/doxygen/overviews/ipc.h

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