QFtp

La classe QFtp fournit une implémentation du protocole FTP. Plus d'informations...

#include <QFtp>

Héritage

Hérite de QObject.

Description détaillée

La classe QFtp fournit une implémentation du protocole FTP.

Cette classe fournit une interface directe pour le FTP qui vous permet d'avoir plus de contrôles sur les requêtes. Cependant, pour les nouvelles applications, il est recommandé d'utiliser QNetworkAccessManager et QNetworkReply, car ces classes possèdent un système plus simple et une API plus puissante.

La classe travaille en asynchrone, il n'y a donc pas de fonctions bloquantes. Si une opération ne peut être exécutée immédiatement, la fonction se terminera d'emblée et l'opération sera planifiée pour une exécution ultérieure. Les résultats de cette opération de planification sont reportés via les signaux. Cette approche dépend de la boucle événementielle qui est en service.

Les opérations qui peuvent être planifiées (elles sont appelées « commandes » dans le reste de la documentation) sont les suivantes : connectToHost(), login(), close(), list(), cd(), get(), put(), remove(), mkdir(), rmdir(), rename() et rawCommand().

Toutes ces commandes retournent un identifiant unique qui vous permet de garder la trace de la commande qui est actuellement en cours d'exécution. Quand l'exécution d'une commande démarre, le signal commandStarted() avec l'identifiant de la commande est émis. Quand la commande est finie, le signal commandFinished() est émis avec l'identifiant de la commande et un booléen qui indique si la commande s'est finie avec une erreur.

Dans certains cas, vous voudrez peut-être exécuter une séquence de commandes, par exemple, si vous souhaitez vous connecter et vous loguer à un serveur FTP. Voici un petit exemple :

QFtp *ftp = new QFtp(parent);
ftp->connectToHost("ftp.trolltech.com");
ftp->login();

Dans ce cas, deux commandes FTP sont planifiées. Quand la dernière commande planifiée se termine, un signal done() est émis avec un argument booléen qui indique si la séquence s'est terminée avec une erreur.

Si une erreur se produit pendant l'exécution de l'une des commandes de séquence de commandes, toutes celles en attente (c'est-à-dire planifiées, mais pas encore exécutées) sont effacées et aucun signal n'est émis pour elles.

Certaines commandes, par exemple list(), émettent un signal additionnel pour annoncer leurs résultats.

Exemple : si vous voulez télécharger le fichier INSTALL depuis le serveur FTP de Trolltech, vous devez écrire ceci :

ftp->connectToHost("ftp.trolltech.com"); // id == 1
ftp->login(); // id == 2
ftp->cd("qt"); // id == 3
ftp->get("INSTALL"); // id == 4
ftp->close(); // id == 5

Pour cet exemple, la séquence de signaux suivante est émise (avec des petites variations, dépendant du trafic réseau, etc.) :

start(1)
stateChanged(HostLookup)
stateChanged(Connecting)
stateChanged(Connected)
finished(1, false)
start(2)
stateChanged(LoggedIn)
finished(2, false)
start(3)
finished(3, false)
start(4)
dataTransferProgress(0, 3798)
dataTransferProgress(2896, 3798)
readyRead()
dataTransferProgress(3798, 3798)
readyRead()
finished(4, false)
start(5)
stateChanged(Closing)
stateChanged(Unconnected)
finished(5, false)
done(false)

Le signal dataTransferProgress() dans l'exemple ci-dessus est utile si vous voulez afficher une barre de progression pour informer l'utilisateur sur l'état d'avancement du téléchargement. Le signal readRead() prévient quand des données sont prêtes à être lues. La quantité de données peut être obtenue avec la fonction bytesAvailable() et peut être lue avec les fonctions read() ou readAll().

Si le login échoue pour l'exemple ci-dessus, les signaux se présenteront comme suit :

start(1)
stateChanged(HostLookup)
stateChanged(Connecting)
stateChanged(Connected)
finished(1, false)
start(2)
finished(2, true)
done(true)

Vous pouvez obtenir des détails sur l'erreur avec les fonctions error() et errorString().

Pour le transfert de fichier, QFtp peut utiliser le mode actif ou passif, par défaut il utilise le mode passif ; voir la documentation setTransferMode() pour plus de détails à ce propos.

Appelez setProxy() pour que QFtp se connecte via un serveur proxy FTP.

Les fonctions currentId() et currentCommand() fournissent plus d'informations sur la commande en cours d'exécution.

Les fonctions hasPendingCommands() et clearPendingCommands() vous permettent de rechercher et d'effacer la liste d'attente des commandes.

Si vous êtes un développeur expérimenté dans le domaine du réseau et que vous voulez un contrôle complet, vous pouvez utiliser rawCommand() pour exécuter arbitrairement des commandes FTP.

Attention : l'actuelle version de QFtp ne supporte pas complètement les serveurs FTP non Unix.

Voir aussi QNetworkAccessManager, QNetworkRequest, QNetworkReply et l'exemple FTP.

Types membres

enum QFtp::Command

Cette énumération est utilisée comme valeur de retour pour la fonction currentCommand(). Cela vous permet d'effectuer des actions spécifiques pour des commandes. Par exemple, dans un client FTP, vous pouvez effacer la vue du répertoire quand une commande list() est lancée ; dans ce cas il vous suffit d'une simple vérification dans le slot connecté au signal start() si le currentCommand() est List.

Voir aussi currentCommand().

enum QFtp::Error

Cette énumération identifie l'erreur qui s'est produite.

enum QFtp::State

Cette énumération définit l'état de la connexion.

Voir aussi stateChanged() et state().

enum QFtp::TransferMode

Le FTP travaille avec deux connexions socket ; une pour les commandes et une autre pour le transfert de données. Tant que la connexion de commande est toujours engagée par le client, la seconde connexion peut être engagée par le client ou par le serveur.

Cette énumération définit si le client (mode passif) ou le serveur (mode actif) doivent mettre en place la connexion de données.

enum QFtp::TransferType

Cette énumération identifie les transferts de données utilisés avec les commandes get et put.

Fonctions membres

QFtp::QFtp ( QObject * parent = 0 )

Construit un objet QFtp avec le parent donné.

QFtp::~QFtp () [virtual]

Destructeur.

void QFtp::abort () [slot]

Interrompt la commande actuelle et supprime toutes les commandes planifiées.

S'il y a une commande inachevée (c'est-à-dire une commande pour laquelle le signal commandStarted() a été émis, mais pas commandFinished()), cette fonction envoie une commande ABORT au serveur. Quand le serveur répond que la commande est annulée, le signal commandFinished() avec l'argument error fixé à true est émis pour la commande. En raison du timing, il est possible que la commande ait déjà fini avant que la requête abort atteigne le serveur ; dans ce cas, le signal commandFinished() est émis avec l'argument error fixé à false.

Pour toutes les autres commandes qui sont touchées par abort(), aucun signal n'est émis.

Si vous ne lancez pas d'autres commandes FTP directement après le abort(), il n'y aura pas de commandes planifiées et le signal done() sera émis.

Attention : certains serveurs FTP, par exemple le démon BSD FTP (version 0.3), retourne à tort une réponse positive même si ABORT a eu lieu. Pour ces serveurs, le signal commandFinished() a son argument error fixé à false, même si la commande n'a pas été effectuée correctement.

Voir aussi clearPendingCommands().

qint64 QFtp::bytesAvailable () const

Retourne le nombre d'octets qui peuvent être lus sur les données du socket à ce moment.

Voir aussi get(), readyRead(), read() et readAll().

int QFtp::cd ( const QString & dir )

Change le répertoire de travail du serveur avec l'argument dir.

La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique qui est passé à commandStarted() et commandFinished().

Quand la commande est lancée le signal commandStarted() est émis. Quand la commande est finie, le signal commandFinished() est émis.

Voir aussi commandStarted() et commandFinished().

void QFtp::clearPendingCommands ()

Supprime toute les commandes en attente de la liste des commandes planifiées. Cela n'a aucun effet sur la commande en cours d'exécution. Si vous voulez l'arrêter aussi, utilisez abort().

Voir aussi hasPendingCommands() et abort().

int QFtp::close ()

Ferme la connexion au serveur FTP.

Le signal stateChanged() est émis quand l'état du processus de connexion change, par exemple de Closing à Unconnected.

La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique, passé à commandStarted() et commandFinished().

Quand la commande est lancée le signal commandStarted() est émis. Quand la commande est finie, le signal commandFinished() est émis.

Voir aussi stateChanged(), commandStarted() et commandFinished().

void QFtp::commandFinished ( int id, bool error ) [signal]

Le signal est émis quand le traitement de la commande est terminé, identifié par id. error vaut true si une erreur s'est produite durant le traitement, sinon false.

Voir aussi commandStarted(), done(), error() et errorString().

void QFtp::commandStarted ( int id ) [signal]

Le signal est émis quand le traitement démarre, identifié par id.

Voir aussi commandFinished() et done().

int QFtp::connectToHost ( const QString & host, quint16 port = 21 )

Se connecte au serveur FTP host utilisant le port défini par port.

Le signal stateChanged() est émis quand l'état du processus de connexion change, par exemple de HostLookup, à Unconnected, à Connected.

La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique qui est passé à commandStarted() et commandFinished().

Quand la commande est lancée le signal commandStarted() est émis. Quand la commande est finie, le signal commandFinished() est émis.

Voir aussi stateChanged(), commandStarted() et commandFinished().

Command QFtp::currentCommand () const

Retourne le type de commande de la commande FTP en cours d'exécution ou None s'il n'y en a aucune.

Voir aussi currentId().

QIODevice * QFtp::currentDevice () const

Retourne le pointeur QIODevice utilisé par la commande FTP pour lire ou stocker les données. S'il n'y a aucune commande en cours d'exécution ou si la commande n'est pas utilisée par un périphérique d'entrée / sortie, cette fonction retourne 0.

Cette fonction peut être utilisée pour supprimer le QIODevice dans le slot connecté au signal commandFinished().

Voir aussi get() et put().

int QFtp::currentId () const

Retourne l'identifiant de la commande FTP qui est en cours d'exécution ou 0 s'il n'y en a aucune.

Voir aussi currentCommand().

void QFtp::dataTransferProgress ( qint64 done, qint64 total ) [signal]

Le signal est émis en réponse à une requête get() ou put() pour indiquer la progression actuelle du téléchargement ou du téléversement.

done est la quantité de données qui ont déjà été transférées et total est la quantité totale de données devant être lues ou écrites. Il est possible que la classe QFtp ne soit pas en mesure de déterminer la quantité totale de données qui devraient être transférées, dans ce cas total vaut 0. (Si vous connectez ce signal à une QProgressBar, la barre de progression affichera un indicateur occupé si le total est de 0).

Attention : done et total ne sont pas nécessairement la taille en octets, car, pour de gros fichiers, ces valeurs peuvent être réduites pour éviter les débordements.

Voir aussi get(), put() et QProgressBar.

void QFtp::done ( bool error ) [signal]

Le signal est émis quand la dernière commande en attente est terminée (il est émis après le signal commandFinished() de la dernière commande). error vaut true si une erreur s'est produite durant le traitement, sinon false.

Voir aussi commandFinished(), error() et errorString().

Error QFtp::error () const

Retourne la dernière erreur qui s'est produite. Il est utile de savoir ce qui s'est passé lors de la réception d'un signal commandFinished() ou done() avec l'argument error fixé à true.

Si vous lancez une nouvelle commande, le statut d'erreur est remis à NoError.

QString QFtp::errorString () const

Retourne une description lisible par l'homme de la dernière erreur qui s'est produite. Il est utile de savoir ce qui s'est passé lors de la réception d'un signal commandFinished() ou done() avec l'argument error fixé à true.

La chaîne de caractères d'erreur est souvent (mais pas toujours) la réponse donnée par le serveur, donc il n'est pas toujours possible de traduire la chaîne de caractères. Si le message vient de Qt, la chaîne de caractères passe par tr().

int QFtp::get ( const QString & file, QIODevice * dev = 0, TransferType type = Binary )

Télécharge le fichier file du serveur.

Si dev est 0, alors le signal readyRead() est émis quand il y a des données prêtes à être lues. Vous pouvez alors lire les données avec les fonctions read() et readAll().

Si dev n'est pas 0, les données sont directement écrites dans le périphérique dev. Assurez-vous que le pointeur dev est valide pour la durée de l'opération (il est sans danger de le supprimer lorsque le signal commandFinished() est émis). Dans ce cas le signal readyRead() n'est pas émis et vous ne pouvez pas lire les données avec les fonctions read() et readAll().

Si vous ne lisez pas les données immédiatement lorsqu'elles deviennent disponibles, c'est-à-dire lorsque le signal readyRead() est émis, elles restent alors disponibles jusqu'à la prochaine commande lancée.

Par exemple, si vous voulez présenter les données à l'utilisateur dès qu'il y a quelque chose de disponible, connectez le signal readyRead() et lisez les données immédiatement ; d'autre part, si vous voulez seulement travailler avec l'ensemble des données, vous pouvez vous connecter au signal commandFinished() et lire les données quand la commande get() est finie.

Les données sont transférées en binaire ou en ASCII, cela dépend de la valeur de type.

La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique qui est passé à commandStarted() et commandFinished().

Quand la commande est lancée, le signal commandStarted() est émis. Quand la commande est finie, le signal commandFinished() est émis.

Voir aussi readyRead(), dataTransferProgress(), commandFinished() et commandStarted().

bool QFtp::hasPendingCommands () const

Retourne true s'il y a des commandes en attente qui n'ont pas encore été exécutées, sinon false.

La commande qui est en cours d'exécution n'est pas considérée comme une commande en attente.

Voir aussi clearPendingCommands() currentId() et currentCommand().

int QFtp::list ( const QString & dir = QString() )

Liste le contenu du répertoire dir sur le serveur FTP. Si dir est vide, elle liste le contenu du répertoire courant.

Le signal listInfo() est émis pour chaque entrée de répertoire trouvé.

La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique qui est passé à commandStarted() et commandFinished().

Quand la commande est lancée, le signal commandStarted() est émis. Quand la commande est finie, le signal commandFinished() est émis.

Voir aussi listInfo(), commandStarted() et commandFinished().

void QFtp::listInfo ( const QUrlInfo & i ) [signal]

Le signal est émis pour chaque entrée de répertoire trouvé de la commande list(). Les détails de l'entrée sont stockés dans i.

Voir aussi list().

int QFtp::login ( const QString & user = QString(), const QString & password = QString() )

Se logue sur le serveur FTP avec l'utilisateur user et le mot de passe password.

Le signal stateChanged() est émis quand l'état du processus de connexion change, par exemple LoggedIn.

La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique qui est passé à commandStarted() et commandFinished().

Quand la commande est lancée le signal commandStarted() est émis. Quand la commande est finie le signal commandFinished() est émis.

Voir aussi commandStarted() et commandFinished().

int QFtp::mkdir ( const QString & dir )

Crée un répertoire appelé dir sur le serveur.

La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique qui est passé à commandStarted() et commandFinished().

Quand la commande est lancée, le signal commandStarted() est émis. Quand la commande est finie, le signal commandFinished() est émis.

Voir aussi commandStarted() et commandFinished().

int QFtp::put ( QIODevice * dev, const QString & file, TransferType type = Binary )

Lit les données depuis le périphérique d'entrée/sortie dev et écrit les données dans le fichier file sur le serveur. Les données sont lues dans les morceaux du périphérique d'entrée/sortie, cette surcharge vous permet de transmettre de grandes quantités de données sans avoir besoin de lire toutes les données en mémoire à chaque fois.

Les données sont transférées en binaire ou en ASCII, cela dépend de la valeur de type.

Assurez-vous que le pointeur dev est valide pour la durée de l'opération (il n'y a pas de danger de le supprimer lorsque le signal commandFinished() est émis).

int QFtp::put ( const QByteArray & data, const QString & file, TransferType type = Binary )

Il s'agit d'une fonction membre surchargée.

Écrit une copie de data dans le fichier file sur le serveur. La progression du téléversement est reportée par le signal dataTransferProgress()]). Les données sont transférées en binaire ou en ASCII, cela dépend de ''type''. La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique qui est passé à [[#commandStarted() et commandFinished()]). Quand la commande est lancée, le signal [[#commandStarted() est émis. Quand la commande est finie, le signal commandFinished() est émis.

Étant donné que cette fonction prend une copie de data, vous pouvez vous débarrasser de votre copie lors du retour de la fonction.

Voir aussi dataTransferProgress(), commandStarted() et commandFinished().

int QFtp::rawCommand ( const QString & command )

Envoie une commande brute command sur le serveur. Ceci est utile pour avoir un accès bas niveau sur le FTP. Si l'opération que vous souhaitez effectuer est un équivalent d'une fonction QFtp, nous vous recommandons d'utiliser la fonction plutôt qu'une commande FTP brute. De plus, les fonctions sont plus faciles d'accès et plus sûres.

La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique qui est passé à commandStarted() et commandFinished().

Quand la commande est lancée, le signal commandStarted() est émis. Quand la commande est finie, le signal commandFinished() est émis.

Voir aussi rawCommandReply(), commandStarted() et commandFinished().

void QFtp::rawCommandReply ( int replyCode, const QString & detail ) [signal]

Le signal est émis en réponse à la fonction rawCommand(). replyCode est la réponse du code à 3 chiffres et detail est le texte qui suit le code de réponse.

Voir aussi rawCommand().

qint64 QFtp::read ( char * data, qint64 maxlen )

Lit maxlen octets de données du socket, les met dans data et retourne le nombre d'octets lus. Retourne -1 si une erreur s'est produite.

Voir aussi get(), readyRead(), bytesAvailable() et readAll().

QByteArray QFtp::readAll ()

Lit tous les octets disponibles sur le socket de données et les retourne dans un QByteArray.

Voir aussi get(), readyRead(), bytesAvailable() et read().

void QFtp::readyRead () [signal]

Le signal est émis en réponse à la commande get() quand il y a de nouvelles données a lire.

Si vous spécifiez un périphérique dans le deuxième argument de la commande get(), le signal n'est pas émis ; les données sont écrites instantanément dans le périphérique.

Vous pouvez lire les données avec les fonctions readAll() et read().

Le signal est utile si vous souhaitez traiter les données en morceaux dès qu'elles sont disponibles. Si vous êtes uniquement intéressé par les données complètes, connectez le signal commandFinished() et lisez les données.

Voir aussi get() read() readAll() et bytesAvailable().

int QFtp::remove ( const QString & file )

Supprime le fichier appelé file sur le serveur.

La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique qui est passé à commandStarted() et commandFinished().

Quand la commande est lancée, le signal commandStarted() est émis. Quand la commande est finie, le signal commandFinished() est émis.

Voir aussi commandStarted() et commandFinished().

int QFtp::rename ( const QString & oldname, const QString & newname )

Renomme le fichier appelé oldname en newname sur le serveur.

La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique qui est passé à commandStarted() et commandFinished().

Quand la commande est lancée, le signal commandStarted() est émis. Quand la commande est finie, le signal commandFinished() est émis.

Voir aussi commandStarted() et commandFinished().

int QFtp::rmdir ( const QString & dir )

Supprime le répertoire appelé dir sur le serveur.

La fonction n'est pas bloquante et se termine immédiatement avec une valeur de retour. La commande est planifiée et son exécution est effectuée de façon asynchrone. La fonction retourne un identifiant unique qui est passé à commandStarted() et commandFinished().

Quand la commande est lancée, le signal commandStarted() est émis. Quand la commande est finie, le signal commandFinished() est émis.

Voir aussi commandStarted() et commandFinished().

int QFtp::setProxy ( const QString & host, quint16 port )

Actionne l'utilisation du proxy FTP sur l'hôte host et sur le port port. Appelez cette fonction avec host vide pour désactiver le proxy.

QFtp ne supporte pas les serveurs proxy HTTP. Utilisez QNetworkAccessManager pour cela.

int QFtp::setTransferMode ( TransferMode mode )

Fixe le mode de transfert courant avec l'argument mode. Par défaut, il est fixé à QFtp::Passive.

Voir aussi QFtp::TransferMode.

State QFtp::state () const

Retourne l'état actuel de l'objet. Quand l'état change, le signal stateChanged() est émis.

Voir aussi State et stateChanged().

void QFtp::stateChanged ( int state ) [signal]

Le signal est émis quand l'état de la connexion change. L'argument state est le nouvel état de la connexion ; il est l'une des valeurs de State.

Il est généralement émis en réponse à une commande connectToHost() ou close() , mais il peut aussi être émis « spontanément », par exemple, lorsque le serveur ferme la connexion de manière inattendue.

Voir aussi connectToHost(), close(), state etState.

Remerciements

Merci à Mikael Sans pour la traduction et à Jonathan Courtois, Thibaut Cuvelier ainsi qu'à Jacques Thery pour leur relecture !