Control Interface

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

Functions
netStatus	netTELNETs_Start (void)
	Start the Telnet server. [thread-safe].
netStatus	netTELNETs_Stop (void)
	Stop the Telnet server. [thread-safe].
bool	netTELNETs_Running (void)
	Check if the Telnet server is running. [thread-safe].
uint16_t	netTELNETs_GetPort (void)
	Get port number of the Telnet server. [thread-safe].
netStatus	netTELNETs_SetPort (uint16_t port)
	Set port number of the Telnet server. [thread-safe].
const char *	netTELNETs_GetUsername (void)
	Retrieve username of the built-in user account. [thread-safe].
netStatus	netTELNETs_SetUsername (const char *username)
	Set username of the built-in user account. [thread-safe].
const char *	netTELNETs_GetPassword (void)
	Retrieve password of the built-in user account. [thread-safe].
netStatus	netTELNETs_SetPassword (const char *password)
	Reset password of the built-in user account. [thread-safe].
bool	netTELNETs_LoginActive (void)
	Determine if Telnet server authentication is enabled. [thread-safe].
netStatus	netTELNETs_LoginOnOff (bool login)
	Enable or disable Telnet server authentication. [thread-safe].
netStatus	netTELNETs_GetClient (NET_ADDR *addr, uint32_t addr_len)
	Get IP address and port number of a connected Telnet client. [thread-safe].
int32_t	netTELNETs_GetSession (void)
	Get current session number of the Telnet server. [thread-safe].
bool	netTELNETs_CheckCommand (const char *cmd, const char *user_cmd)
	Check command string for a command. [thread-safe].
netStatus	netTELNETs_RepeatCommand (uint32_t delay)
	Request a repeated call to netTELNETs_ProcessCommand function. [thread-safe].
netStatus	netTELNETs_RequestMessage (int32_t session)
	Request unsolicited message processing in netTELNETs_ProcessMessage function. [thread-safe].

Description

Functions to work with the Telnet server.

Like all services, the Telnet 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 Telnet server needs to be started manually in the user application using netTELNETs_Start. At runtime, it is always possible to stop the Telnet server using the function netTELNETs_Stop. The user application can check for a running server using the netTELNETs_Running function.

To change the port of the Telnet server at runtime, first call netTELNETs_Stop (if the server is running) and then use the netTELNETs_SetPort function. Afterwards, the Telnet server needs to be (re-)started by the application calling netTELNETs_Start.

Code Example

void change_server_port (uint16_t port) {
  if (netTELNETs_Running() == true) {
    netTELNETs_Stop();
  }
  netTELNETs_SetPort (port);
  netTELNETs_Start();
}

The Telnet server supports a built-in user account if the TELNET_SERVER_AUTH_ADMIN is set to 1. In this case, the user specified by TELNET_SERVER_AUTH_USER is created and the password TELNET_SERVER_AUTH_PASS is used for this user. The Telnet server control interface provides functions to work with this built-in account. To retrieve the username in the application, use netTELNETs_GetUsername. To change this username at runtime, use netTELNETs_SetUsername. The same pair of functions is available for managing the password (netTELNETs_GetPassword / netTELNETs_SetPassword).

It is also possible to check if this login is active (netTELNETs_LoginActive) and to enable or disable it at runtime using netTELNETs_LoginOnOff. Please note that the function netTELNETs_LoginOnOff is only available at runtime if the define TELNET_SERVER_AUTH_ENABLE is set to 1 in the Net_Config_Telnet_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.

The command line interface functions are located in the Telnet_Server_UIF.c template file. You must add this file to your project and customize it. You can add new commands or remove existing commands from the file. To add the template file to your project, simply right-click on the Source group, select Add New Item to Group, then click on User Code Template and scroll in the template files list until you find the Telnet Server template.

Function Documentation

netTELNETs_CheckCommand()

bool netTELNETs_CheckCommand	(	const char *	cmd,
		const char *	user_cmd
	)

Check command string for a command. [thread-safe].

Parameters

[in]	cmd	pointer to command string from Telnet client.
[in]	user_cmd	user command to check for (in upper case).

Returns

• true = Command found in command string.
• false = Command not found.

The function netTELNETs_CheckCommand compares the command in the buffer cmd with the string user_cmd.

The argument cmd is null-terminated or space-separated command line string from the client.

The argument user_cmd is a user command to compare with, which is a null-terminated string in upper case.

Code Example (see netTELNETs_ProcessCommand)

netTELNETs_GetClient()

netStatus netTELNETs_GetClient	(	NET_ADDR *	addr,
		uint32_t	addr_len
	)

Get IP address and port number of a connected Telnet client. [thread-safe].

Parameters

[out]	addr	structure that will receive IP address and port number.
[in]	addr_len	size of NET_ADDR structure for the client.

Returns

status code that indicates the execution status of the function.

The function netTELNETs_GetClient provides information about the remote machine that has connected to the Telnet server.

The argument addr points to a structure that will receive the IP address and port of the remote machine.

The argument addr_len specifies the length of the addr structure. Using IPv4 only, you can optimize memory usage by specifying an addr_len that is equal to the size of NET_ADDR4 (8 bytes). The Telnet server checks the addr_len argument, whether it can enter the IP address of the client into the structure.

Possible netStatus return values:

• netOK: Operation completed successfully.
• netInvalidParameter: Invalid parameter provided.
• netWrongState: Server session not active.

Note

Use this function to restrict machines from performing system changes.

Code Example

NET_ADDR client;
char ip_ascii[40];
 ..
netTELNETs_GetClient (&client, sizeof(client));
netIP_ntoa (client.addr_type, client.addr, ip_ascii, sizeof(ip_ascii));
printf ("IP address: %s\n", ip_ascii);
printf ("TCP port:   %d\n", client.port);

netTELNETs_GetPassword()

const char * netTELNETs_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 netTELNETs_GetPassword returns the password of the built-in user if TELNET_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_Telnet_Server.h file. If this define is set to 0, the function is not available at runtime and returns NULL.

Code Example (see netTELNETs_LoginActive)

netTELNETs_GetPort()

uint16_t netTELNETs_GetPort

(

void

)

Get port number of the Telnet server. [thread-safe].

Returns

port number.

The function netTELNETs_GetPort returns the port that is used for the Telnet server.

Code Example

printf ("Telnet server is listening on port %d\n", netTELNETs_GetPort ());

netTELNETs_GetSession()

int32_t netTELNETs_GetSession

(

void

)

Get current session number of the Telnet server. [thread-safe].

Returns

current session number.

The function netTELNETs_GetSession retrieves the current session number of the Telnet server for further usage. The session number can be used, when multiple Telnet clients are connected at the same time.

Code Example

uint32_t netTELNETs_ProcessMessage (netTELNETs_Message msg, char *buf, uint32_t buf_len) {
  uint32_t len = 0;
 
  switch (msg) {
     ..
    case netTELNETs_MessagePrompt:
      // Prompt message (with user id)
      len = sprintf (buf, "\r\n"
                          "User%d> ", netTELNETs_GetSession());
      break;
     ..
  }
  return (len);
}

netTELNETs_GetUsername()

const char * netTELNETs_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 netTELNETs_GetUsername returns the user name of the built-in user if TELNET_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_Telnet_Server.h file. If this define is set to 0, the function is not available at runtime and returns NULL.

Code Example (see netTELNETs_LoginActive)

netTELNETs_LoginActive()

bool netTELNETs_LoginActive

(

void

)

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

Returns

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

The function netTELNETs_LoginActive checks if the Telnet server is set up for user authentication.

Code Example

if (netTELNETs_LoginActive() == true) {
  printf ("Authentication is enabled\n");
  printf ("Username is: %s\n", netTELNETs_GetUsername());
  printf ("Password is: %s\n", netTELNETs_GetPassword());
}

netTELNETs_LoginOnOff()

netStatus netTELNETs_LoginOnOff

(

bool

login

)

Enable or disable Telnet 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 netTELNETs_LoginOnOff enables or disables the user authentication on the Telnet server. If TELNET_SERVER_AUTH_ENABLE is set to 0 in the Net_Config_Telnet_Server.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 (netTELNETs_LoginActive () == true) {
  netTELNETs_LoginOnOff (false);
}

netTELNETs_RepeatCommand()

netStatus netTELNETs_RepeatCommand

(

uint32_t

delay

)

Request a repeated call to netTELNETs_ProcessCommand function. [thread-safe].

Parameters

[in]

delay

time period to wait in number of 100ms ticks.

Returns

status code that indicates the execution status of the function.

The function netTELNETs_RepeatCommand ensures that the Telnet server does not call the netTELNETs_ProcessCommand function until a certain time period expires. When a timeout expires, the Telnet server calls netTELNETs_ProcessCommand function again, with the same content of cmd argument. This continuously updates information on the client screen. The end-less calling of netTELNET_ProcessCommand is terminated, when a user presses any key in the Telnet client.

The argument delay specifies the time period to wait, in number of timer ticks.

Possible netStatus return values:

• netOK: Repeat command requested successfully.
• netInvalidParameter: Invalid parameter provided.
• netWrongState: Server is not updating the client screen.

Code Example

uint32_t netTELNETs_ProcessCommand (const char *cmd, char *buf, uint32_t buf_len, uint32_t *pvar) {
  static uint32_t timer;
  uint32_t len = 0;
 
  switch (*pvar) {
    case 0:
      // New command received
      if (netTELNETs_CheckCommand (cmd, "TIMER") == true) {
        // TIMER command given
        *pvar = 1;
        timer = 0;
        len   = sprintf (buf, CLS);
        return (len | (1u << 31));
      }
       ..
      break;
 
    case 1:
      // Command TIMER, repeated call
      len = sprintf (buf, "Timer = %d", ++timer);
      // Repeat a command after 10 ticks (1 second)
      netTELNETs_RepeatCommand (10);
      // Set request for another callback
      return (len | (1u << 31));
  }
  return (len);
}

netTELNETs_RequestMessage()

netStatus netTELNETs_RequestMessage

(

int32_t

session

)

Request unsolicited message processing in netTELNETs_ProcessMessage function. [thread-safe].

Parameters

[in]

session

session identification, when multiple connections are active.

Returns

status code that indicates the execution status of the function.

The function netTELNETs_RequestMessage is used to pass unsolicited messages to the Telnet server. It needs to be called by the user application when unsolicited message is ready. The content of unsolicited message is passed to the Telnet server in the netTELNETs_ProcessMessage function.

The Telnet session handle parameter session identifies the remote host when many Telnet connections are active at the same time.

Possible netStatus return values:

• netOK: Unsolicited message requested successfully.
• netInvalidParameter: Invalid session provided.
• netWrongState: Server session not active.

Code Example

if (netTELNETs_RequestMessage (1) == netOK) {
  // Request accepted, wait for callback
}

netTELNETs_Running()

bool netTELNETs_Running

(

void

)

Check if the Telnet server is running. [thread-safe].

Returns

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

The function netTELNETs_Running checks whether the Telnet server is running. It returns true if the server is up and running.

Code Example (see netTELNETs_SetPort)

netTELNETs_SetPassword()

netStatus netTELNETs_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 netTELNETs_SetPassword sets the password of the built-in user if TELNET_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_Telnet_Server.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 netTELNETs_SetUsername)

netTELNETs_SetPort()

netStatus netTELNETs_SetPort

(

uint16_t

port

)

Set port number of the Telnet server. [thread-safe].

Parameters

[in]

port

port number.

Returns

status code that indicates the execution status of the function.

The function netTELNETs_SetPort sets the port that is to be used for the Telnet server. The Telnet server must not run while setting the port. If required, stop it first using netTELNETs_Stop.

The argument port specifies the port number to be used.

Possible netStatus return values:

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

Code Example

void change_server_port (uint16_t port) {
  if (netTELNETs_Running () == true) {
    netTELNETs_Stop ();
  }
  netTELNETs_SetPort (port);
  netTELNETs_Start ();
}

netTELNETs_SetUsername()

netStatus netTELNETs_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 netTELNETs_SetUsername sets the user name of the built-in user if TELNET_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_Telnet_Server.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 (netTELNETs_LoginActive() == true) {
  netTELNETs_SetUsername ("sysadmin");
  netTELNETs_SetPassword ("a$Min#77");
}

netTELNETs_Start()

netStatus netTELNETs_Start

(

void

)

Start the Telnet server. [thread-safe].

Returns

status code that indicates the execution status of the function.

The function netTELNETs_Start starts the Telnet server at runtime. It can be stopped again using netTELNETs_Stop.

Possible netStatus return values:

• netOK: Telnet 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 Telnet server previously using netTELNETs_Stop or have set NET_START_SERVICE to 0.

Code Example (see netTELNETs_SetPort)

netTELNETs_Stop()

netStatus netTELNETs_Stop

(

void

)

Stop the Telnet server. [thread-safe].

Returns

status code that indicates the execution status of the function.

The function netTELNETs_Stop stops the Telnet server at runtime. It can be restarted using netTELNETs_Start.

Possible netStatus return values:

• netOK: Telnet server stopped successfully.

Code Example (see netTELNETs_SetPort)