doc/src/examples/ftp.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example network/qftp
  30     \title FTP Example
  31
  32     \brief The FTP example demonstrates a simple FTP client that can be used
  33     to list the available files on an FTP server and download them.
  34
  35     \image ftp-example.png
  36
  37     The user of the example can enter the address or hostname of an
  38     FTP server in the \gui {Ftp Server} line edit, and then push the
  39     \gui Connect button to connect to it. A list of the server's
  40     top-level directory is then presented in the \gui {File List} tree
  41     view. If the selected item in the view is a file, the user can
  42     download it by pushing the \gui Download button. An item
  43     representing a directory can be double clicked with the mouse to
  44     show the contents of that directory in the view.
  45
  46     The functionality required for the example is implemented in the
  47     QFtp class, which provides an easy, high-level interface to the
  48     file transfer protocol. FTP operations are requested through
  49     \l{QFtp::Command}s. The operations are asynchronous. QFtp will
  50     notify us through signals when commands are started and finished.
  51
  52     We have one class, \c FtpWindow, which sets up the GUI and handles
  53     the FTP functionality. We will now go through its definition and
  54     implementation - focusing on the code concerning FTP. The code for
  55     managing the GUI is explained in other examples.
  56
  57     \section1 FtpWindow Class Definition
  58
  59     The \c FtpWindow class displays a window, in which the user can
  60     connect to and browse the contents of an FTP server. The slots of
  61     \c FtpWindow are connected to its widgets, and contain the
  62     functionality for managing the FTP connection. We also connect to
  63     signals in QFtp, which tells us when the
  64     \l{QFtp::Command}{commands} we request are finished, the progress
  65     of current commands, and information about files on the server.
  66
  67     \snippet examples/network/qftp/ftpwindow.h 0
  68
  69     We will look at each slot when we examine the \c FtpWindow
  70     implementation in the next section. We also make use of a few
  71     private variables:
  72
  73     \snippet examples/network/qftp/ftpwindow.h 1
  74
  75     The \c isDirectory hash keeps a history of all entries explored on
  76     the FTP server, and registers whether an entry represents a
  77     directory or a file. We use the QFile object to download files
  78     from the FTP server.
  79
  80     \section1 FtpWindow Class Implementation
  81
  82     We skip the \c FtpWindow constructor as it only contains code for
  83     setting up the GUI, which is explained in other examples.
  84
  85     We move on to the slots, starting with \c connectOrDisconnect().
  86
  87     \snippet examples/network/qftp/ftpwindow.cpp 0
  88
  89     If \c ftp is already pointing to a QFtp object, we QFtp::Close its
  90     FTP connection and delete the object it points to. Note that we do
  91     not delete the object using standard C++ \c delete as we need it
  92     to finish its abort operation.
  93
  94     \dots
  95     \snippet examples/network/qftp/ftpwindow.cpp 1
  96
  97     If we get here, \c connectOrDisconnect() was called to establish a
  98     new FTP connection. We create a new QFtp for our new connection,
  99     and connect its signals to slots in \c FtpWindow. The
 100     \l{QFtp::}{listInfo()} signal is emitted whenever information
 101     about a single file on the sever has been resolved. This signal is
 102     sent when we ask QFtp to \l{QFtp::}{list()} the contents of a
 103     directory. Finally, the \l{QFtp::}{dataTransferProgress()} signal
 104     is emitted repeatedly during an FTP file transfer, giving us
 105     progress reports.
 106
 107     \snippet examples/network/qftp/ftpwindow.cpp 2
 108
 109     The \gui {Ftp Server} line edit contains the IP address or
 110     hostname of the server to which we want to connect. We first check
 111     that the URL is a valid FTP sever address. If it isn't, we still
 112     try to connect using the plain text in \c ftpServerLineEdit. In
 113     either case, we assume that port \c 21 is used.
 114
 115     If the URL does not contain a user name and password, we use
 116     QFtp::login(), which will attempt to log into the FTP sever as an
 117     anonymous user. The QFtp object will now notify us when it has
 118     connected to the FTP server; it will also send a signal if it
 119     fails to connect or the username and password were rejected.
 120
 121     We move on to the \c downloadFile() slot:
 122
 123     \snippet examples/network/qftp/ftpwindow.cpp 3
 124     \dots
 125     \snippet examples/network/qftp/ftpwindow.cpp 4
 126
 127     We first fetch the name of the file, which we find in the selected
 128     item of \c fileList. We then start the download by using
 129     QFtp::get(). QFtp will send progress signals during the download
 130     and a signal when the download is completed.
 131
 132     \snippet examples/network/qftp/ftpwindow.cpp 5
 133
 134     QFtp supports canceling the download of files. We make sure that
 135     any file that is currently being written to is closed and removed,
 136     and tidy up by deleting the file object.
 137
 138     \snippet examples/network/qftp/ftpwindow.cpp 6
 139
 140     The \c ftpCommandFinished() slot is called when QFtp has
 141     finished a QFtp::Command. If an error occurred during the
 142     command, QFtp will set \c error to one of the values in
 143     the QFtp::Error enum; otherwise, \c error is zero.
 144
 145     \snippet examples/network/qftp/ftpwindow.cpp 7
 146
 147     After login, the QFtp::list() function will list the top-level
 148     directory on the server. addToList() is connected to
 149     QFtp::listInfo(), and will be invoked for each entry in that
 150     directory.
 151
 152     \snippet examples/network/qftp/ftpwindow.cpp 8
 153
 154     When a \l{QFtp::}{Get} command is finished, a file has finished
 155     downloading (or an error occurred during the download).
 156
 157     \snippet examples/network/qftp/ftpwindow.cpp 9
 158
 159     After a \l{QFtp::}{List} command is performed, we have to check if
 160     no entries were found (in which case our \c addToList() function
 161     would not have been called).
 162
 163     Let's continue with the \c addToList() slot:
 164
 165     \snippet examples/network/qftp/ftpwindow.cpp 10
 166
 167     When a new file has been resolved during a QFtp::List command,
 168     this slot is invoked with a QUrlInfo describing the file. We
 169     create a separate row for the file in \c fileList. If \c fileList
 170     does not have a current item, we set the new item to be the
 171     current item.
 172
 173     \snippet examples/network/qftp/ftpwindow.cpp 11
 174
 175     The \c processItem() slot is called when an item is double clicked
 176     in the \gui {File List}. If the item represents a directory, we
 177     want to load the contents of that directory with QFtp::list().
 178
 179     \snippet examples/network/qftp/ftpwindow.cpp 12
 180
 181     \c cdToParent() is invoked when the user requests to go to the
 182     parent directory of the one displayed in the file list. After
 183     changing the directory, we QFtp::List its contents.
 184
 185     \snippet examples/network/qftp/ftpwindow.cpp 13
 186
 187     The \c updateDataTransferProgress() slot is called regularly by
 188     QFtp::dataTransferProgress() when a file download is in progress.
 189     We use a QProgressDialog to show the download progression to the
 190     user.
 191
 192     \snippet examples/network/qftp/ftpwindow.cpp 14
 193
 194     The \c enableDownloadButton() is called whenever the current item
 195     in \c fileList changes. If the item represents a file, the \gui
 196     {Enable Download} Button should be enabled; otherwise, it is
 197     disabled.
 198 */
 199