added null pointer check and assert

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

\section{Interprocess communication overview}\label{ipcoverview}

Classes: \helpref{wxServer}{wxserver},
\helpref{wxConnection}{wxddeconnection},
\helpref{wxClient}{wxclient}
%\helpref{wxTCPServer}{wxtcpserver}, \helpref{wxTCPConnection}{wxtcpconnection},
%\helpref{wxTCPClient}{wxtcpclient}

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
\item \helpref{wxSocketEvent}{wxsocketevent},
\helpref{wxSocketBase}{wxsocketbase},
\helpref{wxSocketClient}{wxsocketclient},
\helpref{wxSocketServer}{wxsocketserver}: classes for the low-level TCP/IP API.
\item \helpref{wxProtocol}{wxprotocol}, \helpref{wxURL}{wxurl}, \helpref{wxFTP}{wxftp}, \helpref{wxHTTP}{wxhttp}: classes
for programming popular Internet protocols.
\end{itemize}

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 {\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}.

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.

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
\item wxClient. This represents the client application, and is used
only within a client program.
\item wxServer. This represents the server application, and is used
only within a server program.
\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}

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!

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
\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.
\end{enumerate}

To create a working client, the programmer must:

\begin{enumerate}\itemsep=0pt
\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 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}

\subsection{Data transfer}\label{datatransfer}

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
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.
\item {\bf 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).
\item {\bf Poke:} The client sends a data string associated with an item
string directly to the server. This succeeds or fails.
\item {\bf 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.
\end{itemize}

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.

\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
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.

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

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
\helpref{wxClient::OnMakeConnection}{wxddeclientonmakeconnection}
member can return a wxConnection of the required class, when a
connection is made.

For example:

\begin{verbatim}
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; }
};

\end{verbatim}

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";
  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");
\end{verbatim}