GAMBAS-BUCH 3.19.1

Beachten Sie: FTP oder „File Transfer Protocol“ (Dateiübertragungsprotokoll) ist ein unsicheres Protokoll zur Übertragung von Dateien zwischen zwei Systemen, das nur in begrenzten Fällen oder in Netzwerken verwendet werden sollte, denen Sie vertrauen.

Die Klasse stellt einen FTP-Client zur Verfügung, der das Herunterladen von Dateien von einem FTP-Server, das Hochladen von Dateien auf einen FTP-Server und das Senden von FTP-Befehlen zu einem FTP-Server ermöglicht. Die Klasse basiert auf der (Basis-)Klasse Curl in gb.net.curl.

So erzeugen Sie einen neuen FTP-Client:

Dim hFTPClient As FTPClient
hFTPClient = New FTPClient() As hFTPClient ' Event-Name

Die Klasse FTPClient verfügt über diese Eigenschaften:

Tabelle 24.2.3.0.1 : Eigenschaften der Klasse FTPClient

Beispiel für die Eigenschaft Lines:

Dim hFile As File
Dim sLine As String

hFile = Open "/var/log/syslog"
For Each sLine In hFile.Lines
  If InStr(sLine, "[drm]") Then Print sLine
Next

Werte der Status-Eigenschaft, die nur gelesen werden können:

Net.Inactive        (0)	Der FTP-Client ist inaktiv.
Net.ReceivingData   (4)	Der FTP-Client empfängt Daten aus dem Netzwerk.
Net.Connecting      (6)	Der FTP-Client verbindet sich mit dem FTP-Server.

Trat ein Fehler auf, dann ist der Status-Wert negativ. Der Wert des Status ist eigentlich -1000 vermindert um den libcurl-Fehlercode. Die meisten dieser Fehlercodes haben eine entsprechende Konstante in der Net-Klasse. Um zu wissen, was ein Fehlercode genau bedeutet, müssen Sie sich die libcurl-Fehlercodeliste unter https://curl.se/libcurl/c/libcurl-errors.html oder im Gambas-Club unter https://www.gambas-club.de/viewtopic.php?f=3&t=5580&p=13190&hilit=Curl+error#p13190 ansehen.

FTPClient hat in Abhängigkeit von der Async-Eigenschaft zwei Möglichkeiten zu arbeiten. Wenn Async den Wert TRUE hat, dann hält das Programm an, bis der angeforderte Vorgang abgeschlossen ist. Dies garantiert, dass das gewünschte Ergebnis fertiggestellt ist, bevor das Programm fortgesetzt wird. Sie erhalten aber keine Informationen während des laufenden Prozesses. Hat die Eigenschaft den Wert FALSE, so fordert das Programm die FTP-Operation vom Server an und setzt sie fort. In diesem Fall können Sie auf den Status des Prozesses zugreifen.

Für die Programmentwicklung ist es von Vorteil, wenn Sie die Debug-Eigenschaft auf True setzen. Dann sehen Sie stets das komplette Verbindungsprotokoll in der Konsole der IDE – so wie im folgenden Beispiel:

*   Trying 109.xyz.140.40:21...
* TCP_NODELAY set
* Connected to gambas-buch.de (109.xyz.140.40) port 21 (#0)
< 220 FTP Server ready.
> USER ftp_username
< 331 Password required for ftp_username
> PASS ftp_password
< 230 Zugriff gewaehrt fuer ftp_username
> PWD
< 257 "/" is the current directory
* Entry path is '/'
> CWD base
* ftp_perform ends with SECONDARY: 0
< 250 CWD command successful
> CWD dwiki
< 250 CWD command successful
> CWD data
< 250 CWD command successful
> CWD k3
< 250 CWD command successful
> CWD k3.1
< 250 CWD command successful
> EPSV
* Connect data stream passively
< 229 Entering Extended Passive Mode (|||65089|)
*   Trying 109.xyz.140.40:65089...
* TCP_NODELAY set
* Connecting to 109.xyz.140.40 (109.xyz.140.40) port 65089
* Connected to gambas-buch.de (109.xyz.140.40) port 21 (#0)
> TYPE I
< 200 Type set to I
> STOR start.txt
< 150 Opening BINARY mode data connection for start.txt
* We are completely uploaded and fine
* Remembering we are in dir "base/dwiki/data/k3/k3.1/"
< 226 Transfer complete
* Connection #0 to host gambas-buch.de left intact

Die Klasse FTPClient verfügt über folgende Methoden:

Tabelle 24.2.3.0.2 : Methoden der Klasse FTPClient

Die Klasse FTPClient verfügt über 6 Ereignisse:

Tabelle 24.2.3.0.3 : Ereignisse der Klasse FTPClient

Beispiel 1: Put()-Methode (Upload)

Der folgende Quelltext-Ausschnitt stammt aus einem Programm zum Einfügen von einzelnen Seiten im DokuWiki-Format in das Gambas-Buch auf gambas-buch.de:

Public hFTPClient As FtpClient
 
Public Sub Form_Open()
 
    MAdditional.CheckNetwork()
 
    hFTPClient = New FtpClient As "hFTPClient"
 
    hFTPClient.User = "ftp123"
    hFTPClient.Password = "pass456"
 
...
 
End
 
Public Sub btnFileUpLoad_Click()
 
    Dim bFTPClientStatus As Boolean = False
 
    FileUpload()
 
    Repeat
      Wait 0.001
      lblFTPStatus.Text = "FTP-Status = " & hFTPClient.Status
    Until bFTPClientStatus = bConnected
 
End
 
Public Sub hFTPClient_Connect()
    lblFTPStatus.Text = "FTP status: Connection to FTP server established!"
    bConnected = True
End
 
Public Sub hFTPClient_Finished()
 
    ProgressBar1.Value = 1
    btnFileUpLoad.Picture = Picture["leds/led_green_16x16.png"]
    lblFTPStatus.Text = "FTP status: Transfer complete"
 
    If bConnected = True Then hFTPClient.Close()
 
End
 
Public Sub hFTPClient_Progress()
 
'-- (Relative) Display of the uploaded bytes in relation to the size of the transferred file.
    If hFTPClient.TotalUploaded > 0 Then
       ProgressBar1.Value = hFTPClient.Uploaded / hFTPclient.TotalUploaded
    Endif
 
End
 
Public Sub hFTPClient_Error()
  Message.Error("<b><font color='DarkRed'>FTP:  ERROR</b></font><hr>" & hFTPClient.ErrorText)
End
 
Private Sub FileUpload()
 
    hFTPClient.URL = txbTargetURL.Text
'-- The Argument in the Put(sArg) method is the path of the file to be uploaded *on the local PC*
'-- Upload the selected DokuWiki source text file:
    hFTPClient.Put(txbSourcePath.Text)
 
End

Abbildung 24.2.3.0.1: Der Upload einer Datei war erfolgreich

Beachten Sie: Die Namen der LocalSource-Datei und der Target-Datei müssen nicht notwendigerweise gleich sein! Das gilt für den Upload genauso wie für den Download!

Fehler beim Upload von einzelnen Seiten werden vom Programm abgefangen und angezeigt:

Abbildung 24.2.3.0.2: Fehler beim Upload

Beispiel 2: Get()-Methode (Download)

Das Beispiel wurde gewählt, weil es eine Besonderheit präsentiert. Normalerweise geben Sie als Argument für die Get()-Methode einen kompletten Pfad für die Datei auf dem FTP-Server an, die vom FTP-Server in ein ausgewähltes Verzeichnis auf dem FTP-Client-System herunter geladen werden soll. Geben Sie jedoch einen kompletten Pfad für ein Verzeichnis auf dem FTP-Server an – der mit / enden muss – dann wird der Inhalt dieses Verzeichnisses zurückgegeben:

Abbildung 24.2.3.0.3: Inhalt eines ausgewählten Verzeichnisses auf dem FTP-Server

Der Quelltext für das Auslesen des Inhaltes eines ausgewählten Verzeichnisses auf dem FTP-Server ist erfreulich kurz und wird deshalb komplett angegeben. Sie können das Projekt selbst erproben, da die FTP-Konto-Daten für den öffentlichen FTP-Server mit angegeben werden:

' Gambas class file
 
Public hFTPClient As FtpClient
 
Public Sub Form_Open()
 
    FMain.Caption = "FTP-Server: Directory List"
 
    hFTPClient = New FtpClient As "hFTPClient"
 
    hFTPClient.User = "anonymous"      '-- Required: `anonymous`
    hFTPClient.Password = "wer@ist.da" '-- Required: An arbitrary, but syntactically correct email address
 
    hFTPClient.Debug = True
 
End
 
Public Sub hFTPClient_Error()
    txaOutput.Insert("FTP-Error-Text => " & hFTPClient.ErrorText & gb.NewLine)
    txaOutput.Insert("FTP Status: " & hFTPClient.Status & gb.NewLine)
End
 
Public Sub btnGetList_Click()
 
    Dim aList As String[]
    Dim iCount As Integer
 
    aList = GetList("ftp.uni-erlangen.de/pub/")
'-- aList = GetList("ftp.uni-erlangen.de/pub/ubuntu/")
 
    txaOutput.Clear()
 
    For iCount = 0 To aList.Max
      If iCount < aList.Max Then
         txaOutput.Insert(aList[iCount] & gb.NewLine)
      Else
         txaOutput.Insert(aList[iCount])
      Endif
    Next
 
End
 
Private Function GetList(argURL As String) As String[]
 
    Dim sTempFileName As String = Temp()
    Dim aList As String[]
 
    hFTPClient.URL = argURL
    hFTPClient.Async = False
    hFTPClient.Timeout = 3
 
    hFTPClient.Get(sTempFileName)
 
    aList = Split(File.Load(sTempFileName), gb.NewLine)
 
    Return aList
 
End

Die Hauptlast trägt die Funktion GetList(argURL). Als (Download-)Datei wird eine temporäre Datei benutzt, da deren Inhalt interessiert, der im Rückgabewert der Funktion gespeichert wird.

Beispiel 3: Exec()-Methode

In der praktischen Arbeit hat sich die Exec()-Methode u.a. zum Anlegen und zum Löschen eines Verzeichnisses auf dem FTP-Server bewährt:

  Inc Application.Busy
    hFTPClient.Async = False
    hFTPClient.Exec(["MKD " & "BaseDirectoryPath/DirectoryName_Create"])
  Dec Application.Busy

  Inc Application.Busy
    hFTPClient.Async = False
    hFTPClient.Exec(["RMD " & "BaseDirectoryPath/DirectoryName_Delete"])
  Dec Application.Busy

Eine Übersicht aller auf dem FTP-Server implementierten FTP-Befehle erhalten Sie mit folgendem Quelltext-Abschnitt. Berücksichtigen Sie, dass die Ausgabe nur dann in der Konsole der IDE angezeigt wird, wenn die Debug-Eigenschaft den Wert True hat:

  hFTPClient = New FtpClient As "hFTPClient"
 
  hFTPClient.User = "ftp123"
  hFTPClient.Password = "pass345"
  hFTPClient.URL = "gambas-buch.de"
  hFTPClient.Async = False
  hFTPClient.Timeout = 3
 
  hFTPClient.Debug = True
  hFTPClient.Exec(["HELP"])

Das ist die Ausgabe für den verwendeten FTP-Server (vsFTPd) des Autors:

> HELP
* ftp_perform ends with SECONDARY: 0
< 214-The following commands are recognized (* =>'s unimplemented):
<  CWD     XCWD    CDUP    XCUP    SMNT*   QUIT    PORT    PASV
<  EPRT    EPSV    ALLO*   RNFR    RNTO    DELE    MDTM    RMD
<  XRMD    MKD     XMKD    PWD     XPWD    SIZE    SYST    HELP
<  NOOP    FEAT    OPTS    HOST    CLNT    AUTH    CCC*    CONF*
<  ENC*    MIC*    PBSZ    PROT    TYPE    STRU    MODE    RETR
<  STOR    STOU    APPE    REST    ABOR    USER    PASS    ACCT*
<  REIN*   LIST    NLST    STAT    SITE    MLSD    MLST

Eine einzelne Datei löschen Sie auf dem FTP-Server so:

  Inc Application.Busy
    hFTPClient.Async = False
    hFTPClient.Exec(["DELE " & "BaseDirectoryPath/FileName"])
  Dec Application.Busy
 
  If hFTPClient.ErrorText Then
     Message.Error("ERROR:<br>" & hFTPClient.ErrorText)
  Endif

Es ist eine gute Idee, die erforderlichen FTP-Konto-Daten für ein FTP-Programm entweder durch einen einzelnen Dialog oder durch einen FTP-Konto-Manager mit mehreren Dialogen bereitzustellen. Anregungen für geeignete Dialoge oder für Konto-Manager finden Sie bereits im Gambas-Buch:

https://gambas-buch.de/doku.php?id=k12:k12.4:k12.4.4:k12.4.4.1:start
https://gambas-buch.de/doku.php?id=k24:k24.3:k24.3.4:start

Abbildung 24.2.3.0.4: Konto-Dialog für einen FTP-Server

Wenn Sie mehrere FTP-Server nutzen, dann wird ein FTP-Konto-Manager die richtige Wahl sein:

Abbildung 24.2.3.0.5: FTP-Konto-Manager

Eine kurze, auf das Wesentliche reduzierte Einführung in die Verwendung von Curl gibt es u.a. auf dieser Webseite (Stand: 24.01.2022):

http://www.mukeshkumar.net/articles/curl/how-to-use-curl-command-line-tool-with-ftp-and-sftp

Im nächsten Kapitel wird Ihnen ein Projekt für einen FTP-Client auf der Basis der Klasse FTPClient vorgestellt.