source: trunk/doc/src/examples/ftp.qdoc@ 846

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example network/qftp
    \title FTP Example

    The FTP example demonstrates a simple FTP client that can be used
    to list the available files on an FTP server and download them.

    \image ftp-example.png

    The user of the example can enter the address or hostname of an
    FTP server in the \gui {Ftp Server} line edit, and then push the
    \gui Connect button to connect to it. A list of the server's
    top-level directory is then presented in the \gui {File List} tree
    view. If the selected item in the view is a file, the user can
    download it by pushing the \gui Download button. An item
    representing a directory can be double clicked with the mouse to
    show the contents of that directory in the view.

    The functionality required for the example is implemented in the
    QFtp class, which provides an easy, high-level interface to the
    file transfer protocol. FTP operations are requested through
    \l{QFtp::Command}s. The operations are asynchronous. QFtp will
    notify us through signals when commands are started and finished.

    We have one class, \c FtpWindow, which sets up the GUI and handles
    the FTP functionality. We will now go through its definition and
    implementation - focusing on the code concerning FTP. The code for
    managing the GUI is explained in other examples.

    \section1 FtpWindow Class Definition

    The \c FtpWindow class displays a window, in which the user can
    connect to and browse the contents of an FTP server. The slots of
    \c FtpWindow are connected to its widgets, and contain the
    functionality for managing the FTP connection. We also connect to
    signals in QFtp, which tells us when the
    \l{QFtp::Command}{commands} we request are finished, the progress
    of current commands, and information about files on the server.

    \snippet examples/network/qftp/ftpwindow.h 0

    We will look at each slot when we examine the \c FtpWindow
    implementation in the next section. We also make use of a few
    private variables:

    \snippet examples/network/qftp/ftpwindow.h 1

    The \c isDirectory hash keeps a history of all entries explored on
    the FTP server, and registers whether an entry represents a
    directory or a file. We use the QFile object to download files
    from the FTP server. 

    \section1 FtpWindow Class Implementation

    We skip the \c FtpWindow constructor as it only contains code for
    setting up the GUI, which is explained in other examples.

    We move on to the slots, starting with \c connectOrDisconnect().

    \snippet examples/network/qftp/ftpwindow.cpp 0

    If \c ftp is already pointing to a QFtp object, we QFtp::Close its
    FTP connection and delete the object it points to. Note that we do
    not delete the object using standard C++ \c delete as we need it
    to finish its abort operation.

    \dots
    \snippet examples/network/qftp/ftpwindow.cpp 1

    If we get here, \c connectOrDisconnect() was called to establish a
    new FTP connection. We create a new QFtp for our new connection,
    and connect its signals to slots in \c FtpWindow. The
    \l{QFtp::}{listInfo()} signal is emitted whenever information
    about a single file on the sever has been resolved. This signal is
    sent when we ask QFtp to \l{QFtp::}{list()} the contents of a
    directory. Finally, the \l{QFtp::}{dataTransferProgress()} signal
    is emitted repeatedly during an FTP file transfer, giving us