ftp_client.h

00001 /**
00002  * @file ftp_client.h
00003  * @brief FTP client (File Transfer Protocol)
00004  *
00005  * @section License
00006  *
00007  * Copyright (C) 2010-2017 Oryx Embedded SARL. All rights reserved.
00008  *
00009  * This file is part of CycloneTCP Open.
00010  *
00011  * This program is free software; you can redistribute it and/or
00012  * modify it under the terms of the GNU General Public License
00013  * as published by the Free Software Foundation; either version 2
00014  * of the License, or (at your option) any later version.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program; if not, write to the Free Software Foundation,
00023  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
00024  *
00025  * @author Oryx Embedded SARL (www.oryx-embedded.com)
00026  * @version 1.7.6
00027  **/
00028 
00029 #ifndef _FTP_CLIENT_H
00030 #define _FTP_CLIENT_H
00031 
00032 //Dependencies
00033 #include "core/net.h"
00034 #include "core/socket.h"
00035 
00036 //FTP client support
00037 #ifndef FTP_CLIENT_SUPPORT
00038    #define FTP_CLIENT_SUPPORT ENABLED
00039 #elif (FTP_CLIENT_SUPPORT != ENABLED && FTP_CLIENT_SUPPORT != DISABLED)
00040    #error FTP_CLIENT_SUPPORT parameter is not valid
00041 #endif
00042 
00043 //FTP over SSL/TLS
00044 #ifndef FTP_CLIENT_TLS_SUPPORT
00045    #define FTP_CLIENT_TLS_SUPPORT DISABLED
00046 #elif (FTP_CLIENT_TLS_SUPPORT != ENABLED && FTP_CLIENT_TLS_SUPPORT != DISABLED)
00047    #error FTP_CLIENT_TLS_SUPPORT parameter is not valid
00048 #endif
00049 
00050 //Default timeout
00051 #ifndef FTP_CLIENT_DEFAULT_TIMEOUT
00052    #define FTP_CLIENT_DEFAULT_TIMEOUT 20000
00053 #elif (FTP_CLIENT_DEFAULT_TIMEOUT < 1000)
00054    #error FTP_CLIENT_DEFAULT_TIMEOUT parameter is not valid
00055 #endif
00056 
00057 //Size of the buffer for input/output operations
00058 #ifndef FTP_CLIENT_BUFFER_SIZE
00059    #define FTP_CLIENT_BUFFER_SIZE 512
00060 #elif (FTP_CLIENT_BUFFER_SIZE < 64)
00061    #error FTP_CLIENT_BUFFER_SIZE parameter is not valid
00062 #endif
00063 
00064 //Minimum TX buffer size for FTP sockets
00065 #ifndef FTP_CLIENT_SOCKET_MIN_TX_BUFFER_SIZE
00066    #define FTP_CLIENT_SOCKET_MIN_TX_BUFFER_SIZE 1430
00067 #elif (FTP_CLIENT_SOCKET_MIN_TX_BUFFER_SIZE < 1)
00068    #error FTP_CLIENT_SOCKET_MIN_TX_BUFFER_SIZE parameter is not valid
00069 #endif
00070 
00071 //Minimum RX buffer size for FTP sockets
00072 #ifndef FTP_CLIENT_SOCKET_MIN_RX_BUFFER_SIZE
00073    #define FTP_CLIENT_SOCKET_MIN_RX_BUFFER_SIZE 1430
00074 #elif (FTP_CLIENT_SOCKET_MIN_RX_BUFFER_SIZE < 1)
00075    #error FTP_CLIENT_SOCKET_MIN_RX_BUFFER_SIZE parameter is not valid
00076 #endif
00077 
00078 //Maximum TX buffer size for FTP sockets
00079 #ifndef FTP_CLIENT_SOCKET_MAX_TX_BUFFER_SIZE
00080    #define FTP_CLIENT_SOCKET_MAX_TX_BUFFER_SIZE 2860
00081 #elif (FTP_CLIENT_SOCKET_MAX_TX_BUFFER_SIZE < 1)
00082    #error FTP_CLIENT_SOCKET_MAX_TX_BUFFER_SIZE parameter is not valid
00083 #endif
00084 
00085 //Maximum RX buffer size for FTP sockets
00086 #ifndef FTP_CLIENT_SOCKET_MAX_RX_BUFFER_SIZE
00087    #define FTP_CLIENT_SOCKET_MAX_RX_BUFFER_SIZE 2860
00088 #elif (FTP_CLIENT_SOCKET_MAX_RX_BUFFER_SIZE < 1)
00089    #error FTP_CLIENT_SOCKET_MAX_RX_BUFFER_SIZE parameter is not valid
00090 #endif
00091 
00092 //SSL/TLS supported?
00093 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
00094    #include "crypto.h"
00095    #include "tls.h"
00096 #endif
00097 
00098 //Test macros for FTP response codes
00099 #define FTP_REPLY_CODE_1YZ(code) ((code) >= 100 && (code) < 200)
00100 #define FTP_REPLY_CODE_2YZ(code) ((code) >= 200 && (code) < 300)
00101 #define FTP_REPLY_CODE_3YZ(code) ((code) >= 300 && (code) < 400)
00102 #define FTP_REPLY_CODE_4YZ(code) ((code) >= 400 && (code) < 500)
00103 #define FTP_REPLY_CODE_5YZ(code) ((code) >= 500 && (code) < 600)
00104 
00105 //Forward declaration of FtpClientContext structure
00106 struct _FtpClientContext;
00107 #define FtpClientContext struct _FtpClientContext
00108 
00109 
00110 /**
00111  * @brief Connection options
00112  **/
00113 
00114 typedef enum
00115 {
00116    FTP_NO_SECURITY       = 0,
00117    FTP_IMPLICIT_SECURITY = 1,
00118    FTP_EXPLICIT_SECURITY = 2,
00119    FTP_ACTIVE_MODE       = 0,
00120    FTP_PASSIVE_MODE      = 4
00121 } FtpConnectionFlags;
00122 
00123 
00124 /**
00125  * @brief File opening options
00126  **/
00127 
00128 typedef enum
00129 {
00130    FTP_FOR_READING   = 0,
00131    FTP_FOR_WRITING   = 1,
00132    FTP_FOR_APPENDING = 2,
00133    FTP_BINARY_TYPE   = 0,
00134    FTP_TEXT_TYPE     = 4
00135 } FtpFileOpeningFlags;
00136 
00137 
00138 /**
00139  * @brief Flags used by I/O functions
00140  **/
00141 
00142 typedef enum
00143 {
00144    FTP_FLAG_PEEK       = 0x0200,
00145    FTP_FLAG_WAIT_ALL   = 0x0800,
00146    FTP_FLAG_BREAK_CHAR = 0x1000,
00147    FTP_FLAG_BREAK_CRLF = 0x100A,
00148    FTP_FLAG_WAIT_ACK   = 0x2000
00149 } FtpFlags;
00150 
00151 
00152 //SSL/TLS supported?
00153 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
00154 
00155 /**
00156  * @brief SSL initialization callback function
00157  **/
00158 
00159 typedef error_t (*FtpClientTlsInitCallback)(FtpClientContext *context,
00160    TlsContext *tlsContext);
00161 
00162 #endif
00163 
00164 
00165 /**
00166  * @brief FTP client context
00167  **/
00168 
00169 struct _FtpClientContext
00170 {
00171    NetInterface *interface;                  ///<Underlying network interface
00172    IpAddr serverIpAddr;                      ///<IP address of the FTP server
00173    bool_t passiveMode;                       ///<Passive mode
00174    Socket *controlSocket;                    ///<Control connection socket
00175    Socket *dataSocket;                       ///<Data connection socket
00176    char_t buffer[FTP_CLIENT_BUFFER_SIZE];    ///<Memory buffer for input/output operations
00177 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
00178    TlsContext *controlTlsContext;            ///<SSL context (control connection)
00179    TlsContext *dataTlsContext;               ///<SSL context (data connection)
00180    TlsSession tlsSession;                    ///<SSL session
00181    FtpClientTlsInitCallback tlsInitCallback; ///<SSL initialization callback function
00182 #endif
00183 };
00184 
00185 
00186 //FTP client related functions
00187 error_t ftpConnect(FtpClientContext *context, NetInterface *interface,
00188    const IpAddr *serverIpAddr, uint16_t serverPort, uint_t flags);
00189 
00190 error_t ftpAuth(FtpClientContext *context);
00191 
00192 error_t ftpLogin(FtpClientContext *context, const char_t *username,
00193    const char_t *password, const char_t *account);
00194 
00195 error_t ftpGetWorkingDir(FtpClientContext *context, char_t *path, size_t size);
00196 error_t ftpChangeWorkingDir(FtpClientContext *context, const char_t *path);
00197 error_t ftpChangeToParentDir(FtpClientContext *context);
00198 
00199 error_t ftpMakeDir(FtpClientContext *context, const char_t *path);
00200 error_t ftpRemoveDir(FtpClientContext *context, const char_t *path);
00201 
00202 error_t ftpOpenFile(FtpClientContext *context, const char_t *path, uint_t flags);
00203 
00204 error_t ftpWriteFile(FtpClientContext *context,
00205    const void *data, size_t length, uint_t flags);
00206 
00207 error_t ftpReadFile(FtpClientContext *context,
00208    void *data, size_t size, size_t *length, uint_t flags);
00209 
00210 error_t ftpCloseFile(FtpClientContext *context);
00211 
00212 error_t ftpRenameFile(FtpClientContext *context,
00213    const char_t *oldName, const char_t *newName);
00214 
00215 error_t ftpDeleteFile(FtpClientContext *context, const char_t *path);
00216 
00217 error_t ftpClose(FtpClientContext *context);
00218 
00219 error_t ftpSendCommand(FtpClientContext *context,
00220    const char_t *command, uint_t *replyCode);
00221 
00222 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
00223 
00224 error_t ftpRegisterTlsInitCallback(FtpClientContext *context,
00225    FtpClientTlsInitCallback callback);
00226 
00227 error_t ftpInitControlTlsContext(FtpClientContext *context);
00228 error_t ftpInitDataTlsContext(FtpClientContext *context);
00229 
00230 #endif
00231 
00232 #endif
00233