tqt3/doc/networking.doc

/*
    This is under development; the text is intended to replace
    network.doc.
*/

/*

\page networking.html

\title Network Module


\if defined(commercial)
This module is part of the \link commercialeditions.html TQt Enterprise Edition \endlink.
\endif

\tableofcontents

\section1 Introduction

Qt's networking classes make it straightforward to write
cross-platform networking applications. 

The networking classes can be divided into three groups:
\list 1
\i <b>High Level Network Programming</b>

TQUrlOperator, TQNetworkProtocol (and its TQFtp and TQHttp subclasses),
along with TQNetworkOperator, provide a simple high level API for
performing network operations in a network- and protocol-transparent
manner. For example, using TQUrlOperator, you can fetch a file across
the network, with just one line of code.
\omit
When TQHttpClient, TQFtpClient and TQHttpServer are available, we'll
refer to them her.
\endomit

\i <b>Medium Level Network Programming</b>

The TQSocket and TQServerSocket classes provide an easy-to-use 
API for client and server socket programming.

These classes require an event loop and must be used within an
application's GUI thread. They are ideal for end-user
applications that need network access, but they are not suitable for
console applications or for high performance daemons (services).

\i <b>Low Level Network Programming</b>

The TQSocketDevice and TQDns classes provide low level networking
access. TQSocketDevice can be used for UDP as well as TCP/IP, and can
be used in the non-GUI threads of a multi-threaded application. TQDns
performs simple hostname lookups, and also more specialised lookups,
such as Mx records, name Ptr records, etc.

These classes are suitable for all types of applications, from GUI
end-user applications to console applications and high performance
daemons (services). 

\endlist

The class documentation for each class presents the functionality and
usage of the class. In this document we will explore typical uses of
Qt's networking classes, showing how they are used in practice.

If you are using standard network protocols, such as FTP and HTTP, you
must register them before you can use TQUrlOperator. For example, put
the following call in your \c main() function, after creating your
TQApplication object:
\code
    tqInitNetworkProtocols();
\endcode

\section1 Network- and Protocol-Transparent Operations

Copying files is simple:
\code
    TQUrlOperator url;
    url.copy( TQString("ftp://ftp.trolltech.com/qt/source/qt-3.0.0.tar.gz"), "file:/tmp" );
\endcode
The first (source) URL is copied to the second (destination) URL. The
\link TQUrlOperator::copy() copy()\endlink function can be used to move
as well as copy.

TQUrlOperator also provides \link TQUrlOperator::listChildren()
listChildren()\endlink to obtain a list of the files in a given
directory, \link TQUrlOperator::mkdir() mkdir()\endlink, to create a
directory, as well as \link TQUrlOperator::rename() rename()\endlink
and \link TQUrlOperator::remove() remove()\endlink.

\code
    TQUrlOperator url;
    url.get( "http://www.somedomain.com/cgi-bin/lookup.pl?name=Buzz" );
\endcode
The \link TQUrlOperator::get() get()\endlink function is used to get
data, in this example from a query issued to a web site. There is also
a \link TQUrlOperator::put() put()\endlink function for writing data to
a remote file.

All operations are performed asynchronously. To find out the results
of an operation connect to the TQUrlOperator::finished() signal and
examine the TQNetworkOperation object passed to it.

The TQUrlOperator class also provides other functions and many more
signals to make it easy to track the progress of an operation. These
signals could be used, for example, to provide feedback on progress to
the user.

\section2 Example: Fetching All the Files in a Remote Directory

This example class is used as follows:
\code
    FetchFiles ff( "ftp://ftp.trolltech.com" );
    connect( &myWidget, stop(), &ff, stop() );
    connect( &ff, start(), &myWidget, start() );
    connect( &ff, startFile(), &myWidget, startFile() );
    connect( &ff, finishedFile(), &myWidget, finishedFile() );
    connect( &ff, finished(), &myWidget, finished() );
    connect( &ff, error(), &myWidget, error() );
    ff.fetch();
\endcode
The FetchFiles constructor takes a URL. When \c fetch() is called, the
FetchFiles object will iterate over every file it finds at the given
URL and download each one that is a regular file, (i.e. ignoring
directories). The FetchFiles object will emit signals as follows:
\list
\i start() -- emitted when it calls listChildren().
\i startFile( TQString ) -- emitted once for each file it starts to
copy, parameterised by the filename.
\i finishedFile( TQString ) -- emitted once for each file it finishes
copying, parameterised by the filename.
\i finished() -- emitted when all files have been read.
\i error() -- emitted if an error occurs.
\endlist

By connecting the signals to a widget you can keep the user notified
regarding progress.

The object also has a \c stop() slot, which you can connect to. This
is useful if you want the user to be able to cancel the operation
before it is complete.

### Rainer: is this a good example? If it is, I'll try to write the code.

\section3 The FetchFiles header file

\section3 The FetchFiles C++ file


\section1 Client/Server Applications that use Custom Protocols



In this section we'll present creation of the simple Information Server and two Clients - one that uses direct network programming, using TQServerSocket and TQSocket and the other one that uses TQNetworkProtocol subclass.

For that purpose we developed a very simple communication protocol between sever and clients.
Data is stored at server in hierarchical structure (similar to file systems) with folder (directory) and data (file) nodes. Our protocol uses only two directives - \c LIST and \c GET.
Server accepts only those two commands and returns one or more lines of the following format:

"xxxM line_content"
xxx represents the return message code, If character M (More) is '+' that means that it's not the last line of the response, and if M is ' ' (space) than it is the last line.

LIST directory_node_path
Response: "212+T child_address"

It lists all children of given directory node. It returns a line  for every child of the directory. T stands for Type and can be 'D' for directories or 'F' for file nodes. Last line of response will always be "212 ".

GET data_node_path
Response: "213+ one_data_line"

GET returns specified file line by line. Last line is always "213 ".

There are two more responses:
"500 File not found" - path points to non-existent node.
"550 Syntax error" - error in command parsing.


\section2 Info Server

First, we'll write a simple server that keeps information data in a tree structure and supports described communication protocol.
Data and supported operations handles \e InfoData class. We will present here just the public interface of that class:

\quotefile network/infoprotocol/infoserver/infodata.h

\skipto class InfoData
\printuntil };

\caption From \l network/infoprotocol/infoserver/infodata.h

\c InfoData::list lists all node children, while \c InfoData::get gets the data file. You can see this class implementation in file \l network/infoprotocol/infoserver/infodata.cpp. For this example, we just hard coded description of one small office network.

The main idea follows: Server creates the SimpleServer object (TQServerSocket subclass) which listens on the specified port and, when receives connection request from a client, creates ClientSocket object (TQSocket subclass) to handle that connection. ClientSocket recognizes two mentioned operations (list and get), performs them on InfoData object and returns generated response back to the client.

Let us look at Server implementation (\l network/infoprotocol/infoserver/server.cpp):
\quotefile network/infoprotocol/infoserver/server.cpp

\skipto ::SimpleServer
\printuntil exit
\printline }
\printline }

In the SimpleServer base class TQServerSocket constructor tries to bind itself to the given port. We use TQServerSocket::ok() to find out if that was successful and to detect eventual problems. After that it will monitor that port an call TQServerSocket::newConnection() every time a succesful connection with client is made.

\skipto newConnection
\printuntil }

This is reimplemented pure virtual function TQServerSocket::newConnection(). It creates ClientSocket which will be responsible for just established incoming connection with \e socket as the file descriptor.

\skipto ClientSocket
\printuntil }

ClientSocket constructor connects TQSocket::readyRead() signal which is emitted when something arrives from the Client. We also want to know when connection is terminated. When SimpleServer creates ClientSocket, connection is already established, so we just need to specify used socket with TQSocket::setSocket().

\skipto readClient
\printuntil }
\printline }

This slot is called every time we receive some data via socket.
Our communication protocol is textual and line oriented, and socket communication is asynchronous (don't forget that, we don't know when readyRead() will be emitted, or will that be at the end of the line), so we have to check with TQSocket::canReadLine() if the full line has been received. Because each input line presents one command in this protocol (list or get) we will process it and return generated answer through the socket back to the Client. 
Function processCommand() parses the input line and if it recognizes LIST or GET command, calls corresponding (InfoData*)info methods - list and get, otherwise creates appropriate error message.
TQSocket is a subclass of TQIODevice, thus we can use TQTextStream to read and write lines to it.



\skipto connectionClosed
\printuntil }

When connection closes, ClientSocket is not needed anymore, so it deletes itself. New one will be created upon new connection.


\section2 Info Client

Now, lets see the example of a Client that will use this Server, implemented through direct socket programming with TQSocket (\l network/infoprotocol/infoclient/client.cpp)

\quotefile network/infoprotocol/infoclient/client.cpp

\skipto ::connectToServer
\printuntil }

Because user connects to the server by request (btnConnect), connectToServer() dynamically creates new TQSocket which will carry out the connection with the server. Signal TQSocket::connected() is emitted after connection is successfully performed, and TQSocket::error(int) is emitted with error code on any error. Because communication is asynchronous, we can't check if TQSocket::connectToHost() succeeded or not. That's why we must rely on signals.


\skipto ::sendToServer
\printuntil os <<
\printline }

This function sends a command to the server. Notice that is uses TQTextStream to send data via socket.


\skipto ::socketReadyRead
\printuntil append( line.mid
\printline }
\printline }
\printline }

Here we parse responses from the server. It's worth noting again that the communication is asynchronous and it must not be assumed when and how the data will come. The fact that server socket sends all data lines at once (in one loop) does not mean that client socket will receive them as one package and emit one readyRead() signal. That is why we designed our protocol to have termination line , with M = ' ' (e.g. "213 "). In this example the line code will determine its destination (infoList or infoText), but in more advanced usage client would probably require some sort of the finite state machine, as we'll se in the next example.        


\skipto ::socketConnectionClosed()
\printuntil .arg
\printline }

It is not mandatory, of course, but it's good programming practice to cover errors and termination of the connection. Also, the best way to detect if the connecting to host succeeded (using connectToHost()) is use of an error(int) signal.


\section2 Info Url Client

It is time to illustrate how to use TQNetworkProtocol, TQNetworkOperation and TQUrlOperator to register our communication protocol and make it on par to already implemented protocols, like TQFtp, TQHttp and TQLocalFs. This will give us much larger flexibility in use and let us use TQt class that supports Network Protocols, e.g. TQFileDialog.

First, here is the header file in which Qip (our custom Network
Protocol) is declared (\c network/infoprotocol/infourlclient/qip.h):

\quotefile network/infoprotocol/infourlclient/qip.h

\skipto Qip
\printuntil };

TQNetworkProtocol is the base class for every Network Protocol class. Because this protocol uses network, we embedded one TQSocket* member variable to which we'll delegate network communication. Protocols that doesn't require to use network will do it on their own way - e.g. TQLocalFs uses TQDir, some data acquisition protocol may use serial or USB connection, only requirement is that protocol uses hierarchical structure and can be accessed using URLs (to have addressable nodes).

Let us go to the Qip implementation (\c
network/infoprotocol/infourlclient/qip.cpp):

\quotefile network/infoprotocol/infourlclient/qip.cpp

\skipto Qip
\printuntil }

Because we use TQSocket to perform network communication for us we have to initialize \e socket in the similar way we did in previous example.

\skipto supportedOperations
\printuntil }

We have to announce which of the supported operations our protocol supports. For the complete list of available operations, see TQNetworkProtocol::Operation.

\skipto checkConnection
\printuntil }

In this function protocol checks if the connection is established, and if not, tries to do so. Again, because of the asynchronous nature of the TQSocket, we don't know when and how connectToHost() will be finished, so we need to test if socket are still trying to make a connection.

\skipto operationListChildren
\printuntil GET
\printuntil ;
\printuntil }

Here we implement two supported operations. TQUrlOperator is class that initiated our protocol at first (after spotting that url starts with "qip://"), and can be approached with url() function. We'll use it to find path to our node. E.g. if url was "qip://my_server/network/fax/", path() would return "/network/fax/", while host() would be "my_server". For each operation, TQNetworkOperation object is created to hold its state and description. We will mark here that current operation started. See all operation states at TQNetworkProtocol::State.

\skipto ::socketReadyRead
\printuntil finished
\printuntil }
\printuntil }
\printuntil }

Implementation is very similar to previous example in addition that there are now some signal emitting requirements, so we had to use simple state machine here. In list operation we have to emit start(TQNetworkOperation*) before first child, and then to emit TQNetworkProtocol::newChild (const TQUrlInfo&, TQNetworkOperation*) for each child listed from the server. For get operation, we should emit TQNetworkProtocol::data (const TQByteArray&, TQNetworkOperation*) for each data chunk received (in this case, one text line). It is very important that \e every operation finishes with TQNetworkProtocol::finished(TQNetworkOperation*) signal!

\skipto error
\printuntil state
\printline }

In the case of an error we set error state, code and message, and, important enough and deserves to be mention again,  emit finished(TQNetworkOperation*) signal.

Now, when we have our TQNetworkProtocol Qip implemented, Info Url Client will be much simpler than in previous TQSocket example.
But, before we can use our new protocol, we have to register it first, so TQUrlOperators can react on it. We have done it in the main.cpp (\l network/infoprotocol/infourlclient/main.cpp):

\quotefile network/infoprotocol/infourlclient/main.cpp
\skipto register
\printline register

This registers Qip protocol and bonds it to prefix "qip". You can use tqInitNetworkProtocols() which registers pre coded Ftp (for "ftp") and Http ("http") protocols. Local file system (TQLocalFs) is always registered.

Client implementation (\c network/infoprotocol/infourlclient/client.cpp):

\quotefile network/infoprotocol/infourlclient/client.cpp
\skipto ::ClientInfo
\printuntil }

Qip protocol will send us data lines, our is just to pick them and process. Note that here we don't use finished() signal which we'd like to use if we want to know when the full file is received. In that case, in appropriate slot, we would like to check if it's ( operationInProgress()->operation() == TQNetworkProtocol::OpGet ).

\skipto ::downloadFile
\printuntil get
\printuntil }
\printuntil }

Here is where we use some TQNetworkProtocol magic. (TQUrlOperator)op is constructed from a selected url \e file, and then we just use TQUrlOperator::get() to fetch its content.

\skipto ::getOpenFileName
\printuntil return
\printuntil }

This function implements simple TQFileDialog that will serve us to browse through the nodes on the server and to select one data node to view. Starting url is "qip://localhost/" which indicates to TQFileDialog that we want to use Qip protocol served on the local server. We could also specify the exact port, e.g. "qip://my_server:123" will try to inquire my_server over port 123, otherwise the default port is used. 
We didn't use static function TQFileDialog::getOpenFileName() because under Windows and Mac OS X, it will usually use the native file dialog and not a TQFileDialog, in which case we wouldn't be able to use our protocol at all.


\section2 Creating a Custom Protocol

### Rainer: have we an example that I can use?

\section2 Client Applications that use Custom Protocols

### Rainer: have we an example that I can use?

\section2 Server Applications that use Custom Protocols

### Rainer: have we an example that I can use?

\section1 Client/Server Applications that use Standard Protocols

### Rainer: have we an example that I can use?

\section2 Client Applications that use Standard Protocols

### Rainer: have we an example that I can use?

\section2 Server Applications that use Standard Protocols

### Rainer: have we an example that I can use?

\section1 Inter-Process Communication between TQt Applications

### Rainer: have we an example that I can use?

\section1 Inter-Process Communication between TQt and non-Qt Applications

### Rainer: have we an example that I can use?


*/