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

Functions
netStatus	netFTPs_Start (void)
	Start FTP server. [thread-safe].

netStatus	netFTPs_Stop (void)
	Stop FTP server. [thread-safe].

bool	netFTPs_Running (void)
	Check if FTP server is running. [thread-safe].

uint16_t	netFTPs_GetPort (void)
	Get port number of FTP server. [thread-safe].

netStatus	netFTPs_SetPort (uint16_t port)
	Set port number of FTP server. [thread-safe].

const char *	netFTPs_GetRootPath (void)
	Retrieve path to the root directory on FTP server. [thread-safe].

netStatus	netFTPs_SetRootPath (const char *path)
	Set path to the root directory on FTP server. [thread-safe].

const char *	netFTPs_GetUsername (void)
	Retrieve username of the built-in user account. [thread-safe].

netStatus	netFTPs_SetUsername (const char *username)
	Set username of the built-in user account. [thread-safe].

const char *	netFTPs_GetPassword (void)
	Retrieve password of the built-in user account. [thread-safe].

netStatus	netFTPs_SetPassword (const char *password)
	Reset password of the built-in user account. [thread-safe].

bool	netFTPs_LoginActive (void)
	Determine if FTP server authentication is enabled. [thread-safe].

netStatus	netFTPs_LoginOnOff (bool login)
	Enable or disable FTP server authentication. [thread-safe].

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.h 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) {
    netFTPs_Stop();
  }
  netFTPs_SetPort (port);
  netFTPs_Start();
}

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

◆ netFTPs_GetPassword()

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)

◆ netFTPs_GetPort()

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 ());

◆ netFTPs_GetRootPath()

const char * netFTPs_GetRootPath ( void )

Retrieve path to the root directory on 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 ());
}

◆ netFTPs_GetUsername()

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)

◆ 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());
}

◆ netFTPs_LoginOnOff()

netStatus netFTPs_LoginOnOff ( bool login )

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

Parameters

[in]

login

new 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) {
  netFTPs_LoginOnOff (false);
}

◆ netFTPs_Running()

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)

◆ netFTPs_SetPassword()

netStatus netFTPs_SetPassword ( const char * password )

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

Parameters

[in] password new 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)

◆ netFTPs_SetPort()

netStatus netFTPs_SetPort ( uint16_t port )

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

Parameters

[in] port port 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) {
    netFTPs_Stop();
  }
  netFTPs_SetPort (port);
  netFTPs_Start();
}

◆ netFTPs_SetRootPath()

netStatus netFTPs_SetRootPath ( const char * path )

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

Parameters

[in] path new 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. This path is common to all FTP server users.

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.

You can change the root path until the user logs on to the server. Once the user is authenticated, the root path can no longer be changed. This simple solution allows the root folder to be mapped to the user when logging on to the server. For example to access two drives, it is therefore necessary to create two user profiles, one has a root folder on the first drive (i.e "M:") and the other on the second drive (i.e. "F:"). The root path can be changed in the netFTPs_CheckUsername or in the netFTPs_CheckPassword function. To access another drive, the user must log out and then log on with other credentials.

Possible netStatus return values:

netOK: Root path successfully set.
netInvalidParameter: Invalid path parameter provided.
netWrongState: FTP server is running and the user is logged in.
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

uint8_t netFTPs_CheckUsername ( const char *username) {
  if (strcmp (username, "DRIVE_M") == 0) {
    netFTPs_SetRootPath ("M:");
    return (1);
  }
  if (strcmp (username, "DRIVE_F") == 0) {
    netFTPs_SetRootPath ("F:");
    return (2);
  }
  return (0);
}

◆ netFTPs_SetUsername()

netStatus netFTPs_SetUsername ( const char * username )

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

Parameters

[in] username new 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");
}

◆ netFTPs_Start()

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.h, 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)

◆ netFTPs_Stop()

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)