FTPConnect (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Internet browser
Security error in a secure FTPS connection
Required permissions
Required configuration

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

FTPConnect (Function)

In french: FTPConnecte

Connects the current computer to an FTP server (File Transfer Protocol).

The available secure connection modes are as follows:

FTPS: FTP secured according to the SSL protocol with implicit encryption.
FTPES: FTP secured according to the SSL protocol with explicit encryption.
SFTP: FTP secured by a SSH channel.

Versions 15 and later

This function is now available for Android applications.

New in version 15

This function is now available for Android applications.

Versions 18 and later

This function is now available in Android widget mode.

This function is now available for WINDEV applications in Linux.

This function is now available for WEBDEV sites in Linux.

This function is now available for iPhone/iPad applications.

New in version 18

This function is now available in Android widget mode.

This function is now available for WINDEV applications in Linux.

This function is now available for WEBDEV sites in Linux.

This function is now available for iPhone/iPad applications.

This function is now available in Android widget mode.

This function is now available for WINDEV applications in Linux.

This function is now available for WEBDEV sites in Linux.

This function is now available for iPhone/iPad applications.

Example

See additional examples

// Connect the current computer to the FTP server
ResConnect = FTPConnect("192.54.12.8")

Syntax

<Result> = FTPConnect(<Server> [, <User name> [, <Password> [, <Port number> [, <Type of connection> [, <Connection timeout> [, <Private key> [, <Key password>]]]]]]])

<Result>: Integer

Connection identifier,
0 during the first connection.
-1 if an error occurred. The details of the error are returned by ErrorInfo with the errCode or errMessage constant.
If an identification error occurs, ErrorInfo with the errCode constant returns the ftpErrorAuthentification constant.
This parameter is a Variant parameter that corresponds to the connection identifier or -1 if an error occurs.

<Server>: Character string

Name of FTP server ("ftp.cdrom.com" for example) or IP address of FTP server ("192.54.12.8" for example).
This parameter is used to define the protocol used:
if the server name starts with "ftp://", the connection is established in non-secure mode.
if the server name starts with "ftps://", the connection is established in secure mode according to the FTPS protocol (FTP secured by SSL with implicit encryption).
if the server name starts with "ftpes://", the connection is established in secure mode according to the FTPES protocol (FTP secured by SSL with explicit encryption).
if the server name starts with "sftp://", the connection is established in secure mode via a SSH channel according to the SFTP protocol.

<User name>: Optional character string

Name of user attempting to perform a named connection (user authentication on FTP server). This parameter is given by the administrator of FTP server.
Empty string ("") to perform an anonymous connection.

<Password>: Optional character string

User password: used to identify the user on the FTP server. This parameter is given by the administrator of FTP server.
This password corresponds to:
the specified <Password> if this parameter is not an empty string (""),
the email address of the user if <Username> is not specified or it is equal to an empty string (""),
an empty string ("") if this parameter is not specified and if <Username> does not correspond to an empty string ("").
Remark: If the password contains special characters, it may be necessary to convert it to UTF-8 using StringToUTF8.

<Port number>: Optional integer

Number of the port on which the server will be run. This parameter is given by the administrator of FTP server.
By default:
for a non-secure connection, this port is port 21.
for a secure connection in FTPS mode, this port is port 990.
for a secure connection in FTPES mode, this port is port 21.
for a secure connection in SFTP mode, this port is port 22.

<Type of connection>: Optional Integer constant

Type of connection to establish:
Versions 21 and later
ftpActiveMode
New in version 21
ftpActiveMode
ftpActiveMode (or False for compatibility) Active connection to the FTP server.
When transferring files, the client starts the transfer. This type of connection may be refused by some protected FTP servers.
Versions 21 and later
ftpExtendedPassiveMode
New in version 21
ftpExtendedPassiveMode
ftpExtendedPassiveMode Extended passive connection to the FTP server (EPSV mode).
When transferring files, the server takes the initiative for the transfer. This type of connection is used to step over some "firewalls".
If the server does not support the extended passive mode (the FEAT command is sent to the server to find out the capacity), the connection is crippled in simple passive mode.
Limitations:
This mode is not supported when using the "wininet" module of Windows (see FTPParameter): the connection is performed in ftpPassiveMode.
Constant not available.
This constant is identical to the ftpPassiveMode constant.
Versions 21 and later
ftpPassiveMode
New in version 21
ftpPassiveMode
ftpPassiveMode (or True for compatibility)
(Default value) Passive connection to the FTP server (PASV mode).
When transferring files, the server takes the initiative for the transfer. This type of connection is used to step over some "firewalls".
Remark: If the connection to the server is in IPV6, the connection will be performed in extended passive mode (because the passive mode does not support IPV6).
Versions 23 and later
ftpPassiveModeIgnoreIP
New in version 23
ftpPassiveModeIgnoreIP
ftpPassiveModeIgnoreIP Passive connection to the FTP server (PASV mode).
When transferring files in passive mode, the server sets the port and IP address for data transfer. With this parameter, only the port is taken into account. The IP address is ignored.
This type of connection allows the use of FTP servers that return non-routable IP addresses but are reachable via the connection IP address
Limitations:
This mode is not supported when using the "wininet" module of Windows (see FTPParameter): the connection is performed in ftpPassiveMode.
Constant not available.

<Connection timeout>: Optional integer or optional Duration

Number of seconds after which the request for connecting to the FTP server is canceled (20 by default). This timeout applies to all FTP operations performed on this connection. If no response is received from the server during the specified <Connection timeout>, FTPConnect returns -1.
Remark: This parameter can correspond to:
an integer corresponding to the number of seconds,
a Duration variable,
Versions 23 and later
the duration in a readable format (e.g., '1s').
New in version 23
the duration in a readable format (e.g., '1s').
the duration in a readable format (e.g., '1s').
This parameter corresponds to an integer.

<Private key>: Optional character string

Name and path of file corresponding to the private key used during a connection in SFTP mode. This file must have been generated in OpenSSH format.
If this parameter is not specified, the secure connection is using an authentication by <Username>/<Password>.

<Key password>: Optional ANSI character string

Password of file containing the private key used during a connection in SFTP mode.
If UNICODE strings are used at runtime ("Unicode" tab of the current configuration), the password must not be specified between quotation marks. It must be in a string variable declared in ANSI format.
If this parameter is not specified, the secure connection is using an authentication by <Username>/<Password>.

Remarks

Internet browser

FTPConnect requires Internet Explorer version 3 or later.

The modifications made to <Timeout> have no effect with some versions of Internet Explorer. It is a known problem of Microsoft components that is fixed in the more recent versions of Internet Explorer (version 5.1 and later).

Versions 18 and later

Security error in a secure FTPS connection

During a secure transaction, the function may fail due to security errors:

invalid certificate or certificate coming from an unknown company.
site name found in the certificate not corresponding to a server.
invalid or expired certificate date.

You have the ability to connect while ignoring these errors. To do so, use the FTP.IgnoreError variable:

Value of FTP.IgnoreError (these values can be combined)	Description

ftpIgnoreInvalidCertificate	The certificate is ignored.
ftpIgnoreExpiredCertificate	The certificate date is ignored.
ftpIgnoreInvalidCertificateName	The site name specified in the certificate is ignored.
ftpIgnoreRevocation	The certificate revocation is ignored.

// Example for error management

xnum is int
FTP.IgnoreError = ftpIgnoreExpiredCertificate + ftpIgnoreInvalidCertificate + ...
ftpIgnoreInvalidCertificateName + ftpIgnoreRévocation
xnum = FTPConnect("ftpes://My_Server_IP", "My_User", "My_Password", 21, True)
IF xnum =-1 THEN
Info(ErrorInfo(errMessage))
ELSE
Info("OK")
END

New in version 18

Security error in a secure FTPS connection

During a secure transaction, the function may fail due to security errors:

invalid certificate or certificate coming from an unknown company.
site name found in the certificate not corresponding to a server.
invalid or expired certificate date.

You have the ability to connect while ignoring these errors. To do so, use the FTP.IgnoreError variable:

Value of FTP.IgnoreError (these values can be combined)	Description

ftpIgnoreInvalidCertificate	The certificate is ignored.
ftpIgnoreExpiredCertificate	The certificate date is ignored.
ftpIgnoreInvalidCertificateName	The site name specified in the certificate is ignored.
ftpIgnoreRevocation	The certificate revocation is ignored.

Security error in a secure FTPS connection

During a secure transaction, the function may fail due to security errors:

invalid certificate or certificate coming from an unknown company.
site name found in the certificate not corresponding to a server.
invalid or expired certificate date.

You have the ability to connect while ignoring these errors. To do so, use the FTP.IgnoreError variable:

Value of FTP.IgnoreError (these values can be combined)	Description

ftpIgnoreInvalidCertificate	The certificate is ignored.
ftpIgnoreExpiredCertificate	The certificate date is ignored.
ftpIgnoreInvalidCertificateName	The site name specified in the certificate is ignored.
ftpIgnoreRevocation	The certificate revocation is ignored.

Required permissions

The call to this function modifies the permissions required by the application.
Required permission : INTERNET
This permission allows the applications to open the network sockets.

Required configuration

In PHP, the ftp module must be enabled.
To enable (if necessary) this library locally, the PHP.INI file found in the Windows directory must include the "extension=php_ftp.dll" line.

Related Examples:

Unit examples (WINDEV): The FTP functions

[ + ] Using the main FTP functions of WINDEV:
- Connect to a FTP server
- List the files and directories found on the FTP server
- Retrieve the files found on the FTP server
- Disconnect from a FTP server

Complete examples (WINDEV): WD FTP File Transfer

[ + ] WD FTP file transfer

This example is a full FTP client allowing you to store several FTP servers. Then, you have the ability to perform multi-file transfers from the local computer to the server or from the FTP server to the local computer. To do so, we are using the standard functions of WLanguage (FTPConnect, etc...)

Component: wd270com.dll