FTP Development Guide_Rev1.1

Revision History

Version	Date	Author	Revision Content
Rev1.0	2023-10-08	chw	Initial document creation
Rev1.1	2024-03-25	sxx	Changed document name
Rev1.2	2025-02-13	sxx	Added interface for changing transmission type

1 Introduction

This document introduces the LTE-EC71X FTP interface APIs. The API interfaces are declared in the file components/kernel/lierda_api/liot_ftp/liot_ftp.h.

This set of API interfaces belongs to synchronous interfaces.

2 API Function Overview

Function	Description
`liot_ftp_client_new()`	Create FTP client
`liot_ftp_client_release()`	Release FTP client
`liot_ftp_client_setopt()`	Set client options
`liot_ftp_client_open()`	Connect to FTP server
`liot_ftp_client_close()`	Disconnect from FTP server
`liot_ftp_client_get_ex()`	Download file
`liot_ftp_client_put_ex()`	Upload file
`liot_ftp_client_delete()`	Delete file
`liot_ftp_client_pwd()`	Get current directory path
`liot_ftp_client_cwd()`	Change current directory path
`liot_ftp_client_mkdir()`	Create new directory
`liot_ftp_client_rmdir()`	Delete directory
`liot_ftp_client_list()`	Get directory information
`liot_ftp_client_size()`	Get file size
`liot_ftp_client_rename()`	Rename file
`liot_ftp_client_FileTpye()`	Set transmission file type

3 Type Descriptions

3.1 LIOT_FTP_CLIENT_ERR_E

FTP API execution result return codes.

Declaration

typedef enum
{
    LIOT_FTP_CLIENT_ERR_SUCCESS = 0,           // Function executed successfully
    LIOT_FTP_CLIENT_ERR_INVALID_CLIENT = 1,    // Invalid FTP client handle
    LIOT_FTP_CLIENT_ERR_INVALID_HOST,          // Invalid host address
    LIOT_FTP_CLIENT_ERR_DNS_FAIL,              // DNS resolution failed
    LIOT_FTP_CLIENT_ERR_SOCK_CREATE_FAIL,      // Failed to create SOCKET
    LIOT_FTP_CLIENT_ERR_SOCK_BIND_FAIL = 5,    // Failed to bind SOCKET
    LIOT_FTP_CLIENT_ERR_SOCK_CONN_FAIL,        // SOCKET connection failed
    LIOT_FTP_CLIENT_ERR_SOCK_SEND_FAIL,        // SOCKET send failed
    LIOT_FTP_CLIENT_ERR_SOCK_RECV_FAIL,        // SOCKET receive failed
    LIOT_FTP_CLIENT_ERR_SOCK_CLOSE_FAIL,       // Failed to close SOCKET connection
    LIOT_FTP_CLIENT_ERR_SOCK_DISCONNECTED = 10,// Connection disconnected
    LIOT_FTP_CLIENT_ERR_SSL_CONN_FAIL,         // SSL connection failed
    LIOT_FTP_CLIENT_ERR_RESP_TIMEOUT,          // Request timeout
    LIOT_FTP_CLIENT_ERR_CREATE_FILE_FAIL,      // Failed to create file
    LIOT_FTP_CLIENT_ERR_NO_FILE,               // File does not exist
    LIOT_FTP_CLIENT_ERR_NO_DIR = 15,           // Directory does not exist
    LIOT_FTP_CLIENT_ERR_UNKNOWN                // Unknown error
} LIOT_FTP_CLIENT_ERR_E;

3.2 LIOT_FTP_CLIENT_OPT_E

FTP client attribute setting tags.

Declaration

typedef enum {
    LIOT_FTP_CLIENT_SSL_ENABLE,   // SSL enable, 0: FTP, 1: FTPS implicit encryption, 2: FTPS explicit encryption. Currently FTPS is not supported
    LIOT_FTP_CLIENT_OPT_START_POS,// File start position setting, default is 0
    LIOT_FTP_CLIENT_FILE_TYPE,    // File type, 0: binary, 1: ASCII
    LIOT_FTP_CLIENT_TRANS_MODE,   // Transmission mode, 0: active mode, 1: passive mode
    LIOT_FTP_CLIENT_RSP_TIMEOUT,  // Timeout time, default 90s
}LIOT_FTP_CLIENT_OPT_E;

Tag Description

LIOT_FTP_CLIENT_SSL_ENABLE:

[] SSL enable, 0: FTP, 1: FTPS implicit encryption, 2: FTPS explicit encryption. Currently FTPS is not supported.

LIOT_FTP_CLIENT_OPT_START_POS:

[] File start position setting, default is 0.

LIOT_FTP_CLIENT_FILE_TYPE:

[] File type, 0: binary, 1: ASCII.

LIOT_FTP_CLIENT_TRANS_MODE:

[] Transmission mode, 0: active mode, 1: passive mode.

LIOT_FTP_CLIENT_RSP_TIMEOUT:

[] Timeout time, default 90s.

3.3 LIOT_FTP_CLIENT_WRITE_CB_EX

Download completion callback function.

Declaration

typedef void (*LIOT_FTP_CLIENT_WRITE_CB_EX)(void *ptr, uint32_t size);

Parameters

ptr:

[In] Download data pointer.

size:

[In] Download data length, unit: bytes.

Return Value

None.

4 API Function Details

4.1 liot_ftp_client_new

Create FTP client.

Declaration

void *liot_ftp_client_new(void);

Parameters

None.

Return Value

void *: FTP client handle.

4.2 liot_ftp_client_release

Release FTP client.

Declaration

void liot_ftp_client_release(void *client);

Parameters

client:

[In] FTP client handle.

Return Value

None.

4.3 liot_ftp_client_setopt

Set FTP client attributes.

Declaration

int liot_ftp_client_setopt(void *client, LIOT_FTP_CLIENT_OPT_E tag, void *param);

Parameters

client:

[In] FTP client handle.

tag:

[In] Attribute tag, please refer to 3.2 LIOT_FTP_CLIENT_OPT_E.

param:

[In] Attribute value.

Return Value

int: Execution result code, please refer to 3.1.

4.4 liot_ftp_client_open

Connect to FTP server.

Declaration

int liot_ftp_client_open(void *client, char *hostname, char *port, char *username, char *password);

Parameters

client:

[In] FTP client handle.

hostname:

[In] Server address, maximum length 255 bytes.

port:

[In] Server port, 0~65535.

username:

[In] Username, maximum length 255 bytes.

password:

[In] Password, maximum length 255 bytes.

Return Value

int: Execution result code, please refer to 3.1.

4.5 liot_ftp_client_close

Disconnect from FTP server.

Declaration

int liot_ftp_client_close(void *client);

Parameters

client:

[In] FTP client handle.

Return Value

int: Execution result code, please refer to 3.1.

4.6 liot_ftp_client_get_ex

Download file.

Declaration

int liot_ftp_client_get_ex(void *client, char *remotefile, char *localfile, LIOT_FTP_CLIENT_WRITE_CB_EX write_cb);

Parameters

client:

[In] FTP client handle.

remotefile:

[In] Server file path, maximum length 255 bytes.

localfile:

[In] Local file name, valid when callback function write_cb is NULL, download file to local file, maximum length 84 bytes.

write_cb:

[In] Download completion callback function, when not NULL, downloaded data is obtained in this function, please refer to 3.3 LIOT_FTP_CLIENT_WRITE_CB_EX.

Return Value

int: Execution result code, please refer to 3.1.

4.7 liot_ftp_client_put_ex

Upload file.

Declaration

int liot_ftp_client_put_ex(void *client, char *localfile, char *remotefile, void *userData, uint32_t uploadlen);

Parameters

client:

[In] FTP client handle.

localfile:

[In] Local file name, valid when upload data userData is NULL, upload local file to server, maximum length 84 bytes.

remotefile:

[In] Server file path, maximum length 255 bytes.

userData:

[In] Data to be uploaded, when not NULL, upload data from this address to server.

uploadlen:

[In] Length of data pointed to by userData.

Return Value

int: Execution result code, please refer to 3.1.

4.8 liot_ftp_client_delete

Delete server file.

Declaration

int liot_ftp_client_delete(void *client, char *remotefile);

Parameters

client:

[In] FTP client handle.

remotefile:

[In] Server file path, maximum length 255 bytes.

Return Value

int: Execution result code, please refer to 3.1.

4.9 liot_ftp_client_pwd

Get server directory path.

Declaration

int liot_ftp_client_pwd(void *client, char *path);

Parameters

client:

[In] FTP client handle.

path:

[Out] Returned server current path, maximum length 255 bytes.

Return Value

int: Execution result code, please refer to 3.1.

4.10 liot_ftp_client_cwd

Change server directory path.

Declaration

int liot_ftp_client_cwd(void *client, char *path);

Parameters

client:

[In] FTP client handle.

path:

[In] Directory path to change to, maximum length 255 bytes.

Return Value

int: Execution result code, please refer to 3.1.

4.11 liot_ftp_client_mkdir

Create new server directory.

Declaration

int liot_ftp_client_mkdir(void *client, char *path);

Parameters

client:

[In] FTP client handle.

path:

[In] New directory path, maximum length 255 bytes.

Return Value

int: Execution result code, please refer to 3.1.

4.12 liot_ftp_client_rmdir

Delete server directory.

Declaration

int liot_ftp_client_rmdir(void *client, char *path);

Parameters

client:

[In] FTP client handle.

path:

[In] Directory path to delete, maximum length 255 bytes.

Return Value

int: Execution result code, please refer to 3.1.

4.13 liot_ftp_client_list

Get server directory information list.

Declaration

int liot_ftp_client_list(void *client, char *path, char *list);

Parameters

client:

[In] FTP client handle.

path:

[In] Directory path, maximum length 255 bytes.

list:

[Out] Directory list information.

Return Value

int: Execution result code, please refer to 3.1.

4.14 liot_ftp_client_size

Get server file size.

Declaration

int liot_ftp_client_size(void *client, char *filename, uint32_t *size);

Parameters

client:

[In] FTP client handle.

filename:

[In] Server file path, maximum length 255 bytes.

size:

[Out] File size, unit: bytes.

Return Value

int: Execution result code, please refer to 3.1.

4.15 liot_ftp_client_rename

Rename server file.

Declaration

int liot_ftp_client_rename(void *client, char *old_name, char *new_name);

Parameters

client:

[In] FTP client handle.

old_name:

[In] Old file name, maximum length 255 bytes.

new_name:

[In] New file name, maximum length 255 bytes.

Return Value

int: Execution result code, please refer to 3.1.

4.16 liot_ftp_client_FileTpye

Change transmission file type.

Declaration

int liot_ftp_client_FileTpye(void *client, uint32_t Type);

Parameters

client:

[In] FTP client handle.

Type:

[In] Transmission file type, FTP_ASCII or FTP_BINARY.

Return Value

int: Execution result code, please refer to 3.1.

5 Code Example

Sample code reference: examples/demo/src/demo_ftp.c file.

Due to the large size of the code example, please refer to the SDK for complete sample code. The main functions include:

FTP client creation and connection
File upload and download
Directory operations (create, delete, change)
File operations (rename, delete, get size)
Directory listing retrieval

Running Result:

Open USB port to capture test logs