The EtherSmart Wildcard Glossary

<< Previous | Next>>

C:   uint HTTP_Inbufsize ( int modulenum )

4th: HTTP_Inbufsize      ( modulenum -- u )

      Returns the size of the HTTP_Inbuf default input buffer which is set by Ether_Init, Ether_Setup, and/or HTTP_Set_Inbuf for the specified EtherSmart module. Note that the allocated buffer size must be 2 bytes bigger than the maxnumbytes parameter passed to Ether_Init or HTTP_Set_Inbuf; these 2 bytes provide room to store the 16- bit count at the start of the lbuffer. The Ether_Setup function initializes HTTP_Inbufsize to HTTP_INBUFSIZE_DEFAULT = 254, with an allocated buffer size of 256 bytes. See HTTP_Inbuf.

C:   HTTP_INBUFSIZE_DEFAULT

4th: HTTP_INBUFSIZE_DEFAULT

      A 16-bit constant that returns the value 254.  This constant is used by Ether_Setup to specify the size of the HTTP_Inbuf buffer and is returned by HTTP_Inbufsize after Ether_Setup is executed.  The buffer is allocated as 256 bytes, comprising a 2-byte count stored in the first 2 bytes of the buffer, followed by the 254 maximum bytes of data in the buffer.

C:   xaddr HTTP_Index_Ptr ( int modulenum )

4th: HTTP_Index_Ptr     ( modulenum -- xaddr )

      Returns the xaddress within the ether_info struct for the specified EtherSmart module that holds a 16-bit index to the next available row in the HTTP autoserve array.  The value of this index is used by HTTP_Add_Handler and HTTP_Add_GUI_Handler to specify the row in the autoserve array that will receive the next handler/URL pair.  The contents of HTTP_Index_Ptr are zeroed by Ether_Info_Init and its callers (Ether_Init, Ether_Setup, etc.) and incremented by HTTP_Add_Handler and HTTP_Add_GUI_Handler.  This index typically does not need to be modified by the programmer.

C:   void HTTP_Is_Autoserve_Array ( xaddr xarraybase, int numrows, int modulenum )

C:   uint HTTP_Numbytes_Sent ( int modulenum )

4th: HTTP_Numbytes_Sent   ( modulenum -- u )

      Returns the contents of the 16-bit numbytes_sent field located in the ether_info structure for the specified EtherSmart module.  This variable is set by the functions that send data, including Ether_Send_Buffer, Ether_Send_LBuffer, Ether_Send_2Buffers, HTTP_Send_Buffer, HTTP_Send_LBuffer, HTTP_Send_2Buffers, HTTP_GUI_Send_Buffer, HTTP_ GUI_Send_LBuffer, and  HTTP_ GUI_Send_2Buffers. The first 3 functions mentioned also return the number of bytes sent as the least significant 16-bits in ether_response.

C:   xaddr HTTP_Outbuf ( int modulenum )

4th: HTTP_Outbuf ( modulenum -- xaddr )

      Returns the 32-bit extended base address of the default web service buffer for outgoing bytes to the Ethernet for the given module. This buffer is available for use by the programmer to code web service handlers, and is typically (but not necessarily) passed as the target output buffer to functions such as HTTP_Put_Header, HTTP_Put_Content_Type, HTTP_Send_Buffer, HTTP_Send_LBuffer, HTTP_Send_2Buffers, HTTP_GUI_Send_Buffer, HTTP_GUI_Send_LBuffer, and HTTP_GUI_Send_2Buffers. Note that HTTP_Send_LBuffer and HTTP_GUI_Send_LBuffer expect to find the 16-bit count stored in the first 2 bytes of the buffer, with the data following. The convenient HTTP_Outbuf_Cat function adds a specified string to HTTP_Outbuf.  See also HTTP_Set_Outbuf.

      NOTE: HTTP_Outbuf or another dedicated buffer should be used by HTTP handler functions to hold web data content.  If services other than HTTP are in use, general purpose buffers such as Ether_Outbuf should not be used for HTTP web service handlers which are dispatched from the Ethernet task, as the asynchronous user and Ethernet tasks might try to write conflicting data into a buffer that is not dedicated to a single service.

C:   void HTTP_Outbuf_Cat ( xstring\count\modulenum -- )

4th: HTTP_Outbuf_Cat  ( xaddr xstring, uint count, int modulenum )

      Concatenates the specified string plus a terminating carriage return and linefeed to the specified module’s HTTP_Outbuf buffer, and increments the buffer count that is stored in the first two bytes of HTTP_Outbuf. The string is specified by the extended 32-bit address xstring of its first character, and has count bytes to be added to the HTTP_Outbuf buffer. An end-of-line sequence equal to 0x0D0A (carriage return and linefeed) is post-pended to the HTTP_Outbuf after the string is added. This routine clamps the maximum number of bytes in the destination buffer to the value returned by HTTP_Outbufsize (this value does not include the 2-byte count stored at the start of Ether_Outbuf). This function is useful for building up strings to be sent out via web handler functions via the dynamic webserver.

      NOTE: Before adding the first string, be sure to store a 16-bit zero into the xaddress returned by HTTP_Outbuf for the specified module; this initializes the counted lbuffer to its starting size of zero.

C:   uint HTTP_Outbufsize ( int modulenum )

4th: HTTP_Outbufsize   ( modulenum -- u )

      Returns the size of the HTTP_Outbuf default web service output buffer for the specified EtherSmart module which is set by Ether_Init, Ether_Setup, and/or HTTP_Set_Outbuf. This buffer is available for use by the programmer to code web service handlers. Note that the allocated buffer size must be 2 bytes bigger than the maxnumbytes parameter passed to Ether_Init or HTTP_Set_Outbuf; these 2 bytes provide room to store the 16- bit count at the start of the lbuffer. The Ether_Setup function initializes HTTP_Outbufsize to HTTP_OUTBUFSIZE_DEFAULT = 1022, with an allocated buffer size of 1024 bytes (1 Kbyte).

C:   HTTP_OUTBUFSIZE_DEFAULT

4th: HTTP_OUTBUFSIZE_DEFAULT

      A 16-bit constant that returns the value 1022.  This constant is used by Ether_Setup to specify the size of the HTTP_Outbuf buffer and is returned by HTTP_Outbufsize after Ether_Setup is executed.  The buffer is allocated as 1024 bytes, comprising a 2-byte count stored in the first 2 bytes of the buffer, followed by the 1022 maximum bytes of data in the buffer.

C:   void HTTP_Parse_URL ( xaddr xstring, int max_count, int modulenum )

4th: HTTP_Parse_URL   ( xaddr xstring\max_count\modulenum -- )

      Parses the URL (Universal Resource Locator, as described below in this glossary entry) by setting several pointers and string length variables that are used by additional user-callable parsing utilities. This function is not typically invoked by the programmer, because it is automatically called by the Ethernet task running Ether_Service_Loop when a passive incoming connection is identified as a web connection by the presence of a leading GET substring. The input parameter xstring specifies the 32-bit xaddress of the first character in the string which starts after the space after GET in the HTTP_Inbuf buffer. The max_count parameter is constrained by HTTP_Inbufsize, and may include more characters and/or more lines than the URL itself.  This routine skips any leading spaces (typically not present), then scans for the required trailing space after the URL, then sets HTTP_URL_Full_Count, scans for the ? char (if any) which starts the query portion of the url and stores its offset (or the offset to the final BL) in HTTP_Fieldname_Ptr, then un-escapes the base portion (not including query fields) of the resulting URL, and sets HTTP_URL_Base_Count. The unescape process replaces each HTTP 3-character escape sequence %hexhex (where hex is a hexadecimal digit) with its equivalent single ascii character corresponding to the 2-digit hexadecimal value.  If there was no trailing blank in the url buffer as required by the HTTP standard, then this routine sets HTTP_URL_Full_Count = HTTP_URL_Base_Count = 0. This function enables the operation of a set of user-callable functions including HTTP_Parse_URL, HTTP_Fieldname_Ptr, HTTP_Fieldname_Count, HTTP_Value_Ptr, HTTP_Value_Count, HTTP_To_Next_Field, as HTTP_Plus_To_Space, and HTTP_Unescape to simplify the handling of query fields by HTTP handler functions.  See the glossary entry of HTTP_Imagemap function for information on how to handle an HTTP GUI “remote front panel” web request.

      Notes about the URL: URL means Universal Resource Locator.  In the context of this driver code, it means the string that appears in the web browser’s address bar starting with the / character after the domain name or IP address.  If only the IP address or corresponding name is present in the address bar, the browser will send the URL as a single / character.  Consequently, it is recommended that when defining a set of webserver pages, you always include a URL with a single / character as as a synonym for the home page URL, in case the user types only the IP address or machine name.  Typically, you’ll want to also declare the home page URL as

                    /index.html

      The URL starts with a / character and ends with either a terminating space (ascii 0x20) that is not included in the URL string countl, or with a ? (ascii 0x3F) character.  If the ? character is present, it indicates the presence of a query field following the ? that typically results from a “form object” or “imagemap” in the HTML code being displayed in the browser window. 

      URL Examples: If the XPort is assigned IP address 10.0.1.22, and the user types in the address bar of the browser:

                    10.0.1.22/form_entry.html

      then the browser opens a connection to port 80 (which we have defined as the EtherSmart Wildcard’s local port) and sends the following command:

                    GET /form_entry.html

      The GET is always capitalized and followed by a space, after which the URL appears in exactly the same case as it was typed in the browser’s address bar or in the HTML code that invoked it.  URL’s are case sensitive.  Let’s assume that the handler for the URL string /form_entry.html is the one described in the demo code that accompanies this driver.  Then when the “submit” button is pressed after the user fills in the form, the browser opens a connection and sends a request of the form:

                    GET /form_response.cgi?classification=man&name_id=tommy&color=blue

      In this case the URL is defined as

                    /form_response.cgi

      This is the string that is passed to HTTP_Add_Handler to associate the handler function with the URL.  The text after the URL starting with the ? character is the query portion of the URL.  Each “field” in the query comprises a fieldname followed by an = character followed by a field value.  Fields are separated by the & character.  A set of functions including HTTP_Parse_URL, HTTP_Fieldname_Ptr, HTTP_Fieldname_Count, HTTP_Value_Ptr, HTTP_Value_Count, and HTTP_To_Next_Field are available to simplify handling of query fields. Additional functions such as HTTP_Plus_To_Space and HTTP_Unescape deal with the “escaping” of special characters performed by a browser; see their glossary entries for details.

C:   void HTTP_Plus_To_Space ( xaddr xstring, int count )

4th: HTTP_Plus_To_Space    ( xstring\cnt -- )

      This function is handy for processing forms data sent by a browser as a GET statement. The browser typically replaces each space in a value string of a query field with a + sign.  This function accepts a substring in RAM whose first character is at the 32-bit xaddress xstring, with count characters.  This substring is typically generated by the functions HTTP_Value_Ptr and HTTP_Value_Count (see their glossary entries).  This function replaces any embedded ascii + characters in the specified substring with an ascii blank.

C:   void HTTP_Put_Content_Type ( xaddr xlbuffer, uint max_bufsize, int dynamic, int content_id)

4th: HTTP_Put_Content_Type       ( xlbuffer\max_bufsize\dynamic\content_id -- )

      Appends to the specified counted xlbuffer a substring containing the content type, an optional header line that prevents cacheing by the browser for dynamic webpages, and a single blank line to end the HTTP header. The xlbuffer is typically HTTP_Outbuf (see its glossary entry), and the max_bufsize is typically HTTP_Outbufsize, but other buffers dedicated to HTTP use can be specified. Adds the number of placed characters to the string count stored in the 2 bytes at xlbuffer, and appends the ascii characters following the initial buffer contents (as typically placed by HTTP_Put_Header).  The content_id is one of the following:

                    HTTP_TEXT_HTML_CONTENT                    HTTP_TEXT_PLAIN_CONTENT

                    HTTP_IMAGE_BITMAP_CONTENT             HTTP_IMAGE_PNG_CONTENT

                    HTTP_IMAGE_GIF_CONTENT                    HTTP_IMAGE_JPEG_CONTENT

                    HTTP_BINARY_DATA_CONTENT

      The names of these constants are self explanatory, but you can consult their glossary entries for more details.  This function places the content type string terminated with a carriage return and linefeed (crlf), and, if the dynamic input flag is true (nonzero), the string:

                    Cache-Control: no-cache

      with its terminating crlf is appended to the buffer.  If the dynamic flag is zero, this Cache-Control line is not appended. In all cases, a final crlf is appended to end the header with the required empty line. See the glossary entry for HTTP_Put_Header for a discussion of the required browser configuration for the EtherSmart embedded webserver when mixed content (other than all text) is served out in a single page.

      Notes about the no-cache directive: This is very important for dynamic web pages. If cacheing by the browser is not disabled, then the browser will feel free to use a version of the webpage that was served out via an earlier web request.  While this is very efficient for static web page content, it is a real problem if you want the web page to display the latest dynamic data such as the states of inputs, a system clock time, or the current state of the graphics screen.

C:   void HTTP_Put_Header ( xaddr xlbuffer, uint max_bufsize )

4th: HTTP_Put_Header ( xlbuffer\max_bufsize -- )

      Writes the following into the counted long buffer xlbuffer with maximum size max_bufsize:

                    HTTP/1.1 200 OK

                    Server: Mosaic Industries Embedded Webserver

                    Connection: close

                    Content-Type:

      There is a space after the Content-Type:  field.  The string count is stored in the 2 bytes at xlbuffer, with the ascii characters following.  With the addition of a valid content type, an optional line that prevents cacheing by the browser for dynamic webpages, and a single blank line to end the header as placed by HTTP_Put_Content_Type (see its glossary entry), this provides the required HTTP header required for a valid response to a GET request from a web browser.  This HTTP header is not to be confused with the <head> portion of an HTML web page.  All valid web responses, whether they include text or images, should begin with a valid HTTP header.  This header contains only the essential fields necessary for this simple webserver.  The HTTP/1.1 announces the webserver as an  HTTP/1.1 protocol server; the 200 OK means that the GET request has been received and a valid handler has been found that corresponds to the incoming URL (Universal Resource Locator; see HTTP_Add_Handler and HTTP_Add_GUI_Handler). The second line announces the name of the webserver. The third line means that the webserver will close each connection after the GET request has been fulfilled, and “persistent connections” are not supported.  The last line announces the content type which is typically filled in by HTTP_Put_Content_Type, but can also be accomplished using a Cat command with any arbitrary string to specify the content type. Note that one and only one empty line terminated by 0x0D0A (carriage return/linefeed) MUST follow the header; HTTP_Put_Content_Type does this for you. 

      Important Browser Notes: The Lantronix XPort hardware on the EtherSmart Wildcard supports only one active connection at a time.  However, the HTTP/1.1 standard (and consequently all browsers in their default configuration) expect the webserver to be able to host two simultaneous connections.  A default-configured browser will try to open a second connection when two or more content types (for example, text/html and image/bmp) are present in a single webpage.  The second connection will typically be refused by the XPort hardware, causing an incomplete page load.  The solution is to configure the browser to expect only one connection from the webserver.  We highly recommend the use of the free Opera web browser available for download at www.opera.com.  Simply go to www.opera.com and select “Download Opera”.  The download and install are quick, and the program is compact.  And, it’s very easy to configure for the single-connection EtherSmart webserver.  Once Opera is installed, simply go to its Tools menu, and select:

                    Preferences->Advanced->Network->Max Connections Per Server

      and enter 1 in the box.  Now you’re ready to use the Opera web browser with the EtherSmart Wildcard dynamic webserver.

C:   uint HTTP_Send_2Buffers ( xaddr xbuffer1, uint count1, xaddr xbuffer2, uint count2,

                    int modulenum )

4th: HTTP_Send_2Buffers ( xbuffer1\count1\ xbuferf2\count2\module--numbytes_sent)

      Sends to the EtherSmart Wildcard up to count1 bytes of data starting at the 32-bit extended memory address xbuffer1, and then sends up to count2 bytes of data starting at the 32-bit extended memory address xbuffer2. Returns the total number of bytes actually sent.  Unlike the Send_2Buffers function which is called directly by the main application task, this HTTP_Send_2Buffers function is called from within a user-specified webserver handler function which is invoked by the Ethernet task running the Ether_Service_Loop. (See HTTP_Add_Handler for details about how to post a web handler function). HTTP_Send_2Buffers does not send bytes if there is no connection, or if there has been a change in connection status (e.g., a transient disconnect) as detected by Ether_Disconnect_During_Send; in these cases, this routine increments the connection status value returned by Ether_Connect_Status to an odd value to flag the transient disconnect event. Any required end of line characters such as carriage return (0x0D) and linefeed (0x0A) characters must be in the buffers; they are not added by this routine. Each of the two send operations exits within within the time specified by the contents of HTTP_Timeout_Msec_Ptr whether or not the maximum number of bytes have been sent. See also HTTP_GUI_Send_2Buffers, HTTP_Put_Header, and HTTP_Put_Content_Type.

C:   uint HTTP_Send_Buffer ( xaddr xbuffer, uint count, int modulenum )

4th: HTTP_Send_Buffer        ( xbuffer\count\modulenum -- numbytes_sent )

      Sends to the EtherSmart Wildcard up to count bytes of data starting at the 32-bit extended memory address xbuffer, and returns the number of bytes actually sent.  Unlike the Send_Buffer function which is called directly by the main application task, this HTTP_Send_Buffer function is called from within a user-specified webserver handler function which is invoked by the Ethernet task running the Ether_Service_Loop. (See HTTP_Add_Handler for details about how to post a web handler function).  HTTP_Send_Buffer does not send bytes if there is no connection, or if there has been a change in connection status (e.g., a transient disconnect) as detected by Ether_Disconnect_During_Send; in these cases, this routine increments the connection status value returned by Ether_Connect_Status to an odd value to flag the transient disconnect event. Any required end of line characters such as carriage return (0x0D) and linefeed (0x0A) characters must be in the buffer; they are not added by this routine. This function exits within the time specified by the contents of HTTP_Timeout_Msec_Ptr whether or not the maximum number of bytes have been sent.  See also HTTP_Send_LBuffer, HTTP_GUI_Send_Buffer, HTTP_Put_Header, and HTTP_Put_Content_Type.

C:   uint HTTP_Send_LBuffer ( xaddr xlbuffer, int modulenum )

4th: HTTP_Send_LBuffer      ( xlbuffer\modulenum -- numbytes_sent )

      The xlbuffer parameter is a 32-bit extended address that holds the 16-bit buffer count followed by the buffer data. Fetches the count from xlbuffer and sends to the EtherSmart Wildcard up to count bytes of data that are located starting at xlbuffer+2. Returns the number of bytes actually sent.  Unlike the Send_LBuffer function which is called directly by the main application task, this HTTP_Send_LBuffer function is called from within a user-specified webserver handler function which is invoked by the Ethernet task running the Ether_Service_Loop. (See HTTP_Add_Handler for details about how to post a web handler function). HTTP_Send_LBuffer does not send bytes if there is no connection, or if there has been a change in connection status (e.g., a transient disconnect) as detected by Ether_Disconnect_During_Send; in these cases, this routine increments the connection status value returned by Ether_Connect_Status to an odd value to flag the transient disconnect event. Any required end of line characters such as carriage return (0x0D) and linefeed (0x0A) characters must be in the buffer; they are not added by this routine. This function exits within the time specified by the contents of HTTP_Timeout_Msec_Ptr whether or not the maximum number of bytes have been sent.  See also HTTP_Send_Buffer, HTTP_GUI_Send_LBuffer, HTTP_Put_Header, and HTTP_Put_Content_Type.

C:   uint HTTP_Server ( int modulenum )

4th: HTTP_Server ( modulenum -- )

      This function is automatically called by the Ether_Connection_Manager which is invoked by the Ether_Service_Loop in the Ethernet task.  It is a utility function that is typically not invoked by name.  This function serves out a web page to the current connection that has been identified as HTTP.  It looks up the incoming URL in the autoserve array and, if found, calls the associated handler and then closes the connection.  If the URL is not found, HTTP_Default_Handler is called to serve out the “Page not found” error to the browser.  Each web handler function posted by HTTP_Add_Handler or HTTP_Add_GUI_Handler must accept a single integer input parameter that specifies the EtherSmart modulenum, and must not return any values.  Every handler must send a valid HTTP header and content type, typically by executing HTTP_Put_Header and HTTP_Put_Content_Type before sending the referenced page content.  Standard (non-GUI) handler routines can perform as many send operations as needed to serve the page using HTTP_Send_Buffer, HTTP_Send_LBuffer, or HTTP_Send_2Buffers.  GUI handler functions that implement a web “remote front panel” must perform only one send operation to serve the page, using one of the functions using HTTP_GUI_Send_Buffer, HTTP_GUI_Send_LBuffer, or HTTP_GUI_Send_2Buffers; the latter function is the most commonly used.  See the glossary entries of HTTP_Add_Handler or HTTP_Add_GUI_Handler for more information.

      Implementation details: When a passive incoming connection is detected by the Ether_Connection_Manager running in the Ethernet task, it puts the first carriage-return/linefeed-delimited line into HTTP_Inbuf as a counted lstring (up to a maximum of HTTP_Inbufsize bytes) and looks for a leading GET substring to decide whether the connection is HTTP or serial tunneling.  This input operation times out in HTTP_Timeout_Msec if no lines are present. If the line does not identify as HTTP, it is declared as a serial tunneling connection and Ether_Connect_Status returns a value of PASSIVE_NON_WEB_CONNECTION which must be serviced by the application task. Note that if the connection is not identified as HTTP (because a leading GET substring is not found), the incoming bytes accepted by the Ether_Connection_Manager remain in the HTTP_Inbuf as an lstring (16-bit count followed by the data bytes) where they can be processed by the application program.  In this case, the application program learns of the accepted passive connection by polling the Ether_Connect_Status routine; see its glossary entry. If the line identifies as HTTP, this HTTP_Server webserver routine is called by the Ether_Connection_Manager. It invokes HTTP_Parse_URL (see its glossary entry) to parse the URL (web address string) in place in the HTTP_Inbuf, isolating the “base URL” from the query field (if any), and un-escaping any escape sequences in the base URL to prepare it for string matching to the posted URLs. Note that each posted URL should start with a / character, and for completeness, a URL comprising a single / character should be in the table in case the user points a browser at the bare ip address of the wildcard.  Then HTTP_Server compares the base URL to the entries in the autoserve array posted by HTTP_Add_Handler.  If a match is found, the web service request is automatically fulfilled by dispatching the posted handler for the URL, and then the connection is closed by the Ether_Connection_Manager. If there is no match to routines posted by HTTP_Add_Handler, this function looks for a match to the URLs posted by HTTP_Add_GUI_Handler.  If a match is found, the matching handler xcfa (with the modulenum packed into its most significant byte) is sent in the ether_gui_message mailbox.  If the web based “remote front panel” feature is supported by the application, the application task must poll the Ether_Check_GUI routine to receive this message when present.  If there is no match found at all for the received base URL in the autoserve array, the routine pointed to by HTTP_Default_Handler_Ptr is executed to serve out the “404 Not Found” error webpage.  Typically this is performed by HTTP_Default_Handler (see its glossary entry).  In all of these cases, after the handler has executed, the Ether_Connection_Manager closes the HTTP connection that was opened by the remote web browser.

      Notes on web handler functions posted by HTTP_Add_Handler: The handler function must accept one and only one 16-bit input parameter that specifies the EtherSmart modulenum, and it must not return any parameters.  For static web pages, the handler function typically sends the web page via a buffer in convenient chunks the size of the HTTP_Outbuf buffer or smaller until the file has been sent. Each handler can parse the query fields (if any) in the URL using the supplied parsing primitives: HTTP_To_Next_Field, HTTP_Fieldname_Ptr, HTTP_Fieldname_Count, HTTP_Value_Ptr, HTTP_Value_Count, HTTP_Unescape, and HTTP_Plus_To_Space. The user’s handler can call these routines to parse the query values, remove escape sequences and + characters from text entered in forms, and respond as needed by outputting static or dynamic text.  Be careful: the handler is called from the Ethernet task, and any writes by an HTTP handler to a shared buffer such as ETHER_OUTBUF could conflict with simultaneous writes that are being performed by the application task.  It is highly recommended that each service (HTTP, SMTP, serial tunneling) use its own buffers; use of HTTP_Outbuf is recommended for HTTP handler functions. When the HTTP handler returns, the Ether_Connection_Manager called by Ether_Service_Loop running in the Ethernet task closes the connection.

C:   void HTTP_Set_Inbuf ( xaddr xbufbase, int maxnumbytes, int modulenum )

4th: HTTP_Set_Inbuf     ( xbufbase \maxnumbytes\modulenum -- )

      Sets the 32-bit extended base address xbufbase and the size maxnumbytes of the HTTP_Inbuf default web service input buffer for the specified EtherSmart module. Note that the allocated buffer size must be 2 bytes bigger than the maxnumbytes parameter; these 2 bytes provide room to store the 16- bit count at the start of the lbuffer. The Ether_Setup function initializes HTTP_Inbufsize to HTTP_INBUFSIZE_DEFAULT = 254, with an allocated buffer size of 256 bytes. See HTTP_Inbuf.

C:   void HTTP_Set_Outbuf ( xaddr xbufbase, int maxnumbytes, int modulenum )

4th: HTTP_Set_Outbuf ( xbufbase \maxnumbytes\modulenum -- )

      Sets the 32-bit extended base address xbufbase and the size maxnumbytes of the HTTP_Outbuf default web service output buffer for the specified EtherSmart module. Note that the allocated buffer size must be 2 bytes bigger than the maxnumbytes parameter; these 2 bytes provide room to store the 16- bit count at the start of the lbuffer. The Ether_Setup function initializes HTTP_Outbufsize to HTTP_OUTBUFSIZE_DEFAULT = 1022, with an allocated buffer size of 1024 bytes (1 Kbyte). See HTTP_Outbuf.

C:   xaddr HTTP_Status_Ptr ( int modulenum )

4th: HTTP_Status_Ptr    ( modulenum -- xaddr )

      Returns the xaddress within the ether_info struct for the specified EtherSmart module that holds a 32-bit quantity that is reserved for the user.  The programmer can craft HTTP handler functions that write information into this location so that the foreground application program can monitor web server; recall that non-GUI web service responses are dispatched from the Ethernet task. The contents at HTTP_Status_Ptr are erased by Ether_Info_Init and its callers (Ether_Init, Ether_Setup, etc.)

C:   HTTP_TEXT_HTML_CONTENT

4th: HTTP_TEXT_HTML_CONTENT

      A 16-bit constant that returns the value -1.  This constant is passed as a content_identifier to HTTP_Put_Content_Type to indicate that the HTTP header should declare the content type as “text/html”. This is the default content type for web pages.

C:   HTTP_TEXT_PLAIN_CONTENT

4th: HTTP_TEXT_PLAIN_CONTENT

      A 16-bit constant that returns the value 0.  This constant is passed as a content_identifier to HTTP_Put_Content_Type to indicate that the HTTP header should declare the content type as “text/plain”. Note that this content type does not support HTML format tags; typically, the HTTP_TEXT_HTML_CONTENT type is preferred for web pages.

C:   xaddr HTTP_Timeout_Msec_Ptr ( int modulenum )

C:   int HTTP_To_Next_Field ( int modulenum )

4th: HTTP_To_Next_Field     ( modulenum -- numchars_advanced )

      This routine advances the URL (Universal Resource Locator) field pointers to point to the next query field and returns the number of chars advanced. If 0 is returned, there are no more query fields in the URL. This function assumes that HTTP_Parse_URL has been automatically called by the webserver in the Ethernet task running Ether_Service_Loop. This routine is used during the handling of webservice requests to parse the query field of the URL.  Each field is of the form:

                    fieldname=value

      Within the current query field, use the functions HTTP_Fieldname_Ptr, HTTP_Fieldname_Count, HTTP_Value_Ptr, and HTTP_Value_Count to identify the fieldname and value parameters passed by the browser’s GET command string. Let’s assume that the handler for the URL string /form_entry.html is the one described in the demo code that accompanies this driver.  Then when the “submit” button is pressed after the user fills in the form, the browser opens a connection and sends a request of the form:

                    GET /form_response.cgi?classification=man&name_id=tommy&color=blue

      In this case the URL is defined as

                    /form_response.cgi

      This is the string that is passed to HTTP_Add_Handler to associate the handler function with the URL.  The text after the URL starting with the ? character is the query portion of the URL.  Each “field” in the query comprises a fieldname followed by an = character followed by a field value.  Fields are separated by the & character.  When the handler function is first called, executing Http_Fieldname_Ptr returns the xaddress of the ‘c’ in ‘classification’ and the HTTP_Fieldname_Count returns 14, the count of ‘classification’.  HTTP_Value_Ptr returns the xaddress of the ‘m’ in ‘man’, and HTTP_Value_Count returns 3, the count of ‘man’.  A call to HTTP_To_Next_Field advances the current field to after the next & character.  Then Http_Fieldname_Ptr returns the xaddress of the ‘n’ in ‘name_id’ and the HTTP_Fieldname_Count returns 7, the count of ‘name_id’.  HTTP_Value_Ptr then returns the xaddress of the ‘t’ in ‘tommy’, and HTTP_Value_Count returns 5, the count of ‘tommy’. An additional call to HTTP_To_Next_Field advances the current field to after the next & character.  Then Http_Fieldname_Ptr returns the xaddress of the ‘c’ in ‘color’ and the HTTP_Fieldname_Count returns 5, the count of ‘color’.  HTTP_Value_Ptr then returns the xaddress of the ‘b’ in ‘blue’, and HTTP_Value_Count returns 4, the count of ‘blue’.  Because the URL is now exhausted, an additional call to HTTP_To_Next_Field would result in HTTP_Fieldname_Count and HTTP_Value_Count returning 0, signalling that there are no additional query fields to be examined. See the glossary entry of HTTP_Imagemap function for information on how to handle an HTTP GUI “remote front panel” web request.

C:   int HTTP_Unescape ( xaddr xstring, int count )

4th: HTTP_Unescape            ( xaddr\count -- revised_cnt )

      The input parameters specify the starting 32-bit xaddress and count of a substring in a URL (Universal Resource Locator string from a web browser). The unescape process replaces each HTTP 3-character escape sequence %hexhex (where hex is a hexadecimal digit) in the specified substring with its equivalent single ascii character corresponding to the 2-digit hexadecimal value, and shortens the URL field and its count by two chars for each escape sequence encountered. This routine is available for use by the programmer in parsing query subfields; it is automatically applied by HTTP_Parse_URL to the base portion of the URL. After performing the unescape and string compression, this routine writes blanks over any “orphaned” characters remaining after the URL (or after the query field, if present).

      CAUTION: If you are unescaping a query field substring, and the result of the un-escape could introduce a reserved & or = character (the field and value delimiters), the URL parsing routines could get confused by the unescaped characters masquerading as valid delimiters.  To solve this problem, make sure that you save the current HTTP_Fieldname_Ptr, HTTP_ Fieldname_Count, HTTP_Value_Ptr, and HTTP_Value_Count, and execute HTTP_To_Next_Field, before calling HTTP_Unescape for the saved query substring. This ensures that the parsing operations occur before the un-escape operation introduces any confusing delimiters that could corrupt the result. Note that the following characters are “reserved” in URLs and must be escaped (encoded as %hexhex):

                    ; / ? : @ = &

      The following characters are “unsafe” in URLs and should be escaped:

                    < > “ # % { } | \ ^ ~ [ ] ‘

C:   int HTTP_URL_Base_Count ( int modulenum )

4th: HTTP_URL_Base_Count  ( modulenum -- count )

      Returns the count of the URL from the first non-blank character after GET (pointed to by HTTP_URL_Ptr) until either the ? character that marks the start of the query field (if present), or the terminating blank (if no query field is present). The returned count includes the starting / character of the URL, and does not include the terminating ? or blank character. The base portion of the URL is the string that is matched to handlers posted by HTTP_Add_Handler and HTTP_Add_GUI_Handler.  See the glossary entries for HTTP_Parse_URL and HTTP_Add_Handler for further information about URLs.

C:   int HTTP_URL_Full_Count ( int modulenum )

4th: HTTP_URL_Full_Count ( modulenum -- count )

      Returns the count of the full URL including query fields (if any), starting at the first non-space char (typically a / character) after the GET<space> keyword of the web request, and ending with the last non-blank character.  The terminating blank of the URL is not included in the count. See the glossary entries for HTTP_Parse_URL and HTTP_Add_Handler for further information about URLs.

C:   xaddr HTTP_URL_Ptr ( int modulenum )

4th: HTTP_URL_Ptr       ( modulenum -- xaddr )

      Returns the uncounted string xaddress of the first non-space char after the GET<space> keyword in the HTTP_Inbuf for the most recently received web connection.  The character pointed to by xaddr is typically / (forward slash); hence, all URL’s posted should start with the / character. See the glossary entries for HTTP_Parse_URL and HTTP_Add_Handler for further information about URLs.

C:   int HTTP_Value_Count ( int modulenum )

4th: HTTP_Value_Count        ( modulenum -- count )

      Returns the count of the current query field after the = sign of the URL (Universal Resource Locator string) for the specified EtherSmart module. The count does not include the leading = character, nor the following & or blank terminating delimiter.  Returns 0 if the query field is not present or the URL is exhausted. This routine is used during the handling of webservice requests to parse the query field of the URL.  When the handler associated with the incoming URL is first called, this function returns the fieldname count of the first query field after the ? (if present).  To advance to the next field, call HTTP_To_Next_Field. Each field is of the form:

                    fieldname=value

      Within the current query field, use the functions HTTP_Fieldname_Ptr, HTTP_Fieldname_Count, HTTP_Value_Ptr, and HTTP_Value_Count to identify the fieldname and value parameters passed by the browser’s GET command string. Let’s assume that the handler for the URL string /form_entry.html is the one described in the demo code that accompanies this driver.  Then when the “submit” button is pressed after the user fills in the form, the browser opens a connection and sends a request of the form:

                    GET /form_response.cgi?classification=man&name_id=tommy&color=blue

      In this case the URL is defined as

                    /form_response.cgi

      This is the string that is passed to HTTP_Add_Handler to associate the handler function with the URL.  The text after the URL starting with the ? character is the query portion of the URL.  Each “field” in the query comprises a fieldname followed by an = character followed by a field value.  Fields are separated by the & character.  When the handler function is first called, executing Http_Fieldname_Ptr returns the xaddress of the ‘c’ in ‘classification’ and the HTTP_Fieldname_Count returns 14, the count of ‘classification’.  HTTP_Value_Ptr returns the xaddress of the ‘m’ in ‘man’, and HTTP_Value_Count returns 3, the count of ‘man’.  A call to HTTP_To_Next_Field advances the current field to after the next & character.  Then Http_Fieldname_Ptr returns the xaddress of the ‘n’ in ‘name_id’ and the HTTP_Fieldname_Count returns 7, the count of ‘name_id’.  HTTP_Value_Ptr then returns the xaddress of the ‘t’ in ‘tommy’, and HTTP_Value_Count returns 5, the count of ‘tommy’. An additional call to HTTP_To_Next_Field advances the current field to after the next & character.  Then Http_Fieldname_Ptr returns the xaddress of the ‘c’ in ‘color’ and the HTTP_Fieldname_Count returns 5, the count of ‘color’.  HTTP_Value_Ptr then returns the xaddress of the ‘b’ in ‘blue’, and HTTP_Value_Count returns 4, the count of ‘blue’.  Because the URL is now exhausted, an additional call to HTTP_To_Next_Field would result in HTTP_Fieldname_Count and HTTP_Value_Count returning 0, signalling that there are no additional query fields to be examined. See the glossary entry of HTTP_Imagemap function for information on how to handle an HTTP GUI “remote front panel” web request.

C:   xaddr HTTP_Value_Ptr ( int modulenum )

4th: HTTP_Value_Ptr    ( modulenum -- xaddr )

      Returns the 32-bit extended address of the first character after the = in the current query field of the URL (Universal Resource Locator string) for the specified EtherSmart module This routine is used during the handling of webservice requests to parse the query field of the URL.  The returned xaddress points to the character after the ? (first field only) or & (all subsequent fields). When the handler associated with the incoming URL is first called, this function points to the first query field after the ? (if present).  To advance to the next field, call HTTP_To_Next_Field. Each field is of the form:

                    fieldname=value

      Within the current query field, use the functions HTTP_Fieldname_Ptr, HTTP_Fieldname_Count, HTTP_Value_Ptr, and HTTP_Value_Count to identify the fieldname and value parameters passed by the browser’s GET command string. Let’s assume that the handler for the URL string /form_entry.html is the one described in the demo code that accompanies this driver.  Then when the “submit” button is pressed after the user fills in the form, the browser opens a connection and sends a request of the form:

                    GET /form_response.cgi?classification=man&name_id=tommy&color=blue

      In this case the URL is defined as

                    /form_response.cgi

      This is the string that is passed to HTTP_Add_Handler to associate the handler function with the URL.  The text after the URL starting with the ? character is the query portion of the URL.  Each “field” in the query comprises a fieldname followed by an = character followed by a field value.  Fields are separated by the & character.  When the handler function is first called, executing Http_Fieldname_Ptr returns the xaddress of the ‘c’ in ‘classification’ and the HTTP_Fieldname_Count returns 14, the count of ‘classification’.  HTTP_Value_Ptr returns the xaddress of the ‘m’ in ‘man’, and HTTP_Value_Count returns 3, the count of ‘man’.  A call to HTTP_To_Next_Field advances the current field to after the next & character.  Then Http_Fieldname_Ptr returns the xaddress of the ‘n’ in ‘name_id’ and the HTTP_Fieldname_Count returns 7, the count of ‘name_id’.  HTTP_Value_Ptr then returns the xaddress of the ‘t’ in ‘tommy’, and HTTP_Value_Count returns 5, the count of ‘tommy’. An additional call to HTTP_To_Next_Field advances the current field to after the next & character.  Then Http_Fieldname_Ptr returns the xaddress of the ‘c’ in ‘color’ and the HTTP_Fieldname_Count returns 5, the count of ‘color’.  HTTP_Value_Ptr then returns the xaddress of the ‘b’ in ‘blue’, and HTTP_Value_Count returns 4, the count of ‘blue’.  Because the URL is now exhausted, an additional call to HTTP_To_Next_Field would result in HTTP_Fieldname_Count and HTTP_Value_Count returning 0, signalling that there are no additional query fields to be examined. See the glossary entry of HTTP_Imagemap function for information on how to handle an HTTP GUI “remote front panel” web request.

4th:LCOUNT ( xLongstring_addr -- xaddr_of_first_char\ucount )

      This function is only available in Forth, as C functions are limited to one return parameter.  This function “unpacks” a counted longstring into its starting xaddress and count.  The input parameter is a 32-bit extended address that points to a longstring comprising a 2-byte count followed by the string contents.  The output xaddress points to the first character in the string, and the output ucount is the 16-bit count of the string.

      Implementation details: ucount is simply fetched from xLongstring_addr.  xaddr_of_first_char is simply the xaddress that is 2 bytes greater than xLongstring_addr.

      Kernel notes: This function is built into the V6.xx kernels, and is defined in this driver code for V4.xx kernels. 

4th: LPARSE ( xpointer_to_result_area\maxchars\eol\delimiter -- xLstring_addr )

      This function is only available in Forth; C uses other methods to define strings. LPARSE moves lines of text from the input stream’s terminal input buffer (TIB) to the memory area pointed to by the xpointer_to_result_area (typically DP or NP or VP).  After the specified delimiter is found or after maxchars have been parsed (whichever comes first), a terminating null character is added and the xpointer_to_result_area is updated to point to the byte after the terminating null. As each line ending in the input stream is encountered, the specified eol (end of line) sequence is inserted into the result string. The eol parameter can contain 1 or 2 bytes; typical values are 0x0D (carriage return), 0x0A (linefeed), 0x0D0A (carriage return/linefeed), or 0x00 (null byte).  If the eol parameter = -1, no eol bytes are stored in the string by this function. If the most significant (ms) byte of the eol parameter is non-zero, two bytes are stored in the buffer after the appended string: first the msbyte of eol, then the lsbyte of eol.  LPARSE returns xLstring_addr, an 32-bit extended address that points to a 2-byte longstring count followed by the parsed text.  The terminating null is not included in the stored count.

      Kernel version notes: LPARSE is built into the V6.xx kernel, and is defined in this driver code for V4.xx kernels.  There are two key differences between the versions.  The V4.xx LPARSE starts parsing on the line following following the LPARSE keyword, ignoring the remainder of the line containing LPARSE. The V6.xx version of LPARSE, on the other hand, starts parsing immediately after the LPARSE keyword.  In addition, the V6.xx version supports 1- or 2-byte delimiters, while the V4.xx version is limited to 1-byte delimiters.

      Cautions: The xpointer_to_result_area parameter is typically DP or NP or VP; do not use HERE or NHERE or VHERE. The available memory for storing the result string should be at least 3 bytes larger than the specified maxchars to allow for the 2-byte count and the terminating null byte. The maximum value of maxchars = 65,532. The stored output string can cross page boundaries. If the specified delimiter character is a blank, then an end of line in the input stream is interpreted as a valid ending delimiter that will terminate the string. If this routine is terminated by maxchars being reached, the remainder of the input line on which the termination occurred will not be interpreted by the compiler; these orphaned characters are removed from the input stream. A maximum of 94 characters per line can be parsed by the V4.xx version of this routine.

      Terminal note: To speed downloads, the QEDTerm program strips empty lines and lines starting with the \ comment character out of the download file by default. This can alter the content of strings appearing between LPARSE and the delimiter in your download file.  To solve this problem, use the #nostripcomments directive alone on a line in your download file to turn off comment stripping, then define the string(s) using one or more LPARSE directives, and restore the comment stripping using the #stripcomments directive alone on a line.  If your version of QEDTerm does not support these directives, download the latest version of QEDTerm from www.mosaic-industries.com.

      Example of use: Let’s say you want to create a multi-line string located in the dictionary area (which will be in non-volatile memory), with a carriage return and linefeed after every line in the stored string.  There are no empty lines in the string, so we don’t need to use the QEDTerm directives.  We’ll choose the } character as our ending delimiter, and we’ll specify 0x400 (1 Kbyte) characters as the maximum string size.  The longstring would be created as follows:

                    HEX

                    DP 400 0D0A ASCII } LPARSE

                    This is a test string

                    compiled by LPARSE!}

      The result left on the stack is the xaddress of the longstring buffer containing a 2-byte count followed by the string contents.

4th:XTERM/38400SSP ( -- )

      A do-nothing word used only when performing an interactive login using the “Putty” network terminal.  The name of this function corresponds to the default printable characters sent by the Putty network terminal when the “Rlogin” mode is selected for communications with the EtherSmart Wildcard.  The presence of this name in the QED-Forth names list prevents an error message from being displayed when the Putty Rlogin connection is established.  The Rlogin mode has the correct combination of lack of echo and treatment of end-of-line characters for clean operation with the QED-Forth monitor. To obtain the free Putty Ethernet terminal program, type

                    putty

      into your search engine (such as Google) and download the free telnet program from one of the listed sites.  It is a small and simple yet generally useful program.

<< Previous | Next>>