From 252a2ec8b0f0f9cf20c947737087b24a8185b588 Mon Sep 17 00:00:00 2001 From: Michele Calgaro Date: Wed, 10 Jul 2024 18:56:16 +0900 Subject: Rename IO and network class nt* related files to equivalent tq* Signed-off-by: Michele Calgaro --- doc/networking.doc | 90 +++++++++++++++++++++++++++--------------------------- 1 file changed, 45 insertions(+), 45 deletions(-) (limited to 'doc/networking.doc') diff --git a/doc/networking.doc b/doc/networking.doc index 091dfcaf7..c4204f83c 100644 --- a/doc/networking.doc +++ b/doc/networking.doc @@ -25,19 +25,19 @@ The networking classes can be divided into three groups: \list 1 \i High Level Network Programming -QUrlOperator, QNetworkProtocol (and its QFtp and QHttp subclasses), -along with QNetworkOperator, provide a simple high level API for +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 QUrlOperator, you can fetch a file across +manner. For example, using TQUrlOperator, you can fetch a file across the network, with just one line of code. \omit -When QHttpClient, QFtpClient and QHttpServer are available, we'll +When TQHttpClient, TQFtpClient and TQHttpServer are available, we'll refer to them her. \endomit \i Medium Level Network Programming -The QSocket and QServerSocket classes provide an easy-to-use +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 @@ -47,9 +47,9 @@ console applications or for high performance daemons (services). \i Low Level Network Programming -The QSocketDevice and QDns classes provide low level networking -access. QSocketDevice can be used for UDP as well as TCP/IP, and can -be used in the non-GUI threads of a multi-threaded application. QDns +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. @@ -64,7 +64,7 @@ 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 QUrlOperator. For example, put +must register them before you can use TQUrlOperator. For example, put the following call in your \c main() function, after creating your QApplication object: \code @@ -75,33 +75,33 @@ QApplication object: Copying files is simple: \code - QUrlOperator url; + 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 QUrlOperator::copy() copy()\endlink function can be used to move +\link TQUrlOperator::copy() copy()\endlink function can be used to move as well as copy. -QUrlOperator also provides \link QUrlOperator::listChildren() +TQUrlOperator also provides \link TQUrlOperator::listChildren() listChildren()\endlink to obtain a list of the files in a given -directory, \link QUrlOperator::mkdir() mkdir()\endlink, to create a -directory, as well as \link QUrlOperator::rename() rename()\endlink -and \link QUrlOperator::remove() remove()\endlink. +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 - QUrlOperator url; + TQUrlOperator url; url.get( "http://www.somedomain.com/cgi-bin/lookup.pl?name=Buzz" ); \endcode -The \link QUrlOperator::get() get()\endlink function is used to get +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 QUrlOperator::put() put()\endlink function for writing data to +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 QUrlOperator::finished() signal and -examine the QNetworkOperation object passed to it. +of an operation connect to the TQUrlOperator::finished() signal and +examine the TQNetworkOperation object passed to it. -The QUrlOperator class also provides other functions and many more +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. @@ -151,7 +151,7 @@ before it is complete. -In this section we'll present creation of the simple Information Server and two Clients - one that uses direct network programming, using QServerSocket and QSocket and the other one that uses QNetworkProtocol subclass. +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. @@ -189,7 +189,7 @@ Data and supported operations handles \e InfoData class. We will present here ju \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 (QServerSocket subclass) which listens on the specified port and, when receives connection request from a client, creates ClientSocket object (QSocket 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. +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 @@ -199,26 +199,26 @@ Let us look at Server implementation (\l network/infoprotocol/infoserver/server. \printline } \printline } -In the SimpleServer base class QServerSocket constructor tries to bind itself to the given port. We use QServerSocket::ok() to find out if that was successful and to detect eventual problems. After that it will monitor that port an call QServerSocket::newConnection() every time a succesful connection with client is made. +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 QServerSocket::newConnection(). It creates ClientSocket which will be responsible for just established incoming connection with \e socket as the file descriptor. +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 QSocket::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 QSocket::setSocket(). +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 QSocket::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. +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. -QSocket is a subclass of TQIODevice, thus we can use TQTextStream to read and write lines to it. +TQSocket is a subclass of TQIODevice, thus we can use TQTextStream to read and write lines to it. @@ -230,14 +230,14 @@ When connection closes, ClientSocket is not needed anymore, so it deletes itself \section2 Info Client -Now, lets see the example of a Client that will use this Server, implemented through direct socket programming with QSocket (\l network/infoprotocol/infoclient/client.cpp) +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 QSocket which will carry out the connection with the server. Signal QSocket::connected() is emitted after connection is successfully performed, and QSocket::error(int) is emitted with error code on any error. Because communication is asynchronous, we can't check if QSocket::connectToHost() succeeded or not. That's why we must rely on signals. +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 @@ -265,7 +265,7 @@ It is not mandatory, of course, but it's good programming practice to cover erro \section2 Info Url Client -It is time to illustrate how to use QNetworkProtocol, QNetworkOperation and QUrlOperator to register our communication protocol and make it on par to already implemented protocols, like QFtp, QHttp and QLocalFs. This will give us much larger flexibility in use and let us use TQt class that supports Network Protocols, e.g. QFileDialog. +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): @@ -275,7 +275,7 @@ Protocol) is declared (\c network/infoprotocol/infourlclient/qip.h): \skipto Qip \printuntil }; -QNetworkProtocol is the base class for every Network Protocol class. Because this protocol uses network, we embedded one QSocket* 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. QLocalFs uses QDir, 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). +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): @@ -285,24 +285,24 @@ network/infoprotocol/infourlclient/qip.cpp): \skipto Qip \printuntil } -Because we use QSocket to perform network communication for us we have to initialize \e socket in the similar way we did in previous example. +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 QNetworkProtocol::Operation. +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 QSocket, 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. +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. QUrlOperator 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, QNetworkOperation object is created to hold its state and description. We will mark here that current operation started. See all operation states at QNetworkProtocol::State. +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 @@ -310,22 +310,22 @@ Here we implement two supported operations. QUrlOperator is class that initiated \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(QNetworkOperation*) before first child, and then to emit QNetworkProtocol::newChild (const QUrlInfo&, QNetworkOperation*) for each child listed from the server. For get operation, we should emit QNetworkProtocol::data (const TQByteArray&, QNetworkOperation*) for each data chunk received (in this case, one text line). It is very important that \e every operation finishes with QNetworkProtocol::finished(QNetworkOperation*) signal! +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(QNetworkOperation*) signal. +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 QNetworkProtocol Qip implemented, Info Url Client will be much simpler than in previous QSocket example. -But, before we can use our new protocol, we have to register it first, so QUrlOperators can react on it. We have done it in the main.cpp (\l network/infoprotocol/infourlclient/main.cpp): +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 (QLocalFs) is always registered. +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): @@ -333,21 +333,21 @@ Client implementation (\c 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() == QNetworkProtocol::OpGet ). +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 QNetworkProtocol magic. (QUrlOperator)op is constructed from a selected url \e file, and then we just use QUrlOperator::get() to fetch its content. +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 QFileDialog 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 QFileDialog 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 QFileDialog::getOpenFileName() because under Windows and Mac OS X, it will usually use the native file dialog and not a QFileDialog, in which case we wouldn't be able to use our protocol at all. +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 -- cgit v1.2.1