ftpConnect (Function)

 Top  Previous  Next

Architecture:

X32 / NX32 / NX32L

Device support:

All

Firmware version:

2.10 / 1.00.00

This initiates a FTP connection to the specified IP address/port number. When this function returns, the connection has been established.

For each ftpConnect(), there must be a corresponding ftpDisconnect() even if the connection is closed from the server side (see example below).  

 

It is possible to establish a maximum of 2 simultaneous FTP connections.

 

Note:

A connection error is returned if a successful login request cannot be obtained. This includes invalid IP or a non-FTP response from server.

 

Using secure connection

For NX32L devices, a secure TLS (TLS v1.2, v1.1 or 1.0) connection can be established, assuming that the matching X509 certificate is present.

There are 2 ways of implementing secure connections:

1. Explicit, where the secure connection handshake is performed after the server sends the welcome message.

2. Implicit, where the secure connection handshake is performed before the server sends the welcome message.

The second one is an older (non standard) method which requires a different port (the default is port 990).

 

With both methods, the secure connection is established before sending the User name and Password during login.

 

 

Input:

Host : STRING

IP address (in dotted format "aaa.bbb.ccc.ddd" or symbolic "domain.xyz".

 

Port : DINT (1..65535, default 21)

Port to connect to on server.

 

iface : SINT (default 1)

The network interface to use. 0 = Default network, 1 = Mobile network, 2 = LAN network, etc. (See Network)

Note: For backwards compatibility the Mobile network is used as default network.

 

Username : STRING (default "anonymous")

Username to use during login.

 

Password : STRING

Password to use if requested by server.

Note: password is only used if requested by server.

 

Security : SINT

The required type of security used by the connection.

0

- Plain text session.

1

- Plain text session or Explicit secure session.

2

- Explicit secure session.

3

- Implicit secure session.

 

Returns: INT

ID of new connected session.

- 1

- All session is in use, see ftpDisconnect to free.

- 3

- Error in parameter.

- 5

- FTP not open, use ftpOpen to open interface.

- 8

- Connecting to server failed.

- 9

- Login failed, server has not replied as expected to login.

- 10

- Communication with server not possible.

-11

- The server require secure connection.

-12

- Failed to establish secure connection.

 

Declaration:

FUNCTION ftpConnect : INT;
VAR_INPUT
  Host     : STRING;
  Username : STRING := "anonymous";
  Password : STRING;
  Port     : DINT   := 21;
  iface    : SINT   := 1;
  security : SINT   := 0;
END_VAR;

 

Example:

INCLUDE rtcu.inc
 
PROGRAM example;
VAR
  open  : BOOL;
  host  : STRING := "ftp.domain.com";
  usr   : STRING := "ftpuser";
  pwd   : STRING := "user pwd";
 
  id    : INT;
END_VAR;
 
  gsmPower(power := ON);
  gprsOpen();
 
BEGIN
open := (ftpOpen() = 0);
IF open THEN
    id := ftpConnect(host := host, username := usr, password := pwd);
    ...
    ftpDisconnect(id := id);
END_IF;
ftpClose();
END;
END_PROGRAM;