ftp_client.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020-2026 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_NET_FTP_CLIENT_H_
#define ZEPHYR_INCLUDE_NET_FTP_CLIENT_H_
 
#include <zephyr/kernel.h>
#include <zephyr/types.h>
#include <zephyr/net/net_ip.h>
 
#ifdef __cplusplus
extern "C" {
#endif


#if defined(CONFIG_FTP_CLIENT)
#define FTP_BUFFER_SIZE CONFIG_FTP_CLIENT_BUF_SIZE
#else
#define FTP_BUFFER_SIZE 1
#endif

enum ftp_reply_code {
        /* 100 Series   The requested action is being initiated, expect another
         * reply before proceeding with a new command
         */

        FTP_CODE_110_RESTART_MARKER_REPLAY = 110,
        FTP_CODE_120_SERVICE_READY_IN_NNN_MINUTES = 120,
        FTP_CODE_125_DATA_CONN_ALREADY_OPEN = 125,
        FTP_CODE_150_FILE_STATUS_OK = 150,
 
        /* 200 Series   The requested action has been successfully completed */

        FTP_CODE_200_OK = 200,
        FTP_CODE_202_NOT_IMPLEMENTED = 202,
        FTP_CODE_211_SYSTEM_STATUS = 211,
        FTP_CODE_212_DIR_STATUS = 212,
        FTP_CODE_213_FILE_STATUS = 213,
        FTP_CODE_214_HELP_MSG = 214,
        FTP_CODE_215_NAME_SYSTEM_TYPE = 215,
        FTP_CODE_220_SERVICE_READY = 220,
        FTP_CODE_221_SERVICE_CLOSING_CONN = 221,
        FTP_CODE_225_DATA_CONN_OPEN = 225,
        FTP_CODE_226_CLOSING_DATA_CONN_SUCCESS = 226,
        FTP_CODE_227_ENTERING_PASSIVE_MODE = 227,
        FTP_CODE_228_ENTERING_LONG_PASSIVE_MODE = 228,
        FTP_CODE_229_ENTERING_EXT_PASSIVE_MODE = 229,
        FTP_CODE_230_USER_LOGGED_IN = 230,
        FTP_CODE_231_USER_LOGGED_OUT = 231,
        FTP_CODE_233_LOGOUT_COMMAND_NOTED = 233,
        FTP_CODE_234_SECURITY_ACCEPTED = 234,
        FTP_CODE_250_FILE_ACTION_COMPLETED = 250,
        FTP_CODE_257_PATHNAME_CREATED = 257,
 
        /* 300 Series   The command has been accepted, but the requested action
         *is on hold, pending receipt of further information
         */

        FTP_CODE_331_USERNAME_OK_NEED_PASSWORD = 331,
        FTP_CODE_332_NEED_ACCOUNT = 332,
        FTP_CODE_350_FILE_ACTION_PENDING = 350,
 
        /* 400 Series   The command was not accepted and the requested action
         * did not take place, but the error condition is temporary and the
         * action may be requested again
         */

        FTP_CODE_421_SERVICE_UNAVAILABLE = 421,
        FTP_CODE_425_CANNOT_OPEN_DATA_CONN = 425,
        FTP_CODE_426_CONN_CLOSED = 426,
        FTP_CODE_430_INVALID_USERNAME_OR_PASSWORD = 430,
        FTP_CODE_434_HOST_UNAVAILABLE = 434,
        FTP_CODE_450_FILE_ACTION_NOT_TAKEN = 450,
        FTP_CODE_451_ACTION_ABORTED = 451,
        FTP_CODE_452_ACTION_NOT_TAKEN = 452,
 
        /* 500 Series   Syntax error, command unrecognized and the requested
         * action did not take place. This may include errors such as command
         * line too long
         */

        FTP_CODE_500_GENERAL_ERROR = 500,
        FTP_CODE_501_SYNTAX_ERROR = 501,
        FTP_CODE_502_COMMAND_NOT_COMPLETED = 502,
        FTP_CODE_503_BAD_SEQUENCE_OF_COMMANDS = 503,
        FTP_CODE_504_COMMAND_NOT_IMPLEMENTED = 504,
        FTP_CODE_530_NOT_LOGGED_IN = 530,
        FTP_CODE_532_NEED_ACCOUNT = 532,
        FTP_CODE_534_CANNOT_CONNECT_SSL_REQUIRED = 534,
        FTP_CODE_550_FILE_UNAVAILABLE = 550,
        FTP_CODE_551_PAGE_TYPE_UNKNOWN = 551,
        FTP_CODE_552_FILE_EXCEEDED_STORAGE_LOCATION = 552,
        FTP_CODE_553_FILE_NAME_NOT_ALLOWED = 553,
 
        /* Replies regarding confidentiality and integrity */

        FTP_CODE_631_INTEGRITY_PROTECTED_REPLY = 631,
        FTP_CODE_632_INT_AND_CONF_PROTECTED_REPLY = 632,
        FTP_CODE_633_CONFIDENTIALITY_PROTECTED_REPLY = 633,
 
        /* Proprietary reply codes */

        FTP_CODE_900_UNKNOWN_ERROR = 900,

        FTP_CODE_901_DISCONNECTED_BY_REMOTE = 901,
        FTP_CODE_902_CONNECTION_ABORTED = 902,
        FTP_CODE_903_SOCKET_POLL_ERROR = 903,
        FTP_CODE_904_UNEXPECTED_POLL_EVENT = 904,
        FTP_CODE_905_NETWORK_DOWN = 905,
        FTP_CODE_909_UNEXPECTED_ERROR = 909,
 
        /* Non-fatal errors */
        FTP_CODE_910_DATA_TRANSFER_TIMEOUT = 910,
 
        /* 10000 Series Common Winsock Error Codes[2] (These are not FTP
         * return codes)
         */

        FTP_CODE_10054_CONNECTION_RESET_BY_PEER = 10054,
        FTP_CODE_10060_CANNOT_CONNECT = 10060,
        FTP_CODE_10061_CONNECTION_REFUSED = 10061,
        FTP_CODE_10066_DIRECTORY_NOT_EMPTY = 10066,
        FTP_CODE_10068_TOO_MANY_USERS = 10068
};

#define FTP_PRELIMINARY_POS(code)       ((code) >= 100 && (code) < 200)
#define FTP_COMPLETION_POS(code)        ((code) >= 200 && (code) < 300)
#define FTP_INTERMEDIATE_POS(code)      ((code) >= 300 && (code) < 400)
#define FTP_TRANSIENT_NEG(code)         ((code) >= 400 && (code) < 500)
#define FTP_COMPLETION_NEG(code)        ((code) >= 500 && (code) < 600)
#define FTP_PROTECTED(code)             ((code) >= 600 && (code) < 700)
#define FTP_PROPRIETARY(code)           ((code) >= 900 && (code) < 1000)
#define FTP_WINSOCK_ERR(code)           ((code) >= 10000)

enum ftp_transfer_type {
        FTP_TYPE_ASCII, 
        FTP_TYPE_BINARY, 
};

enum ftp_put_type {
        FTP_PUT_NORMAL, 
        FTP_PUT_UNIQUE, 
        FTP_PUT_APPEND, 
};

typedef void (*ftp_client_callback_t)(const uint8_t *msg, uint16_t len);

struct ftp_client {
        struct net_sockaddr remote; 
        bool connected; 
        int ctrl_sock; 
        int data_sock; 
        int sec_tag; 
        uint8_t ctrl_buf[FTP_BUFFER_SIZE]; 
        size_t ctrl_len; 
        uint8_t data_buf[FTP_BUFFER_SIZE]; 
        ftp_client_callback_t ctrl_callback; 
        ftp_client_callback_t data_callback; 
        struct k_mutex lock;
        struct k_work_delayable keepalive_work;
};

int ftp_init(struct ftp_client *client, ftp_client_callback_t ctrl_callback,
             ftp_client_callback_t data_callback);

int ftp_uninit(struct ftp_client *client);

int ftp_open(struct ftp_client *client, const char *hostname, uint16_t port,
             int sec_tag);

int ftp_login(struct ftp_client *client, const char *username,
              const char *password);

int ftp_close(struct ftp_client *client);

int ftp_status(struct ftp_client *client);

int ftp_type(struct ftp_client *client, enum ftp_transfer_type type);

int ftp_pwd(struct ftp_client *client);

int ftp_list(struct ftp_client *client, const char *options, const char *target);

int ftp_cwd(struct ftp_client *client, const char *folder);

int ftp_mkd(struct ftp_client *client, const char *folder);

int ftp_rmd(struct ftp_client *client, const char *folder);

int ftp_rename(struct ftp_client *client, const char *old_name,
               const char *new_name);

int ftp_delete(struct ftp_client *client, const char *file);

int ftp_get(struct ftp_client *client, const char *file);

int ftp_put(struct ftp_client *client, const char *file, const uint8_t *data,
            uint16_t length, int type);

int ftp_keepalive(struct ftp_client *client);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_NET_FTP_CLIENT_H_ */