fix warning about comparing (signed) -1 with (unsigned) in_addr_t under Solaris

[wxWidgets.git] / docs / latex / wx / tipc.tex

diff --git a/docs/latex/wx/tipc.tex b/docs/latex/wx/tipc.tex
index d2c74699d7a08d5da42b0cabc605ec0e846405bd..9edd9836bd7194a7e7f4728ec744814b5c411e08 100644 (file)
--- a/docs/latex/wx/tipc.tex
+++ b/docs/latex/wx/tipc.tex
@@ -1,102 +1,127 @@
 \section{Interprocess communication overview}\label{ipcoverview}
 
 \section{Interprocess communication overview}\label{ipcoverview}
 

-Classes: \helpref{wxDDEServer}{wxddeserver}, \helpref{wxDDEConnection}{wxddeconnection}, 
-\helpref{wxDDEClient}{wxddeclient}, 
-\helpref{wxTCPServer}{wxtcpserver}, \helpref{wxTCPConnection}{wxtcpconnection}, 
-\helpref{wxTCPClient}{wxtcpclient}
+Classes: \helpref{wxServer}{wxserver},
+\helpref{wxConnection}{wxddeconnection},
+\helpref{wxClient}{wxclient}
+%\helpref{wxTCPServer}{wxtcpserver}, \helpref{wxTCPConnection}{wxtcpconnection},
+%\helpref{wxTCPClient}{wxtcpclient}

 
 

-wxWindows 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:
+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:

 
 \begin{itemize}\itemsep=0pt
 
 \begin{itemize}\itemsep=0pt

-\item \helpref{wxSocketEvent}{wxsocketevent}, 
-\helpref{wxSocketBase}{wxsocketbase}, 
-\helpref{wxSocketClient}{wxsocketclient}, 
+\item \helpref{wxSocketEvent}{wxsocketevent},
+\helpref{wxSocketBase}{wxsocketbase},
+\helpref{wxSocketClient}{wxsocketclient},

 \helpref{wxSocketServer}{wxsocketserver}: classes for the low-level TCP/IP API.
 \helpref{wxSocketServer}{wxsocketserver}: classes for the low-level TCP/IP API.

-\item \helpref{wxProtocol}{wxprotocol}, \helpref{wxURL}{wxurl}, \helpref{wxFTP}{wxftp}, wxHTTP: classes
+\item \helpref{wxProtocol}{wxprotocol}, \helpref{wxURL}{wxurl}, \helpref{wxFTP}{wxftp}, \helpref{wxHTTP}{wxhttp}: classes

 for programming popular Internet protocols.
 \end{itemize}
 
 for programming popular Internet protocols.
 \end{itemize}
 

-Further information on these classes will be available in due course.
+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.

 
 

-wxWindows has 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 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 {\tt <wx/ipc.h>} you may define
+convenient synonyms for the IPC classes: {\tt wxServer} for either
+{\tt wxDDEServer} or {\tt wxTCPServer} depending on whether
+DDE-based or socket-based implementation is used and the same
+thing for {\tt wxClient} and {\tt wxConnection}.

 
 

-The following description refers to 'DDE' but remember that the equivalent wxTCP... classes
-can be used in much the same way.
+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 {\tt
+wxUSE\_DDE\_FOR\_IPC} as $0$ before including this header -- this
+will force using TCP/IP implementation even under Windows.

 
 

-Three classes are central to the DDE API:
+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:

 
 \begin{enumerate}\itemsep=0pt
 
 \begin{enumerate}\itemsep=0pt

-\item wxDDEClient. This represents the client application, and is used
+\item wxClient. This represents the client application, and is used

 only within a client program.
 only within a client program.

-\item wxDDEServer. This represents the server application, and is used
+\item wxServer. This represents the server application, and is used

 only within a server program.
 only within a server program.

-\item wxDDEConnection. This represents the connection from the current
-client or server to the other application (server or client), and can be used
-in both server and client programs. Most DDE
-transactions operate on this object.
+\item 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.

 \end{enumerate}
 
 \end{enumerate}
 

-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 sends the message
-MakeConnection to the client 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.
-
-{\bf SECURITY NOTE:} Using Internet domain sockets if extremely insecure for
+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.
+
+{\bf 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!
 
 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, a connection object is created which persists until the
-connection is closed.  The connection object is then used for subsequent
-messages between client and server.
+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:
 
 \begin{enumerate}\itemsep=0pt
 
 To create a working server, the programmer must:
 
 \begin{enumerate}\itemsep=0pt

-\item Derive a class from wxDDEServer.
-\item Override the handler OnAcceptConnection for accepting or rejecting a connection,
-on the basis of the topic argument. This member must create and return a connection
-object if the connection is accepted.
-\item Create an instance of your server object, and call Create to
+\item 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.
+\item 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.
+\item Create an instance of your server object and call Create to

 activate it, giving it a service name.
 activate it, giving it a service name.

-\item Derive a class from wxDDEConnection.
-\item Provide handlers for various messages that are sent to the server
-side of a wxDDEConnection.

 \end{enumerate}
 
 To create a working client, the programmer must:
 
 \begin{enumerate}\itemsep=0pt
 \end{enumerate}
 
 To create a working client, the programmer must:
 
 \begin{enumerate}\itemsep=0pt

-\item Derive a class from wxDDEClient.
-\item Override the handler OnMakeConnection to create and return
-an appropriate connection object.
+\item 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.
+\item Derive a class from wxClient, overriding OnMakeConnection to
+create and return an instance of the derived connection class.

 \item Create an instance of your client object.
 \item Create an instance of your client object.

-\item Derive a class from wxDDEConnection.
-\item Provide handlers for various messages that are sent to the client
-side of a wxDDEConnection.
-\item When appropriate, create a new connection by sending a MakeConnection
-message to the client object, with arguments host name (processed in Unix only),
-service name, and topic name for this connection. The client object will call OnMakeConnection
-to create a connection object of the desired type.
-\item Use the wxDDEConnection member functions to send messages to the server.
+\item When appropriate, create a new connection using
+\helpref{wxClient::MakeConnection}{wxclientmakeconnection},
+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
+\helpref{OnMakeConnection}{wxddeclientonmakeconnection} to create
+a connection object of the derived class if the connection is
+successful.
+\item Use the wxConnection member functions to send messages to the server.

 \end{enumerate}
 
 \end{enumerate}
 

-\subsection{Data transfer}
+\subsection{Data transfer}\label{datatransfer}

 
 

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

 
 \begin{itemize}\itemsep=0pt
 \item {\bf Execute:} the client calls the server with a data string representing
 
 \begin{itemize}\itemsep=0pt
 \item {\bf Execute:} the client calls the server with a data string representing


@@ -120,7 +145,7 @@ 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.
 
 size is the length of the null-terminated string. Windows-specific data
 types could also be used on the PC.
 

-\subsection{Examples}
+\subsection{Examples}\label{ipcexamples}

 
 See the sample programs {\it server}\/ and {\it client}\/ in the IPC
 samples directory.  Run the server, then the client. This demonstrates
 
 See the sample programs {\it server}\/ and {\it client}\/ in the IPC
 samples directory.  Run the server, then the client. This demonstrates


@@ -128,33 +153,33 @@ 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.
 
 with an Advise loop: selecting an item in the server list box causes
 that item to be highlighted in the client list box.
 

-\subsection{More DDE details}
+\subsection{More DDE details}\label{ddedetails}

 
 

-A wxDDEClient object represents the client part of a client-server DDE
-(Dynamic Data Exchange) conversation (available in both
+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,
 Windows and Unix).
 
 To create a client which can communicate with a suitable server,

-you need to derive a class from wxDDEConnection and another from wxDDEClient.
-The custom wxDDEConnection class will intercept communications in
-a `conversation' with a server, and the custom wxDDEServer is required
-so that a user-overridden \helpref{wxDDEClient::OnMakeConnection}{wxddeclientonmakeconnection} member can return
-a wxDDEConnection of the required class, when a connection is made.
+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
+\helpref{wxClient::OnMakeConnection}{wxddeclientonmakeconnection}
+member can return a wxConnection of the required class, when a
+connection is made.

 
 For example:
 
 \begin{verbatim}
 
 For example:
 
 \begin{verbatim}

-class MyConnection: public wxDDEConnection
-{
+class MyConnection: public wxConnection {

  public:
  public:

-  MyConnection(void)::wxDDEConnection(ipc_buffer, 3999) {}
+  MyConnection(void)::wxConnection() {}

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

-class MyClient: public wxDDEClient
-{
+class MyClient: public wxClient {

  public:
   MyClient(void) {}
   wxConnectionBase *OnMakeConnection(void) { return new MyConnection; }
  public:
   MyClient(void) {}
   wxConnectionBase *OnMakeConnection(void) { return new MyConnection; }


@@ -162,15 +187,20 @@ class MyClient: public wxDDEClient
 
 \end{verbatim}
 
 
 \end{verbatim}
 

-Here, {\bf MyConnection} will respond to \helpref{OnAdvise}{wxddeconnectiononadvise} messages sent
-by the server.
-
-When the client application starts, it must create an instance of the derived wxDDEClient. 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 \helpref{wxDDEClient::MakeConnection}{wxddeclientmakeconnection}\rtfsp
-implicitly creates an instance of {\bf MyConnection} if the request for a
-connection is accepted, and the client then requests an {\it Advise} loop
-from the server, where the server calls the client when data has changed.
+Here, {\bf MyConnection} will respond to
+\helpref{OnAdvise}{wxddeconnectiononadvise} 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
+\helpref{wxClient::MakeConnection}{wxddeclientmakeconnection}\rtfsp
+implicitly creates an instance of {\bf MyConnection} if the
+request for a connection is accepted, and the client then
+requests an {\it Advise} loop from the server (an Advise loop is
+where the server calls the client when data has changed).

 
 \begin{verbatim}
   wxString server = "4242";
 
 \begin{verbatim}
   wxString server = "4242";


@@ -189,6 +219,3 @@ from the server, where the server calls the client when data has changed.
   connection->StartAdvise("Item");
 \end{verbatim}
 
   connection->StartAdvise("Item");
 \end{verbatim}
 

-Note that it is no longer necessary to call wxDDEInitialize or wxDDECleanUp, since
-wxWindows will do this itself if necessary.
-