Network Component  Version 7.11.0
MDK Middleware for IPv4 and IPv6 Networking
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Control Interface

Functions to work with the FTP server. More...

Functions

netStatus netFTPs_Start (void)
 Start FTP server. [thread-safe]. More...
 
netStatus netFTPs_Stop (void)
 Stop FTP server. [thread-safe]. More...
 
bool netFTPs_Running (void)
 Check if FTP server is running. [thread-safe]. More...
 
uint16_t netFTPs_GetPort (void)
 Get port number of FTP server. [thread-safe]. More...
 
netStatus netFTPs_SetPort (uint16_t port)
 Set port number of FTP server. [thread-safe]. More...
 
const char * netFTPs_GetRootPath (void)
 Retrieve path to the root directory of FTP server. [thread-safe]. More...
 
netStatus netFTPs_SetRootPath (const char *path)
 Set path to the root directory of FTP server. [thread-safe]. More...
 
const char * netFTPs_GetUsername (void)
 Retrieve username of the built-in user account. [thread-safe]. More...
 
netStatus netFTPs_SetUsername (const char *username)
 Set username of the built-in user account. [thread-safe]. More...
 
const char * netFTPs_GetPassword (void)
 Retrieve password of the built-in user account. [thread-safe]. More...
 
netStatus netFTPs_SetPassword (const char *password)
 Reset password of the built-in user account. [thread-safe]. More...
 
bool netFTPs_LoginActive (void)
 Determine if FTP server authentication is enabled. [thread-safe]. More...
 
netStatus netFTPs_LoginOnOff (bool login)
 Enable or disable FTP server authentication. [thread-safe]. More...
 

Description

Functions to work with the FTP server.

Like all services, the FTP server is normally started automatically if NET_START_SERVICE is set to 1 in the Net_Config.c configuration file. If it is disabled, the FTP server needs to be started manually in the user application using netFTPs_Start. At runtime, it is always possible to stop the FTP server using the function netFTPs_Stop. The user application can check for a running server using the netFTPs_Running function.

To change the port of the FTP server at runtime, first call netFTPs_Stop (if the server is running) and then use the netFTPs_SetPort function. Afterwards, the FTP server needs to be (re-)started by the application calling netFTPs_Start.

Code Example

void change_server_port (uint16_t port) {
if (netFTPs_Running() == true) {
}
}

To change the path to a root folder of the FTP server at runtime, first call netFTPs_Stop (if the server is running) and then use the netFTPs_SetRootPath function. Afterwards, the FTP server needs to be (re-)started by the application calling netFTPs_Start.

The FTP server supports a built-in user account if the FTP_SERVER_AUTH_ADMIN is set to 1. In this case, the user specified by FTP_SERVER_AUTH_USER is created and the password FTP_SERVER_AUTH_PASS is used for this user. The FTP server control interface provides functions to work with this built-in account. To retrieve the username in the application, use netFTPs_GetUsername. To change this username at runtime, use netFTPs_SetUsername. The same pair of functions is available for managing the password (netFTPs_GetPassword/netFTPs_SetPassword).

It is also possible to check if this login is active (netFTPs_LoginActive) and to enable or disable it at runtime using netFTPs_LoginOnOff. Please note that the function netFTPs_LoginOnOff is only available at runtime if the define FTP_SERVER_AUTH_ENABLE is set to 1 in the Net_Config_FTP_Server.h file. Otherwise, this command will not be compiled into the project to save resources. For more complex account management, use the Access and Multi-User Interface.

Function Documentation

const char * netFTPs_GetPassword ( void  )

Retrieve password of the built-in user account. [thread-safe].

Returns
pointer to password, a null-terminated string.
  • NULL if authentication is disabled in the configuration.

The function netFTPs_GetPassword returns the password of the built-in user account if FTP_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_FTP.h file. If this define is set to 0, the function is not available at runtime and returns NULL.

Code Example (see netFTPs_LoginActive)

uint16_t netFTPs_GetPort ( void  )

Get port number of FTP server. [thread-safe].

Returns
port number.

The function netFTPs_GetPort returns the port of the FTP server.

Code Example

printf ("FTP server is listening on port %d\n", netFTPs_GetPort ());
const char * netFTPs_GetRootPath ( void  )

Retrieve path to the root directory of FTP server. [thread-safe].

Returns
pointer to root path, a null-terminated string.
  • NULL if root folder is disabled in the configuration.

The function netFTPs_GetRootPath returns the path to the current root directory if FTP_SERVER_ROOT_ENABLE is set to 1 in the Net_Config_FTP_Server.h file. If this define is set to 0, the function is not available at runtime and returns NULL.

Code Example

if (netFTPs_GetRootPath() != NULL) {
printf ("User files are stored here: %s\n", netFTPs_GetRootPath ());
}
const char * netFTPs_GetUsername ( void  )

Retrieve username of the built-in user account. [thread-safe].

Returns
pointer to username, a null-terminated string.
  • NULL if authentication is disabled in the configuration.

The function netFTPs_GetUsername returns the user name of the built-in user if FTP_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_FTP.h file. If this define is set to 0, the function is not available at runtime and returns NULL.

Code Example (see netFTPs_LoginActive)

bool netFTPs_LoginActive ( void  )

Determine if FTP server authentication is enabled. [thread-safe].

Returns
  • true = Authentication enabled in the configuration.
  • false = Authentication is not enabled.

The function netFTPs_LoginActive checks if the FTP server is set up for user authentication.

Code Example

if (netFTPs_LoginActive() == true) {
printf ("Authentication is enabled\n");
printf ("Username is: %s\n", netFTPs_GetUsername());
printf ("Password is: %s\n", netFTPs_GetPassword());
}
netStatus netFTPs_LoginOnOff ( bool  login)

Enable or disable FTP server authentication. [thread-safe].

Parameters
[in]loginnew authentication state:
  • true = Enable authentication.
  • false = Disable authentication.
Returns
status code that indicates the execution status of the function.

The function netFTPs_LoginOnOff enables or disables the user authentication on the FTP server. If FTP_SERVER_AUTH_ENABLE is set to 0 in the Net_Config_FTP.h file, the function is not available at runtime.

The argument login switches the log-in on (true) or off (false).

Possible netStatus return values:

  • netOK: Login enabled or disabled successfully.
  • netError: Authentication not enabled in the configuration.

Code Example

if (netFTPs_LoginActive () == true) {
}
bool netFTPs_Running ( void  )

Check if FTP server is running. [thread-safe].

Returns
  • true = Server is running.
  • false = Server is not running.

The function netFTPs_Running is used to check whether the FTP server is running. A return value of true shows a running FTP server.

Code Example (see netFTPs_SetPort)

netStatus netFTPs_SetPassword ( const char *  password)

Reset password of the built-in user account. [thread-safe].

Parameters
[in]passwordnew password, a null-terminated string.
Returns
status code that indicates the execution status of the function.

The function netFTPs_SetPassword sets the password of the built-in user if FTP_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_FTP.h file. If this define is set to 0, the function is not available at runtime.

The argument password is a pointer to the password that is to be set, which is a null-terminated string. The function copies the content of the password to the password of the build-in user. The maximum length of the password string is limited to 15 characters.

Possible netStatus return values:

  • netOK: Password successfully set.
  • netInvalidParameter: Invalid password provided.
  • netError: Administrator account not enabled in the configuration.
Note
When the function ends, the content of password becomes irrelevant and may be discarded.

Code Example (see netFTPs_SetUsername)

netStatus netFTPs_SetPort ( uint16_t  port)

Set port number of FTP server. [thread-safe].

Parameters
[in]portport number.
Returns
status code that indicates the execution status of the function.

The function netFTPs_SetPort sets the port of the FTP server. The FTP server must not run while setting the port. If required, stop it first using netFTPs_Stop.

The argument port specifies the port number to be used.

Possible netStatus return values:

  • netOK: Port successfully set.
  • netWrongState: FTP server is running.

Code Example

void change_server_port (uint16_t port) {}
if (netFTPs_Running() == true) {
}
}
netStatus netFTPs_SetRootPath ( const char *  path)

Set path to the root directory of FTP server. [thread-safe].

Parameters
[in]pathnew root path, a null-terminated string.
Returns
status code that indicates the execution status of the function.

The function netFTPs_SetRootPath sets the path to the root directory of FTP server if FTP_SERVER_ROOT_ENABLE is set to 1 in the Net_Config_FTP_Server.h file. If this define is set to 0, the function is not available at runtime. Root directory specifies a path on a storage device, where the user files are stored.

The argument path is a pointer to the new root path to be set, which is a null-terminated string. The function copies the content of the path to the root path of the FTP server. The maximum length of the path string is limited to 79 characters.

Possible netStatus return values:

  • netOK: Root path successfully set.
  • netInvalidParameter: Invalid path parameter provided.
  • netWrongState: FTP server is running.
  • netError: Root path not enabled in the configuration.
Note
When the function ends, the content of path becomes irrelevant and may be discarded.

Code Example

netStatus netFTPs_SetUsername ( const char *  username)

Set username of the built-in user account. [thread-safe].

Parameters
[in]usernamenew username, a null-terminated string.
Returns
status code that indicates the execution status of the function.

The function netFTPs_SetUsername sets the user name of the built-in user if FTP_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_FTP.h file. If this define is set to 0, the function is not available at runtime.

The argument username is a pointer to the user name to be set, which is a null-terminated string. The function copies the content of the username to the user name of the built-in user. The maximum length of the username string is limited to 15 characters.

Possible netStatus return values:

  • netOK: Username successfully set.
  • netInvalidParameter: Invalid username provided.
  • netError: Administrator account not enabled in the configuration.
Note
When the function ends, the content of username becomes irrelevant and may be discarded.

Code Example

if (netFTPs_LoginActive() == true) {
netFTPs_SetUsername ("sysadmin");
netFTPs_SetPassword ("a$Min#77");
}
netStatus netFTPs_Start ( void  )

Start FTP server. [thread-safe].

Returns
status code that indicates the execution status of the function.

The function netFTPs_Start is used to start the FTP server at runtime.

Possible netStatus return values:

  • netOK: FTP server started successfully.
Note
If you set the NET_START_SERVICE to 1 in Net_Config.c, all selected services will be started automatically. Thus, you only need to call this function, if you have either stopped the FTP server previously using netFTPs_Stop or have set NET_START_SERVICE to 0.

Code Example (see netFTPs_SetPort)

netStatus netFTPs_Stop ( void  )

Stop FTP server. [thread-safe].

Returns
status code that indicates the execution status of the function.

The function netFTPs_Stop is used to stop the FTP server at runtime. To re-start the FTP server, use netFTPs_Start.

Possible netStatus return values:

  • netOK: FTP server stopped successfully.

Code Example (see netFTPs_SetPort)