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].
uint32_t	netTELNETs_ProcessMessage (netTELNETs_Message msg, char *buf, uint32_t buf_len)
	Request a message for a Telnet server session. [user-provided].

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:

• Repeat flag - bit 31
  This flag tells the Telnet Server whether the function netTELNETs_ProcessCommand must be called again or not (because the command processing is complete). The return value must be OR-ed with 1u<<31 to call the function again.
• Disconnect flag - bit 30
  This flag tells the Telnet Server to disconnect the Telnet connection. If this flag is set, the Telnet Server disconnects the current Telnet session. The return value must be OR-ed with 1u<<30 to disconnect.

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:

Note

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

Function Documentation

netTELNETs_ProcessCommand()

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]	cmd	pointer to command string from Telnet client.
[out]	buf	output buffer to write the return message to.
[in]	buf_len	length of the output buffer in bytes.
[in,out]	pvar	pointer 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);
  }
  ..
}

netTELNETs_ProcessMessage()

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]	msg	code of requested message.
[out]	buf	output buffer to write the message to.
[in]	buf_len	length 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_MessageLoginTimeout	Login 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) {
    case netTELNETs_MessageWelcome:
      // Initial welcome message
      len = sprintf (buf, "\r\n"
                          "Embedded Telnet Server\r\n");
      break;
 
    case netTELNETs_MessagePrompt:
      // Prompt message
      len = sprintf (buf, "\r\n"
                          "Cmd> ");
      break;
 
    case netTELNETs_MessageLogin:
      // Login message, if authentication is enabled
      len = sprintf (buf, "\r\n"
                          "Please login...");
      break;
 
    case netTELNETs_MessageUsername:
      // Username request login message
      len = sprintf (buf, "\r\n"
                          "Username: ");
      break;
 
    case netTELNETs_MessagePassword:
      // Password request login message
      len = sprintf (buf, "\r\n"
                          "Password: ");
      break;
 
    case netTELNETs_MessageLoginFailed:
      // Incorrect login error message
      len = sprintf (buf, "\r\n"
                          "Login incorrect");
      break;
 
    case netTELNETs_MessageLoginTimeout:
      // Login timeout error message
      len = sprintf (buf, "\r\n"
                          "Login timeout\r\n");
      break;
 
    case netTELNETs_MessageUnsolicited:
      // Unsolicited message (ie. from basic interpreter)
      len = sprintf (buf, "\r\n"
                          "Unsolicited message\r\n");
      break;
  }
  return (len);
}