cgi_func

#include <net_config.h>

U16 cgi_func (
    U8*  env,       /* Pointer to input string from a TCPnet script. */
    U8*  buf,       /* Location where to write the HTTP response string. */
    U16  buflen,    /* Number of bytes in the output buffer. */
    U32* pcgi );    /* Pointer to a storage variable. */

The cgi_func function is what the TCPnet script interpreter calls, when interpreting the TCPnet script, to output the dynamic part of the HTTP response. The script interpreter calls cgi_func for each line in the script that begins with the command c. You must customize the cgi_func function so that it can understand and use the input string from the TCPnet script.

The argument env is a pointer to the input string that cgi_func uses to create the dynamic response. It is the same string of bytes that is specified in the TCPnet script code using the c command.

The argument buf is a pointer to the output buffer where the cgi_func function must write the HTTP response.

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

The argument pcgi is a pointer to a variable that never gets altered by the HTTP Server. Hence, you can use it to store parameters for successive calls of the cgi_func function. You might use this to store:

• loop counters
• number of sent bytes
• pointer to a local status buffer.

The cgi_func function is part of RL-TCPnet. The prototype is defined in net_config.h. You can customize the function in http_cgi.c.

note

• The contents written by the cgi_func function, into the output buffer, must be HTML code.
• c is a command that is available in the TCPnet scripting language.
• The length of the output buffer, buflen, might vary because buffer length is determined by the TCP socket Maximum Segment Size (MSS) negotiation. The buffer length is normally around 1400 bytes for local LAN. But this can be reduced to 500 bytes or even less.
• The length of the output buffer, buflen also varies because the HTTP Server tries to optimize number of generated TCP packets. It calls this function again to use the complete buffer available. It stops when there is only 240 or less bytes freee in the buffer. Then the packet is generated and transmitted. If you want to force the HTTP Server to transmit the packet, return value from this function shall be or-ed with 0x4000.
• If the cgi_func function writes more bytes than buflen into the output buffer, then a system crash resulting from corruption of memory link pointers is highly likely.
• The input string env might contain single-character subcommands to tell the cgi_func function how to process the script line correctly. There is no rule for these subcommands, so you can create and use your own commands.
• The argument pcgi is private to each HTTP Session. The HTTP Server clears the data in the pcgi pointer, to 0, before the cgi_func function is called for the first time in each session.
• The cgi_func function must update the contents in pcgi for each call. You can use the 4 bytes in pcgi to store data in any format.

The cgi_func function returns the number of bytes written to the output buffer and writes the repeat flag value in the most significant bit of the return value.

If the return value's most significant bit is set to 1 (return value or-ed with 0x8000), the TCPnet script interpreter calls the cgi_func function again with the same values for the arguments env, buflen, and pcgi, which holds the same content as previously set. The argument buf is adjusted according to the number of bytes that were written to the output buffer.

If the return value's second most significant bit is set to 1 (return value or-ed with 0x4000), the packet optimization is canceled and the current packet is transmitted immediatelly.

U16 cgi_func (U8 *env, U8 *buf, U16 buflen, U32 *pcgi)
{
   U16 len = 0;

   switch (env[0]) {
      /* Analyze the environment string. It is the script 'c' line starting */
      /* at position 2. What you write to the script file is returned here. */
      case 'a' :
         /* Network parameters - file 'network.cgi' */
          .
          .
         break;

      case 'b':
         /* LED control - file 'led.cgi' */
          .
          .
         break;

      case 'c':
         /* TCP status - file 'tcp.cgi' */
          .
          .
         break;

      case 'd':
         /* System password - file 'system.cgi' */
         switch (env[2]) {
            case '1':
               len = sprintf(buf,&env[4],http_EnAuth ? "Enabled" : "Disabled");
               break;
            case '2':
               len = sprintf(buf,&env[4],http_auth_passw);
               break;
         }
         break;
   }
   return (len);
}