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
User Callbacks

Functions to notify the user application about events on the Telnet server. More...

Functions

uint32_t netTELNETs_ProcessCommand (const char *cmd, char *buf, uint32_t buf_len, uint32_t *pvar)
 Process and execute a command requested by the Telnet client. [user-provided]. More...
 
uint32_t netTELNETs_ProcessMessage (netTELNETs_Message msg, char *buf, uint32_t buf_len)
 Request a message for a Telnet server session. [user-provided]. More...
 

Description

Functions to notify the user application about events on the Telnet server.

The netTELNETs_ProcessCommand function processes the Telnet command when it is received from a remote client. A command is any sequence of characters that is terminated by the CRLF sequence (the Enter key is pressed). The Telnet server assembles this command and passes it as an argument to the netTELNETs_ProcessCommand function. This function then generates a reply message and sends it back to the user. It is part of the Telnet_Server_UIF.c template file.

When the reply message is short, the whole message can be sent in a single TCP packet. However, when long reports are generated, multiple TCP packets must be sent to transfer the whole message. For example, when the log files are displayed this is often the case. Both single and multiple packets are supported by the Embedded Telnet Server.

Short Reply

In the following example, the Telnet command HELP is sent by the Telnet client:

cmd> HELP

This command is answered by the predefined help message telnet_help. This message is copied to the output buffer and sent to the remote Telnet client. The following code sends the reply message:

uint32_t netTELNETs_ProcessCommand (const char *cmd, char *buf, uint32_t buf_len, uint32_t *pvar) {
..
if (netTELNETs_CheckCommand (cmd, "HELP") == true) {
// HELP command, print help text
len = sprintf (buf, telnet_help);
return (len);
}
..
}

Long Reply

A long reply message requires multiple calls to the function netTELNETs_ProcessCommand. Each call to this function generates part of the reply message until the entire message is generated and sent. To distinguish between different calls to the function, the argument pvar is used. This argument is a pointer to a variable that is set to 0 on the first call and not altered on each subsequent call to this function. The function's return value, which specifies the number of bytes in the reply message, cannot exceed 1500. Hence the high bits of the function's return value are used to store the flags:

In the following example, the MEAS command is given by the user using the Telnet client.

cmd> MEAS

When a new Telnet command is received, the function netTELNETs_ProcessCommand is called with the argument pvar set to 0. The command buffer cmd is checked to identify the command.

uint32_t netTELNETs_ProcessCommand (const char *cmd, char *buf, uint32_t buf_len, uint32_t *pvar) {
uint32_t len = 0;
switch (MYBUF(pvar)->id) {
case 0:
// First call to this function
break;
case 1:
// Command MEAS, repeated call
..
// Set request for another callback
return (len | (1u << 31));
..
}
if (netTELNETs_CheckCommand (cmd, "MEAS") == true) {
// MEAS command given, monitor analog inputs
MYBUF(pvar)->id = 1;
if (len > 5) {
uint32_t nmax;
sscanf (&cmd[5], "%u", &nmax);
if (nmax > 255) nmax = 255;
MYBUF(pvar)->nmax = nmax;
}
len = sprintf (buf, meas_header);
if (MYBUF(pvar)->nmax) {
// Bit-31 is a repeat flag
len |= (1u << 31);
}
return (len);
}
..
}

The above example uses 3 bytes of a storage variable pointed by pvar pointer for the following structure:

typedef struct {
uint8_t id;
uint8_t nmax;
uint8_t idx;
} MY_BUF;
#define MYBUF(p) ((MY_BUF *)p)

When the call to netTELNETs_ProcessCommand is repeated for the same command, the value of a storage variable pointed to by argument pvar is not altered any more. You can use the value of pvar to process the command differently. The pvar buffer now holds the private structure MYBUF, which is valid for the lifetime of processing the command. When the command processing is finished, this buffer is not used any more until the next command.

uint32_t netTELNETs_ProcessCommand (const char *cmd, char *buf, uint32_t buf_len, uint32_t *pvar) {
uint32_t len = 0;
switch (MYBUF(pvar)->id) {
case 0:
// First call to this function
break;
case 1:
// Command MEAS, repeated call
while (len < buf_len-80) {
// Let's use as much of the buffer as possible
len += sprintf (buf+len, "\r\n%4d", MYBUF(pvar)->idx);
for (val = 0; val < 8; val++) {
len += sprintf (buf+len, "%7d", AD_in(val));
}
if (++MYBUF(pvar)->idx >= MYBUF(pvar)->nmax) {
// Requested number of measurements done
return (len);
}
}
// Set request for another callback
return (len | (1u << 31));
case 2:
// Repeated call, TCP status display
..
}

After giving a meas 4 command, the Telnet Client screen looks like this:

telnet_meas.png
Note
You can check the Telnet Server to see how it works.

Function Documentation

uint32_t netTELNETs_ProcessCommand ( const char *  cmd,
char *  buf,
uint32_t  buf_len,
uint32_t *  pvar 
)

Process and execute a command requested by the Telnet client. [user-provided].

Parameters
[in]cmdpointer to command string from Telnet client.
[out]bufoutput buffer to write the return message to.
[in]buf_lenlength of the output buffer in bytes.
[in,out]pvarpointer to a session's local buffer of 4 bytes.
  • 1st call = cleared to 0.
  • 2nd call = not altered by the system.
  • 3rd call = not altered by the system, etc.
Returns
number of bytes written to output buffer.
  • return len | (1u<<31) = repeat flag, the system calls this function again for the same command.
  • return len | (1u<<30) = disconnect flag, the system disconnects the Telnet client.

The callback function netTELNETs_ProcessCommand processes and executes the command requested by the Telnet client. The Network Component's Telnet server calls the function when it receives the consecutive Carriage Return (CR) and Line Feed (LF) character sequence from the Telnet client (this is usually produced by the user pressing Enter on the Telnet client terminal).

The argument cmd points to the message containing the command that is received from the Telnet client.

The argument buf points to the output buffer where the netTELNETs_ProcessCommand must write the message to be returned to the Telnet client.

The argument buf_len specifies the length of the output buffer in bytes.

The argument pvar is a pointer to a local session buffer with a length of 4 bytes. The Telnet Server clears the data in the pvar pointer to 0 before the function is called for the first time in each session, and never changes it later. You can use *pvar as a repeat counter or simply to distinguish between different function calls.

Note
The Telnet server does not automatically expand the CR character. The function must write the CR and LF characters into the buffer to indicate the end of each message.

Code Example

The following example is available in the user code template file Telnet_Server_UIF.c. Customize it to the application's needs.

uint32_t netTELNETs_ProcessCommand (const char *cmd, char *buf, uint32_t buf_len, uint32_t *pvar) {
uint32_t len = 0;
..
if (netTELNETs_CheckCommand (cmd, "LED0=ON") == true) {
// Switch ON LED0
len = sprintf (buf," Ok");
return (len);
}
if (netTELNETs_CheckCommand (cmd, "LED0=OFF") == true) {
// Switch OFF LED0
len = sprintf (buf," Ok");
return (len);
}
..
}
uint32_t netTELNETs_ProcessMessage ( netTELNETs_Message  msg,
char *  buf,
uint32_t  buf_len 
)

Request a message for a Telnet server session. [user-provided].

Parameters
[in]msgcode of requested message.
[out]bufoutput buffer to write the message to.
[in]buf_lenlength of the output buffer in bytes.
Returns
number of bytes written to output buffer.

The callback function netTELNETs_ProcessMessage provides the connection and login messages to the Telnet server, when requested. The Telnet server sends these messages to the Telnet client.

The argument msg specifies the type of message that the Telnet server requires:

Message Description
netTELNETs_MessageWelcome Initial welcome message
netTELNETs_MessageLogin Login message, if authentication is enabled
netTELNETs_MessageUsername Username request login message
netTELNETs_MessagePassword Password request login message
netTELNETs_MessageLoginFailed Incorrect login error message
netTELNETs_MessageLoginTimeoutLogin timeout error message
netTELNETs_MessagePrompt Prompt message
netTELNETs_MessageUnsolicited Unsolicited message (triggered by netTELNETs_RequestMessage)

The argument buf points to the output buffer where the netTELNETs_ProcessMessage must write the message.

The argument buf_len specifies the length of the output buffer in bytes.

Note
  • The length of the output buffer (buf_len), might vary because buffer length is determined by the TCP socket Maximum Segment Size (MSS) negotiation. It is normally around 1400 bytes for local LAN. But this can be reduced to 500 bytes or even less.
  • If the netTELNETs_ProcessMessage function writes more bytes than buf_len into the output buffer, then a system crash resulting from corruption of memory link pointers is highly likely.
  • The Telnet server does not automatically expand the carriage return (CR) character. The netTELNETs_ProcessMessage function must write the carriage return and line feed (LF) characters into the buffer to indicate the end of each message.

Code Example

The following example is available in the user code template file Telnet_Server_UIF.c. Customize it to the application's needs.

uint32_t netTELNETs_ProcessMessage (netTELNETs_Message msg, char *buf, uint32_t buf_len) {
uint32_t len = 0;
switch (msg) {
// Initial welcome message
len = sprintf (buf, "\r\n"
"Embedded Telnet Server\r\n");
break;
// Prompt message
len = sprintf (buf, "\r\n"
"Cmd> ");
break;
// Login message, if authentication is enabled
len = sprintf (buf, "\r\n"
"Please login...");
break;
// Username request login message
len = sprintf (buf, "\r\n"
"Username: ");
break;
// Password request login message
len = sprintf (buf, "\r\n"
"Password: ");
break;
// Incorrect login error message
len = sprintf (buf, "\r\n"
"Login incorrect");
break;
// Login timeout error message
len = sprintf (buf, "\r\n"
"Login timeout\r\n");
break;
// Unsolicited message (ie. from basic interpreter)
len = sprintf (buf, "\r\n"
"Unsolicited message\r\n");
break;
}
return (len);
}