Exécuter une commande FTP (ftp.cmd)

Déclaration

result, err = ftp.cmd(URL, cmd [, connectTimeoutSec ])

Paramètres

• URL
  Type texte. URL FTP distante contenant le compte et le mot de passe. Pour les opérations sur des répertoires, utilisez une URL de répertoire se terminant par /.
• cmd
  Type texte. Une seule commande du protocole FTP, par exemple MKD test. Une table de commandes n'est pas prise en charge.
• connectTimeoutSec
  Nombre réel, facultatif. Délai de connexion en secondes, 10 par défaut. Ne limite pas la durée totale de la requête.

Valeurs de retour

• result
  Texte ou nil. Si la requête réussit, renvoie les données reçues, qui peuvent être une chaîne vide. Avec une URL de répertoire, il s'agit généralement de la liste du répertoire, et non du code d'état de la commande FTP ni de la réponse de la connexion de contrôle. Renvoie nil en cas d'échec.
• err
  Texte ou nil. En cas d'échec, renvoie une description textuelle de la cause de l'erreur. En cas de succès, aucune deuxième valeur n'est renvoyée ; la variable qui la reçoit vaut donc nil.

Description

Envoie une commande au serveur FTP pour effectuer des opérations telles que la création de répertoires. Ces opérations portent sur les fichiers ou les répertoires du serveur.

La commande s'exécute avant le passage au répertoire indiqué dans l'URL. Les chemins relatifs ont pour base le répertoire par défaut après connexion ; par exemple, MKD uploads/test crée test dans uploads sous ce répertoire. Ne comptez pas sur le chemin de l'URL pour changer le répertoire de travail de la commande. Les chemins de la commande sont envoyés directement, sans décodage des séquences d'échappement en pourcentage des URL.

MKD ne crée généralement qu'un niveau de répertoire ; le répertoire parent doit donc déjà exister. L'opération peut échouer si le répertoire existe déjà, si le compte n'a pas les droits nécessaires ou si le serveur ne prend pas en charge la commande. Pour créer plusieurs niveaux, appelez la fonction séparément pour chaque répertoire, du parent vers l'enfant.

Dans l'implémentation actuelle, si le texte de la commande contient LIST ou NLST en majuscules, la commande n'est pas envoyée ; seule la requête par défaut de l'URL est effectuée. Cela s'applique aussi lorsque ces sous-chaînes apparaissent dans un nom de répertoire. Ainsi, NLST ne passe pas à une liste contenant uniquement les noms de fichiers, et les arguments de LIST -a n'ont aucun effet.

Après l'exécution de la commande, la fonction demande toujours les données de l'URL ; avec une URL de répertoire, elle récupère aussi la liste du répertoire. Si la récupération de cette liste ou la connexion de données échoue ensuite, le répertoire peut déjà avoir été créé, mais la fonction renvoie tout de même nil et un message d'erreur.
Cette fonction peut céder l'exécution ; d'autres threads peuvent s'exécuter avant son retour.

Exemple simple

Placez le compte et le mot de passe dans l'URL. Le format est le suivant (les parties entre crochets sont facultatives) :

ftp://[user:password@]host[:port]/path

Si le compte ou le mot de passe contient @, : ou /, utilisez respectivement %40, %3A ou %2F pour les échapper. Les autres caractères non valides dans une URL peuvent être encodés en pourcentage. Par exemple, avec le compte havonz et le mot de passe 11@@22, créez test dans le répertoire par défaut après connexion :

local result, err = ftp.cmd("ftp://havonz:11%40%[email protected]/", "MKD test", 10)
if result == nil then
    sys.alert("Échec de la création : " .. tostring(err))
else
    sys.alert("Création réussie")
end

Exemple complexe

Créez successivement demo puis demo/logs ; aucun des deux ne doit encore exister. Arrêtez-vous si une étape échoue. Les répertoires créés précédemment ne sont pas supprimés automatiquement.

local url = "ftp://havonz:11%40%[email protected]/"

for _, path in ipairs({ "demo", "demo/logs" }) do
    local result, err = ftp.cmd(url, "MKD " .. path, 10)
    if result == nil then
        sys.alert("Échec de la création " .. path .. ": " .. tostring(err))
        return
    end
end

sys.alert("Répertoires créés")

Remarque : Le code ci-dessus utilise sys.alert, une fonction d'un autre chapitre.