wxWidgets/docs/doxygen/overviews/ipc.h

/////////////////////////////////////////////////////////////////////////////
// Name:        ipc
// Purpose:     topic overview
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/*!

 @page ipc_overview Interprocess communication overview

 Classes: #wxServer,
 #wxConnection,
 #wxClient
 wxWidgets has a number of different classes to help with
 interprocess communication and network programming. This section
 only discusses one family of classes -- the DDE-like protocol --
 but here's a list of other useful classes:


  #wxSocketEvent,
 #wxSocketBase,
 #wxSocketClient,
 #wxSocketServer: classes for the low-level TCP/IP API.
  #wxProtocol, #wxURL, #wxFTP, #wxHTTP: classes
 for programming popular Internet protocols.


 wxWidgets' DDE-like protocol is a high-level protocol based on
 Windows DDE. There are two implementations of this DDE-like
 protocol: one using real DDE running on Windows only, and another
 using TCP/IP (sockets) that runs on most platforms. Since the API
 and virtually all of the behaviour is the same apart from the
 names of the classes, you should find it easy to switch between
 the two implementations.
 Notice that by including @c wx/ipc.h you may define
 convenient synonyms for the IPC classes: @c wxServer for either
 @c wxDDEServer or @c wxTCPServer depending on whether
 DDE-based or socket-based implementation is used and the same
 thing for @c wxClient and @c wxConnection.
 By default, the DDE implementation is used under Windows. DDE works
 within one computer only. If you want to use IPC between
 different workstations you should define @c wxUSE_DDE_FOR_IPC as 0 before including this header -- this
 will force using TCP/IP implementation even under Windows.
 The following description refers to wx... but remember that the
 equivalent wxTCP... and wxDDE... classes can be used in much the
 same way.
 Three classes are central to the DDE-like API:


  wxClient. This represents the client application, and is used
 only within a client program.
  wxServer. This represents the server application, and is used
 only within a server program.
  wxConnection. This represents the connection from the
 client to the server - both the client and the server use an
 instance of this class, one per connection. Most DDE transactions
 operate on this object.


 Messages between applications are usually identified by three
 variables: connection object, topic name and item name.  A data
 string is a fourth element of some messages. To create a
 connection (a conversation in Windows parlance), the client
 application uses wxClient::MakeConnection to send a message to the
 server object, with a string service name to identify the server
 and a topic name to identify the topic for the duration of the
 connection. Under Unix, the service name may be either an integer
 port identifier in which case an Internet domain socket will be
 used for the communications or a valid file name (which shouldn't
 exist and will be deleted afterwards) in which case a Unix domain
 socket is created.
 @b SECURITY NOTE: Using Internet domain sockets is extremely insecure for
 IPC as there is absolutely no access control for them, use Unix domain sockets
 whenever possible!
 The server then responds and either vetoes the connection or
 allows it. If allowed, both the server and client objects create
 wxConnection objects which persist until the connection is
 closed. The connection object is then used for sending and
 receiving subsequent messages between client and server -
 overriding virtual functions in your class derived from
 wxConnection allows you to handle the DDE messages.
 To create a working server, the programmer must:


  Derive a class from wxConnection, providing handlers for various messages sent to the server
 side of a wxConnection (e.g. OnExecute, OnRequest, OnPoke). Only
 the handlers actually required by the application need to be
 overridden.
  Derive a class from wxServer, overriding OnAcceptConnection
 to accept or reject a connection on the basis of the topic
 argument. This member must create and return an instance of the
 derived connection class if the connection is accepted.
  Create an instance of your server object and call Create to
 activate it, giving it a service name.


 To create a working client, the programmer must:


  Derive a class from wxConnection, providing handlers for various
 messages sent to the client side of a wxConnection (e.g.
 OnAdvise). Only the handlers actually required by the application
 need to be overridden.
  Derive a class from wxClient, overriding OnMakeConnection to
 create and return an instance of the derived connection class.
  Create an instance of your client object.
  When appropriate, create a new connection using
 wxClient::MakeConnection,
 with arguments host name (processed in Unix only, use 'localhost'
 for local computer), service name, and topic name for this
 connection. The client object will call
 #OnMakeConnection to create
 a connection object of the derived class if the connection is
 successful.
  Use the wxConnection member functions to send messages to the server.


 @ref datatransfer_overview
 #Examples
 @ref ddedetails_overview


 @section datatransfer Data transfer

 These are the ways that data can be transferred from one
 application to another. These are methods of wxConnection.


  @b Execute: the client calls the server with a data string representing
 a command to be executed. This succeeds or fails, depending on the
 server's willingness to answer. If the client wants to find the result
 of the Execute command other than success or failure, it has to explicitly
 call Request.
  @b Request: the client asks the server for a particular data string
 associated with a given item string. If the server is unwilling to
 reply, the return value is @NULL. Otherwise, the return value is a string
 (actually a pointer to the connection buffer, so it should not be
 deallocated by the application).
  @b Poke: The client sends a data string associated with an item
 string directly to the server. This succeeds or fails.
  @b Advise: The client asks to be advised of any change in data
 associated with a particular item. If the server agrees, the server will
 send an OnAdvise message to the client along with the item and data.


 The default data type is wxCF_TEXT (ASCII text), and the default data
 size is the length of the null-terminated string. Windows-specific data
 types could also be used on the PC.

 @section ipcexamples Examples

 See the sample programs @e server and @e client in the IPC
 samples directory.  Run the server, then the client. This demonstrates
 using the Execute, Request, and Poke commands from the client, together
 with an Advise loop: selecting an item in the server list box causes
 that item to be highlighted in the client list box.

 @section ddedetails More DDE details

 A wxClient object initiates the client part of a client-server
 DDE-like (Dynamic Data Exchange) conversation (available in both
 Windows and Unix).
 To create a client which can communicate with a suitable server,
 you need to derive a class from wxConnection and another from
 wxClient. The custom wxConnection class will receive
 communications in a 'conversation' with a server.  and the custom
 wxServer is required so that a user-overridden
 wxClient::OnMakeConnection
 member can return a wxConnection of the required class, when a
 connection is made.
 For example:

 @code
 class MyConnection: public wxConnection {
  public:
   MyConnection(void)::wxConnection() {}
   ~MyConnection(void) { }
   bool OnAdvise(const wxString& topic, const wxString& item, char *data, int size, wxIPCFormat format)
   { wxMessageBox(topic, data); }
 };

 class MyClient: public wxClient {
  public:
   MyClient(void) {}
   wxConnectionBase *OnMakeConnection(void) { return new MyConnection; }
 };
 @endcode

 Here, @b MyConnection will respond to
 #OnAdvise messages sent by the
 server by displaying a message box.
 When the client application starts, it must create an instance of
 the derived wxClient. In the following, command line arguments
 are used to pass the host name (the name of the machine the
 server is running on) and the server name (identifying the server
 process). Calling
 wxClient::MakeConnection
 implicitly creates an instance of @b MyConnection if the
 request for a connection is accepted, and the client then
 requests an @e Advise loop from the server (an Advise loop is
 where the server calls the client when data has changed).

 @code
 wxString server = "4242";
   wxString hostName;
   wxGetHostName(hostName);

   // Create a new client
   MyClient *client = new MyClient;
   connection = (MyConnection *)client-MakeConnection(hostName, server, "IPC TEST");

   if (!connection)
   {
     wxMessageBox("Failed to make connection to server", "Client Demo Error");
     return @NULL;
   }
   connection-StartAdvise("Item");
 @endcode

 */