The EtherSmart Wildcard Glossary

4th: Ether_ Netmask_Ptr ( modulenum -- xaddr )

Returns the xaddress within the ether_info struct for the specified EtherSmart module that holds the packed 32bit netmask of the LAN (Local Area Network). The 4 bytes of the netmask are stored in order at the returned xaddress. Assuming that you have initialized the Ethernet task using Ether_Task_Setup, you can view the netmask that is currently in use by the XPort hardware on the EtherSmart Wildcard by executing Ether_IP_Info_Request followed by Ether_Await_Response, and then fetching the 4 bytes from the xaddress returned by this routine. For example, if the netmask is 255.255.255.0, the first 255 will be stored at the returned xaddress, followed by 255, 255, and the 0 in sequential memory bytes (this example corresponds to 8 “subnet bits”; see Ether_Gateway). To use a netmask that is automatically assigned by the LAN’s gateway host, specify an IP address and gateway IP and netmask of 0.0.0.0 (the factory defaults); then the XPort hardware relies on DHCP (Dynamic Host Configuration Protocol) running on the local area network’s gateway. To revert to the factory defaults which rely on a DHCP-assigned IP, gateway IP and netmask, execute Ether_XPort_Defaults. For a printed report of the local IP, gateway IP, and netmask, see Ether_IP_Info_Report. See Ether_Local_IP and Ether_Gateway for more information about how to set the XPort’s IP address, gateway IP, and netmask.

C: xaddr Ether_Outbuf ( int modulenum )

4th: Ether_Outbuf ( modulenum -- xaddr )

Returns the 32-bit extended base address of the default buffer for outgoing bytes to the Ethernet for the given module. This buffer is available for use by the programmer, and is typically (but not necessarily) passed as the target output buffer to functions such as Ether_Send_Buffer, Ether_Send_LBuffer, Ether_Send_2Buffers, and Ether_Send_Email. Note that Ether_Send_LBuffer expects to find the 16-bit count stored in the first 2 bytes of the buffer, with the data following. Ether_Outbuf is modified by functions that use the XPort’s monitor mode: Ether_XPort_Defaults, Ether_XPort_Update, Ether_Ping_Request, Ether_Ping_Report, Ether_IP_Info_Request, Ether_IP_Info_Response, and Ether_Encryption. See also Ether_Outbufsize and Ether_Set_Outbuf. The convenient Ether_Outbuf_Cat function adds a specified string to Ether_Outbuf. Ether_Outbuf should not be used for HTTP (web) service handlers which are dispatched from the Ethernet task; see HTTP_Outbuf.

C: void Ether_Outbuf_Cat ( xaddr xstring, uint count, int modulenum )

4th: Ether_Outbuf_Cat ( xstring\count\modulenum -- )

Concatenates the specified string plus a terminating carriage return and linefeed to the specified module’s Ether_Outbuf buffer, and increments the buffer count that is stored in the first two bytes of Ether_Outbuf to reflect the updated buffer contents. The string is specified by the extended 32-bit address xstring of its first character, and has count bytes to be added to the Ether_Outbuf buffer. An end-of-line sequence equal to 0x0D0A (carriage return and linefeed) is post-pended to the Ether_Outbuf after the string is added. This routine clamps the maximum number of bytes in the destination buffer to the value returned by Ether_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 TCP/IP Ethernet connections.

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

C: uint Ether_Outbufsize ( int modulenum )

4th: Ether_Outbufsize ( modulenum -- u )

Returns the size of the Ether_Outbuf default output buffer for the specified EtherSmart module which is set by Ether_Info_Init and its callers, and/or by the Ether_Set_Outbuf function. Note that the allocated buffer size must be 2 bytes bigger than the maxnumbytes parameter passed to Ether_Init or Ether_Set_Outbuf; these 2 bytes provide room to store the 16-bit count at the start of the lbuffer. To guarantee that Ether_Outbuf will be able to hold s-records as required for the monitor mode commands such as Ether_XPort_Defaults and Ether_XPort_Update, Ether_Outbufsize should be initialized to a value greater than or equal to ETHER_MIN_BUFFER_SIZE = 320. The Ether_Setup function initializes Ether_Outbufsize to ETHER_BUFSIZE_DEFAULT = 510, with an allocated buffer size of 512 bytes.

C: int Ether_Passive_Non_Web_Connection ( int modulenum )

4th: Ether_Passive_Non_Web_Connection ( modulenum -- flag )

Returns a true flag if a passive connection has been accepted that did not identify as HTTP (that is, there was no leading GET keyword detected). The main application task loop can repeatedly call this routine to see if an incoming “serial tunneling” connection needs to be serviced.

Implementation detail: Returns a true (nonzero) flag if Ether_Connect_Status returns the value 6; otherwise returns false. See the glossary entry for Ether_Connect_Status for a detailed description.

C: void Ether_Ping_Report ( char ip1, char ip2, char ip3, char ip4, int modulenum )

4th: Ether_Ping_Report ( ip1\ip2\ip3\ip4\modulenum -- )

This is an interactive version of ping, typically typed at a terminal, with the response printed to the terminal. This function retains control for up to approximately 13 seconds (that is, it’s a blocking function). For a non-blocking version, use Ether_Ping_Request. A “ping” is a way of finding out whether a remote host is available on the network; if so, the remote responds to the ping. This routine invokes Ether_Ping_Request which writes the specified input parameters into the ether_info struct, and SENDs to the task running the Ether_Service_Loop which dispatches the action function to send an outgoing ping from the XPort to a device with IP address ip1.ip2.ip3.ip4. (If the mailbox is full, the SEND routine will PAUSE; see Ether_Ready_For_Command). This routine then RECEIVEs the results from the mailbox and prints the ping result (along with any appropriate error message) to the terminal. An error code is returned via the ether_response mailbox; a nonzero return value results in a “ Couldn’t enter monitor mode!” or “ No response from remote” printout. This routine awaits the response for you, so you do not need to clear the ether_response mailbox. The counted ping response string is at Ether_Outbuf, with the count in the first 2 bytes and the ascii response string (not including error messages) following. If the remote responded to the ping, the ping report is of the form:

Seq 001 time 10ms

Seq 002 time 10ms

Seq 003 time 10ms

Seq 004 time 10ms

Seq 005 time 10ms

Seq 006 time 10ms

Of course, the reported time will vary depending on how long it took the remote to respond to each ping.

C: void Ether_Ping_Request ( char ip1, char ip2, char ip3, char ip4, int modulenum )

4th: Ether_Ping_Request ( ip1\ip2\ip3\ip4\modulenum -- )

Stores the specified input parameters into the ether_info struct and SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function, with an error flag placed in Ether_Error and in the ether_response mailbox to indicate whether the remote responded as described below. (If the command mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). A “ping” is a way of finding out whether a remote host is available on the network; if so, the remote responds to the ping. This function enters monitor mode and sends an outgoing ping from the XPort to an Ethernet device with IP address ip1.ip2.ip3.ip4, waits for return string, and verifies that it has enough bytes to indicate that the remote responded to the ping. The captured ping results are placed as a packed lstring at Ether_Outbuf with the count in first 2 bytes and the ascii ping response following (see the glossary entry of Ether_Ping_Report for the format of the response). The remote ping response comprises 6 lines (1 per second), or nothing if the remote did not respond. The entire operation takes approximately 13 seconds. When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and error flag in the remaining 2 bytes is placed in the ether_response mailbox; the error flag is also available using Ether_Error. The error flag is zero if the operation was successful, or 0x08 (ERROR_INVALID_RESPONSE; see Ether_Error) if we couldn’t enter monitor mode, or 0x10 (ERROR_NO_RESPONSE; see Ether_Error) if the ping was sent but the remote did not respond. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response, but note that the result will not be present until over 13 seconds have elapsed, so please be patient. See also Ether_Ping_Report.

C: int Ether_Ready_For_Command ( int modulenum )

4th: Ether_Ready_For_Command ( modulenum -- ready? )

Checks the state of the ether_command mailbox for the specified module and returns a true flag if the mailbox is empty (i.e, if its contents equal 0\0). Returns a false flag if the contents of ether_command are non-zero, indicating that the mailbox is full and not ready to receive another command. The application program can use this function to avoid invoking an Ethernet command until the Ethernet task is done receiving the prior command; this can avoid potentially long pauses if several commands have been issued, as the SEND routine invoked by the Ethernet command functions will loop and call Pause if the mailbox is still full. See the glossary entry for Ether_Command_Manager for a summary of the relevant commands that write to the ether_command mailbox.

To use: call Ether_Ready_For_Command before invoking one of the commands that writes to the command mailbox, and execute the command only if Ether_Ready_For_Command returns true.

C: xaddr Ether_Remote_IP_Ptr ( int modulenum )

4th: Ether_Remote_IP_Ptr ( module -- xaddr )

Returns the xaddress within the ether_info struct for the specified EtherSmart module that holds the packed 32-bit IP (Internet Protocol) address of the remote computer that was the subject of the last outgoing connection or ping request. This pointer is typically used only for diagnostic purposes, as the remote IP is fully specified in the parameter list that is passed to the functions that initiate the outgoing connection requests.

C: xaddr Ether_Remote_Port_Ptr ( int modulenum )

4th: Ether_Remote_Port_Ptr ( module -- xaddr )

Returns the xaddress within the ether_info struct for the specified EtherSmart module that holds the 16-bit port of the remote computer that was the subject of the last outgoing connection or ping request. This pointer is typically used only for diagnostic purposes, as the remote port is specified in the parameter list that is passed to the functions that initiate the outgoing connection requests.

C: ulong ether_response

4th: ether_ response ( -- xaddr )

A mailbox in common RAM that conveys a 32-bit value from the Ethernet control task to the user’s application task. The programmer monitors the contents of this mailbox using either the non-blocking function Ether_Check_Response, or the blocking function Ether_Await_Response; see their glossary entries for details. When the Ether_Command_Manager running in the Ether_Service_Loop finishes executing a command that is dispatched from the user’s application task, it writes into this mailbox a command_id byte and modulenum in the msword, and an optional 16-bit return parameter in the lsword. The return parameter may be an error flag, the number of bytes transmitted by a send command, etc.

Note: This mailbox is typically not accessed directly. In C, this mailbox can be used as an lvalue or an rvalue, just like any C variable. In Forth, this variable has the standard behavior or returning the xaddress of its contents.

C: int ether_revector_module

4th: ether_revector_module ( -- xaddr )

A 16-bit variable in common RAM containing a modulenum. This variable must be initialized before calling Ether_Serial_Revector or Ether_Monitor to revector serial I/O via the Ethernet Wildcard network port. This variable is not initialized by default. The contents of this variable are used by E_Key, E_ASCII_Key, E_Ask_Key, and E_Emit to implement revectored serial. The specified value must match the hardware jumper setting on the Wildcard that is to be used for revectored I/O. For example, if both of the module ID jumpers are installed and the Wildcard is mounted on Wildcard Module Header 0, then the value 3 should be stored into the variable to access the Wildcard if you want to download code through this Wildcard to the controller. See the User Guide for details about setting the module number. See the glossary entries for Ether_Serial_Revector and Ether_Monitor. The Ethernet Demo code provided in source form presents an example of how to revector downloads and interactive program development through the EtherSmart Wildcard.

Note: In C, this variable can be used as an lvalue or an rvalue, just like any C variable. In Forth, this variable has the standard behavior or returning the xaddress of its contents.

C: void Ether_Send_2Buffers ( xaddr xbuffer1, uint count1, xaddr xbuffer2, uint count2,

uint timeout_msec, int modulenum )

4th: Ether_Send_2Buffers ( xbuffer1\count1\xbuffer2\count2\timeout_msec\modulenum--)

Stores the specified input parameters into the ether_info struct and SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). 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. 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 the specified timeout_msec whether or not the maximum number of bytes have been sent. When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and the total numbytes_sent in the remaining 2 bytes is placed in the ether_response mailbox. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response. The total number of bytes actually sent is also available via Ether_Numbytes_Sent. See also HTTP_Send_2Buffers, HTTP_GUI_Send_2Buffers, Ether_Send_Buffer and Ether_Send_Buffer.

C: void Ether_Send_Buffer ( xaddr xbuffer, uint count, uint timeout_msec, int modulenum )

4th: Ether_Send_Buffer ( xbuffer\count\timeout_msec\modulenum -- )

Stores the specified input parameters into the ether_info struct and SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). Sends to the EtherSmart Wildcard up to count bytes of data starting at the 32-bit extended memory address xbuffer. 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 specified timeout_msec whether or not the maximum number of bytes have been sent. When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and numbytes_sent in the remaining 2 bytes is placed in the ether_response mailbox. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response. The number of bytes actually sent is also available via Ether_Numbytes_Sent. See also HTTP_Send_Buffer, HTTP_GUI_Send_Buffer, Ether_Send_LBuffer and Ether_Send_2Buffers.

C: void Ether_Send_Email ( xaddr xemail_body, uint body_cnt, xaddr xhostname, int host_cnt,

xaddr xsender, int sender_cnt, xaddr xreceiver, int receiver_cnt, xaddr xscratchbuf,

char dest_ip1, char dest_ip2, char dest_ip3, char dest_ip4, int dest_port,

uint timeout_msec, int modulenum )

4th: Ether_Send_Email ( xemail_body \body_cnt\xhostname \host_cnt

\xsender \sender_cnt\ xreceiver\receiver_cnt\xscratch_buf

\dest_ip1\dest_ip2\dest_ip3\dest_ip4\dest_port\timeout_msec\modulenum -- )

Stores the specified input parameters into the ether_info struct of the specified EtherSmart modulenum and SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). This function sends an email to the remote host at IP (Internet Protocol) address dest_ip1.dest_ip2.dest_ip3.dest_ip4 and port dest_port. The highly recommended dest_port is port 25, which is the SMTP (Simple Mail Transfer Protocol) email well-known port. This function allows the XPort to be an SMTP client that initiates an outgoing email, sending it to a remote host that is running an SMTP daemon (mail server). This implementation of SMTP opens a connection to the server, sends a single email, quits and closes the connection. While the specified IP and port must be on the Local Area Network, sending an email to a non-local recipient can be accomplished by configuring the gateway router on your LAN to relay email messages to the non-local recipient (contact your LAN system administrator for assistance if this is required). The specified scratchpad RAM buffer xscratch_buf holds temporary data going to and from the XPort; it must be at least 16 bytes longer than each specified string input buffer (except for the body string, which is never placed into the scratch buffer). Ether_Inbuf provides a convenient scratchpad buffer of adequate size; feel free to pass Ether_Inbuf as the xscratch_buf if this is compatible with your application. The timeout_msec function sets the maximum time for each phase of the email data exchange process to complete; make sure that it is long enough to deal with any delays in your LAN; setting the delay to 10000 (10 seconds) is a reasonable default. The remaining input parameters specify the starting xaddresses and counts of the component strings in the email header and body; these buffers can be in RAM, or in flash memory if their contents are static and pre-initialized. Each xaddress (32-bit extended address) points to the first character in the string, and each corresponding count specifies the number of characters in the string. The xemail_body and body_cnt parameters specify the body of the email. The email body is sent without transferring it to a temporary buffer to improve efficiency and to allow static email bodies to be sent directly from flash memory to the remote. (The transfer is a bit tricky, however, as this routine implements the “transparency” requirement specified by the email protocol; experts can consult RFC821, section 4.5.2 available on the web to find out how it’s done). To build up a dynamic email body “on the fly”, consider using the convenient function Ether_Outbuf_Cat to construct the dynamic email text. Just make sure that the result fits in the specified Ether_Outbuf_Size, and remember to pass Ether_Outbuf+2 as the address of the first character, and the 16-bit contents of Ether_Outbuf as the body_cnt (because Ether_Outbuf contains a 2-byte count followed by the buffer contents). The hostname xaddress and count specify a string that identifies the computer that originates the email; for example:

" XPort.mosaic-industries.com"

The sender xaddress and count specify a string that identifies the sender of the email; for example:

" niceguy@gateway.mosaic-industries.com"

The receiver xaddress and count specify a string that identifies the recepient of the email; for example:

" notso_niceguy@gateway.mosaic-industries.com"

This Ether_Send_Email function automatically emplaces a To: header line in the email referencing the recipient; this field is sent separately via the scratchpad buffer and does not consume any room in the xemail_body buffer. Other optional fields can be explicitly placed by your application program inside the body text. One that is very useful is the subject line, which is emplaced in the body as a line of the form:

" Subject: XPort Email Test-Drive "

The word Subject: should be the first word on the line, and put a space after the colon, with a carriage return/linefeed (0x0D0A) terminating the line (this is the standard line termination for email messages). Other optional fields of similar form include

Date:

Cc:

From:

When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and error code (also available in Ether_Error) in the remaining 2 bytes is placed in the ether_response mailbox.

The numeric (unnamed) error codes are as follows:

Value Meaning

0x00 no error; operation was successful

0x10 ERROR_NO_RESPONSE // no response from remote

0x20 ERROR_ALREADY_CONNECTED // only 1 connection is allowed at a time

0x100 ERROR_TIMEOUT // timed out before operation could complete

Other SMTP-related error codes:

251 User not local; will forward to <forward-path>

551 User not local; please try <forward-path>

500 Line too long.

501 Path too long

552 Too many recipients.

552 Too much mail data.

After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response.

Note: The demo code presented in source form presents an example of how to use this function.

C: void Ether_Send_LBuffer ( xaddr xlbuffer, uint timeout_msec, int modulenum )

4th: Ether_Send_LBuffer ( xlbuffer\timeout_msec\modulenum -- )

Stores the specified input parameters into the ether_info struct and SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). 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 at xlbuffer+2. 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 specified timeout_msec whether or not the maximum number of bytes have been sent. When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and numbytes_sent in the remaining 2 bytes is placed in the ether_response mailbox. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response. The number of bytes actually sent is also available via Ether_Numbytes_Sent. See also HTTP_Send_LBuffer, HTTP_GUI_Send_LBuffer, Ether_Send_Buffer and Ether_Send_2Buffers.

C: void Ether_Serial_Revector ( void )

4th: Ether_Serial_Revector ( -- )

For the current task (that is, the task that invokes this routine), revectors the serial primitives to use the EtherSmart Wildcard that is specified by the contents of the ether_revector_module variable. Make sure to explicitly store a value to the ether_revector_module variable before invoking this routine, as the variable is not initialized by default. See Ether_Monitor.

Implementation detail: Stores the xcfa (execution address) of E_Emit into the user variable UEMIT, stores the xcfa of E_Ask_Key into UASK_KEY (U?KEY in Forth), and stores the xcfa of E_ASCII_Key into UKEY. To restore the standard RS232 serial ports, execute COLD. (If there was the standard SAVE at the end of your program, executing RESTORE after the COLD will restore access to the defined functions in your application).

C: void Ether_Service_Loop ( void )

4th: Ether_Service_Loop ( -- )

An infinite loop task activation routine that repeatedly calls Ether_Connection_Manager and Ether_Command_Manager, passing as the specified modulenum the contents of the ether_service_module variable. See Ether_Task_Setup.

C: int ether_service_module

4th: ether_service_module ( -- xaddr )

A 16-bit variable in common RAM containing a modulenum. This variable is initialized by Ether_Init and its calling functions (Ether_Setup, Ether_Setup_Default, and Ether_Task_Setup) to specify which Wildcard module is accessed by the Ether_Service_Loop routine running in the Ethernet control task. The specified value must match the hardware jumper setting on the Wildcard. For example, if neither of the module ID jumpers are installed and the Wildcard is mounted on Wildcard Module Header 0, then the value 0 should be stored into the variable to access the Wildcard. See the User Guide for details about setting the module number. See the Ethernet Demo code provided in source form for an example of how to setup the Ethernet control task.

Note: In C, this variable can be used as an lvalue or an rvalue, just like any C variable. In Forth, this variable has the standard behavior or returning the xaddress of its contents.

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

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

Sets the 32-bit extended base address xbufbase and the size maxnumbytes of the Ether_Inbuf default input buffer. 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 Ether_Inbufsize to ETHER_BUFSIZE_DEFAULT = 510, with an allocated buffer size of 512 bytes.

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

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

Sets the 32-bit extended base address xbufbase and the size maxnumbytes of the Ether_Outbuf default output buffer. 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. To guarantee that Ether_Outbuf will be able to hold s-records as required for the monitor mode cmds Ether_XPort_Defaults and Ether_XPort_Update, Ether_Outbufsize should be initialized to a value greater than or equal to ETHER_MIN_BUFFER_SIZE = 320. The Ether_Setup function initializes Ether_Outbufsize to ETHER_BUFSIZE_DEFAULT = 510, with an allocated buffer size of 512 bytes.

C: uint Ether_Setup ( xaddr xbuffer_area_base, addr mailbox_base_addr, int modulenum )

4th: Ether_Setup ( xbuffer_area_base\ mailbox_base_addr \module -- numbytes )

High level initialization routine that calls Ether_Init with default buffer locations and sizes starting at the specified xbuffer_area_base, and returns the number of bytes allocated there. Also passes to Ether_Init the addresses of three mailboxes in common RAM starting at mailbox_base (a 16-bit address). The mailboxes are ether_command at mailbox_base_addr, ether_response at mailbox_base_addr+4, and ether_gui_message at mailbox_base_addr+8. These mailboxes must be declared (allocated) before calling this function. Locates all required buffers, the ether_info struct, and the HTTP autoserve array in RAM starting at the specified xbuffer_area_base, and returns the number of bytes allocated. Note that xbuffer_area_base can be in paged RAM to conserve common RAM for other uses. Zeros the three required mailboxes ether_command, ether_response, and ether_gui_message in common RAM. Starting at the specified 32-bit xbuffer_area_base, allocates the ether_info struct, followed in order by the autoserve array, Ether_Inbuf (512 bytes including 2-byte count), Ether_Outbuf (512 bytes including 2-byte count), HTTP_Inbuf (256 bytes including 2-byte count), and HTTP_Outbuf (1024 bytes including 2-byte count). Initializes the UART chip, powers up the XPort chip, starts the timeslicer and globally enables interrupts. This routine initializes the ether_service_module variable which specifies which module is controlled by the Ether_Service_Loop webserver & command processor running in the Ethernet task. (This routine does not initialize the ether_revector_module variable). This routine flushes the UART input buffers for 0.25 second if no connection is open. If there is an open Ethernet connection, this routine disconnects it, which takes 2.5 seconds. Ether_Setup is typically called by Ether_Setup_Default; see its glossary entry.

C: uint Ether_Setup_Default ( int modulenum )

4th: Ether_Setup_Default ( module -- numbytes )

High level initialization routine that calls Ether_Setup with a default xbuffer_area_base. For controllers running V6.xx kernels, passes 0x178000 (address 0x8000 on page 0x17) as the xbuffer_area_base to Ether_Setup. For controllers running V4.xx kernels, passes 0x034000 (address 0x4000 on page 3) as the xbuffer_area_base to Ether_Setup. Returns the number of bytes allocated at xbuffer_area_base; it is less than 3 Kbytes. See Ether_Setup for a detailed description of operation. Ether_Setup_Default is typically called by Ether_Task_Setup; see its glossary entry.

C: void Ether_Shutdown ( int modulenum )

4th: Ether_Shutdown ( modulenum -- )

Shuts down the linear 3.3 volt regulator on the EtherSmart Wildcard, thus saving over 1.25W = 0.25A at 5V. The Ethernet interface on the specified wildcard is not useable while in the shutdown state. To revert to the default powered-up state, power cycle the hardware, or execute Ether_Init or one of its calling functions (Ether_Setup, Ether_Setup_Default, or Ether_Task_Setup).

C: void Ether_Task_Setup ( TASK* task_base_addr, int modulenum )

4th: Ether_Task_Setup ( task_base_addr\modulenum -- )

This is a high level routine that performs a full initialization of the ether_info struct and mailboxes, and builds and activates an Ethernet control task to service the XPort for the specified modulenum. Calls Ether_Setup_Default which in turn calls Ether_Setup with a default xbuffer_area_base. For controllers running V6.xx kernels, passes 0x178000 (address 0x8000 on page 0x17) as the xbuffer_area_base to Ether_Setup. For controllers running V4.xx kernels, passes 0x034000 (address 0x4000 on page 3) as the xbuffer_area_base to Ether_Setup. Less than 3 Kbytes is allocated in this buffer area. See Ether_Setup for a detailed description of operation. Ether_Task_Setup then builds a standard 1 Kbyte task running the Ether_Service_Loop activation routine at the specified 16-bit task_base address in common RAM (task areas must be in common RAM). To use this routine, allocate a 1 Kbyte (1024 byte) task area in common RAM (see the demo program described in the User Guide for an example). Pass its 16-bit base address along with the EtherSmart Wildcard modulenum (that corresponds to the hardware jumper settings) to this routine to perform a complete initialization and start the Ethernet task to service the connections. See the demo code for a convenient Ether_Task_Setup_Default routine that uses a pre-defined 1 Kbyte task area to call this function. Also see the demo code for a Web_Demo function that hosts a demonstration website from the EtherSmart Wildcard.

C: void Ether_TCP_Control ( char keepalive_sec, char discon_minutes,

int send_imm_chars, char flushmode, char packing, int module )

4th: Ether_TCP_Control (keepalive_sec\discon_min\send_imm_chars\flush\packing\module--)

This function is for experts only. Maintaining the default values as set by Ether_XPort_Defaults is highly recommended. This function writes the specified parameters into the ether_info struct for the specified module. Keepalive_sec specifies the number of seconds between “keepalive” signals sent on the network; the default 45, and the valid range is 1 to 65, with a value of 255 disabling the keepalive feature. The discon_minutes parameter forces a disconnect after the specified number of minutes of inactivity; 0-99 is the valid range, with 0 (the default) meaning that the inactivity timeout feature is disabled. The send_imm_chars parameter specifies a 1- or 2-character sequence that, when encountered, triggers an immediate send to the network. if the most significant (ms) byte of this parameter is 0, the feature is disabled. If the most significant (ms) byte is nonzero and the least significant (ls) byte is zero, the single ms byte specifies the send character. If both bytes are nonzero and the packing parameter specifies a 2-byte send sequence, then the 2-byte sequence must be encountered to trigger the immediate send. The flushmode specifies when the XPort’s input and output buffer contents are flushed (discarded); the default value of 0x80 (no flushing, pack control enabled) is highly recommended to avoid loss of data while ensuring fast network response over a wide range of conditions. Other flushmode values are bitmapped as follows (bitmaps can be OR’d to achieve flushing combinations):

0x01 = network->serial clear with active connect

0x02 = network -> serial clear with passive connect through network

0x04 = network -> serial clear at time of disconnect

0x10 = serial -> network clear with active connect (initiated by us)

0x20 = serial -> network clear with passive connect (connect request from network)

0x40 = serial -> network clear at time of disconnect

0x80 = alternate packing algorithm

The packing parameter has a recommended default value of zero; the meaning of this byte is as follows:

0x00 = Idle time to force transmit: 12 ms ( default )

0x01 = Idle time to force transmit: 52 ms

0x02 = Idle time to force transmit: 250 ms

0x03 = Idle time to force transmit: 5 s

0x00 = No trailing chars after sendchar(s)

0x04 = One trailing char after sendchar(s)

0x08 = Two trailing chars after sendchar(s)

0x10 = Sendchar define 2-byte sequence

0x20 = Send immediate after sendchar

After executing this function, assuming that you have initialized the Ethernet task (see Ether_Task_Setup), you can instantiate the values into XPort flash by executing Ether_Update followed by Ether_Await_Response.

C: void Ether_Telnet_Password ( xaddr xpassword_string, int password_cnt, int modulenum )

4th: Ether_Telnet_Password ( xpassword_string\count\modulenum -- )

Writes the specified string specifier parameters into the ether_info struct for the specified module as the password used by the telnet configuration modes. The xaddr xpassword_string is the 32-bit base address of the first character of the string, and count is the number of bytes in the string (clamped to a maximum of 4 bytes). Assuming that you have initialized the Ethernet task (see Ether_Task_Setup), you can instantiate the string into XPort flash after invoking this function by executing Ether_Update followed by Ether_Await_Response. Use of this string is optional; it prohibits access to the setup mode via telnet to port 9999 unless the proper password is entered. To revert to the default (no password), use Ether_XPort_Defaults.

NOTE: If you set a telnet password, the web interface tool may not allow a login if you have specified non-zero parameters for the ETHER_GATEWAY function. This seems to be a bug in the Lantronix XPort web configuration tool. The telnet configuration tools work under these conditions.

C: xaddr Ether_Tunnel_Enable_Ptr ( int modulenum )

4th: Ether_Tunnel_Enable_Ptr ( modulenum -- xaddr )

Returns the xaddress of a a 16-bit flag within the ether_info struct for the specified EtherSmart module. If the flag is false (zero), the Ether_Command_Manager will close any incoming connection that it identifies as non-http (because a leading GET substring is not found). The default value of this flag is true: passive serial tunnelling connections are enabled by default. If no incoming serial tunneling is supported by the application program, setting this flag false may improve the robustness of web service by automatically closing a non-web connection so that the application program does not have to.

C: void Ether_XPort_Defaults ( int modulenum )

4th: Ether_XPort_Defaults ( modulenum -- )

SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). This function enters monitor mode, and sends the default versions of XPort flash block0 (serial and network settings), block3 (additional network settings), and block7 (hardware handshaking configuration) s-records. This routine then executes the monitor mode RS reset command to instantiate the new values in XPort flash memory. The entire operation takes approximately 13 seconds. When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and error flag in the remaining 2 bytes is placed in the ether_response mailbox; the error flag is also available using Ether_Error. The error flag is zero if the operation was successful, or nonzero if there was a problem that prevented the operation from completing. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response, but note that the result will not be present until over 13 seconds have elapsed, so please be patient.

Implementation detail: The Lantronix XPort documentation manual is available at www. lantronix.com. Many of the Lantronix default values are retained this function, but a significant number are changed to reflect the Mosaic default values. The Mosaic custom values are as follows: The baud rate is set to 115 Kbaud, hardware handshaking is enabled, the local TCP port is set to 80, the connect configuration is set to “accept all incoming connections, and use XPort modem mode without echo”. The flush mode is set such that flushing is disabled, and pack control is enabled. The internal “configuration” HTTP port is set to 8000, and the “+++ passthrough suppression” feature is enabled. The local IP, gateway IP, and netmask are kept at the Lantronix default values of 0.0.0.0 (unassigned), so that the device expect to have these parameters assigned via DHCP (Dynamic Host Configuration Protocol) on the LAN. The hardware handshaking pins are enabled in flash block 7.See also Ether_XPort_Update.

C: void Ether_XPort_Update ( int modulenum )

4th: Ether_XPort_Update ( modulenum -- )

For the specified module, SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). This function enters monitor mode, and sends the versions of XPort flash block0 (serial and network settings), block3 (additional network settings), and block7 (hardware handshaking configuration) s-records. The s-records include the default values as optionally modified by the following user-called configuration functions (see their glossary entries for details):

Ether_DHCP_Name

Ether_Gateway

Ether_Internal_Webserver_Port

Ether_Local_IP

Ether_Local_Port

Ether_Telnet_Password (see glossary entry for cautions about use)

Ether_TCP_Control

This routine then executes the monitor mode RS reset command to instantiate the new values in the XPort flash memory. The entire operation takes approximately 13 seconds. When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and error flag in the remaining 2 bytes is placed in the ether_response mailbox; the error flag is also available using Ether_Error. The error flag is zero if the operation was successful, or nonzero if there was a problem that prevented the operation from completing. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response, but note that the result will not be present until over 13 seconds have elapsed, so please be patient. To revert to the default configuration, see Ether_XPort_Defaults.

Note: DHCP (Dynamic Host Configuration Protocol) is enabled by default and after Ether_XPort_Defaults is executed; in this condition, the XPort obtains its IP address, gateway IP and netmask via DHCP on the LAN. To disable DHCP, assign a non-zero value to the local IP address, gateway IP, or netmask using the relevant functions listed in this glossary entry followed by Ether_XPort_Update. The presence of the non-zero IP address will override any DHCP value and disable DHCP. Likewise, specifying a non-zero gateway IP address or netmask will override any gateway IP and netmask values and disable DHCP.

C: int HTTP_Add_GUI_Handler ( xaddr url_xstring, int url_count,

xaddr (*handler_ptr)(void), int modulenum )

4th: HTTP_Add_GUI_Handler ( url_xaddr\url_count\handler_xcfa \modulenum -- error )

Adds a GUI (Graphical User Interface) handler function with the specified execution address to be called each time the webserver receives a GET statement that references the specified URL (Universal Resource Locator, as described below in this glossary entry). A GUI handler is used to implement a web-based “remote front panel” for an instrument that contains a touchscreen and graphics display. When a user clicks on a screen image (typically the same image that is present on the graphics display) presented in a browser window, the GUI toolkit processes the input as if a touch on the touchscreen had occurred, calling the associated GUI action function, and updating the screen image both on the instrument an on the remote browser screen. A GUI handler is different than a standard webservice handler. A standard non-GUI webservice handler executes automatically without any intervention from the user’s application task, and is dispatched by the Ethernet task running the Ether_Service_Loop routine. A GUI handler, on the other hand, requires an interaction with the GUI Toolkit, and, for task synchronization reasons, must be dispatched from the user’s application task. This HTTP_Add_GUI_Handler function posts the handler function and the associated URL to the autoserve array, and marks the function as a GUI Handler so that it will be dispatched via the application task. This function initializes the row specified by the contents of HTTP_Index_Ptr in the autoserve array. This autoserve array is initialized by Ether_Info_Init and its callers Ether_Init and Ether_Setup, and can be declared using HTTP_Is_Autoserve_Array. Each row associates a URL with the corresponding user-specified HTTP handler function that serves out HTML or image data in response to the specified URL request. Each 8-byte row of the autoserve array contains: a 1byte URL count, a 1-byte URL string page, a 2-byte URL string start addr, and a 4-byte handler xcfa (extended code field address, a function pointer). This routine sets the most significant byte of the handler execution address to mark the handler as a GUI handler that is passed to the application task. This routine writes to the row index specified by the contents of HTTP_Index_Ptr, and then increments the contents of HTTP_Index_Ptr. This function returns zero if there was no error, or a nonzero value if the next available index pointed to by HTTP_Index_Ptr is greater than or equal to the maximum number of rows set by the HTTP_Is_Autoserve_Array function.

Notes about the handler function: Each web handler function posted by this routine 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 (see their glossary entries) before sending the referenced buffer. GUI handler functions that implement a web “remote front panel” must perform only one send operation to serve the webpage, using one of the functions HTTP_GUI_Send_Buffer, HTTP_GUI_Send_LBuffer, or HTTP_GUI_Send_2Buffers. The most common function used to serve out the GUI webpage is HTTP_GUI_Send_2Buffers, with the first buffer containing the HTTP header and imagemap HTML text, and the second buffer containing the bitmap screen image.

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 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 the character before either a terminating space (ascii 0x20) or 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. See the glossary entry for HTTP_Add_Handler for a standard form example. Here we present an “imagemap” example that is used to implement a typical GUI handler web page. See the demo code associated with this driver for a coded example. When an image object is declared as an HTML imagemap, then any click on the image causes the browser to issue a GET command to a specified response URL, passing the X and Y coordinates of the mouse click as a comma delimited query field. The X and Y coordinates are in units of pixels relative to the upper left corner of the image.

Imagemap example: Here is an example of a browser GET request when a mouse click occurs 73 pixels to the right and 103 pixels down from the upper left corner of a map image:

GET /gui_response.html?73,103

The GET is always capitalized and followed by a space, after which the URL appears in 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. To properly manage HTTP GUI handlers, the main user application task (the same task that invokes the GUI functions) must call Ether_Check_GUI periodically to accept any incoming GUI web requests and dispatch the associated handler that was posted by this HTTP_Add_GUI_Handler function. In the HTTP GUI handler function associated with the URL string

/gui_response.html

the HTTP_Imagemap function (see its glossary entry) should be called to extract and return the X and Y coordinates from the query field. Then the Simulated_Touch_To_Image function (defined in the special GUI Toolkit section of this glossary document) can be invoked to simulate the touch at the specified screen coordinates, draw the press and release graphics, activate the screen button’s press handler, and, if the screen image changed, reload the screen image buffer with the updated screen bitmap image. Then HTTP_GUI_Send_2Buffers can be used to send the HTTP header and HTML text (in the first buffer) and graphics image (in the second buffer) to the browser to complete the operation. Careful examination of the demo code should clarify this technique.

C: int HTTP_Add_Handler ( xaddr url_xstring, int url_count, xaddr (*handler_ptr)(void),

int modulenum )

4th: HTTP_Add_Handler ( url_xaddr\url_count\handler_xcfa\modulenum -- error )

Adds a handler function with the specified execution address to be called each time the webserver receives a GET statement that references the specified URL (Universal Resource Locator, as described below in this glossary entry). Initializes the row specified by the contents of HTTP_Index_Ptr in the autoserve array. This autoserve array is initialized by Ether_Info_Init and its callers Ether_Init and Ether_Setup, and can be declared using HTTP_Is_Autoserve_Array. Each row associates a URL with the corresponding user-specified HTTP handler function that serves out HTML or image data in response to the specified URL request. Each 8-byte row of the autoserve array contains: a 1byte URL count, a 1-byte URL string page, a 2-byte URL string start addr, and a 4-byte handler xcfa (extended code field address, a function pointer). This routine clears the most significant byte of the handler execution address to mark the handler as a standard handler that is executed by the ethertask (as opposed to a GUI handler; see HTTP_Add_GUI_Handler). This function writes to the row specified by the contents of HTTP_Index_Ptr, and then increments the contents of HTTP_Index_Ptr. This function returns zero if there was no error, or a nonzero value if the next available index pointed to by HTTP_Index_Ptr is greater than or equal to the maximum number of rows set by HTTP_Is_Autoserve_Array, or by Ether_Info_Init or its caller functions such as Ether_Init and Ether_Setup.

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

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

C: HTTP_AUTOSERVE_DEFAULT_ROWS

4th: HTTP_AUTOSERVE_DEFAULT_ROWS

A 16-bit constant that returns the value 32. This constant is used by Ether_Setup to specify the number of rows in the autoserve array. This constant sets the maximum number of web URLs (Universal Resource Locator strings) that can be responded to by the dynamic webserver. To change the size and/or base xaddress of the autoserve array, use HTTP_Is_Autoserve_Array. See also HTTP_Autoserve_Ptr.

C: xaddr HTTP_Autoserve_Ptr ( int modulenum )

4th: HTTP_ Autoserve_Ptr ( modulenum -- xaddr )

Returns the 32-bit extended base address of the autoserve array that is used by the webserver. The base xaddress is set by Is_Autoserve_Array which in turn is called by Ether_Init and Ether_Setup. Each row in the array associates a URL (Universal Resource Locator, a web address string) with the corresponding user-specified HTTP handler function that serves out HTML or image data in response to the specified URL request. Each 8-byte row of the autoserve array contains: a 1byte URL count, a 1-byte URL string page, a 2-byte URL string start addr, and a 4-byte handler xcfa (extended code field address, a function pointer). HTTP_Is_Autoserve_Array does not erase the declared array; this is done by Ether_Init or Ether_Setup. If you want to use a pre-initialized flash-based autoserve array, first call Ether_Init or Ether_Setup to create a RAM-based instance of the autoserve array, and then invoke this function to change to a pre-initialized flash version of the array. To add a handler to the autoserve array, see 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: HTTP_BINARY_DATA_CONTENT

4th: HTTP_BINARY_DATA_CONTENT

A 16-bit constant that returns the value 5. 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 “application/octet-stream" (raw binary data bytes).

C: void HTTP_Default_Handler ( int modulenum )

4th: HTTP_Default_Handler ( modulenum -- )

Directly sends a response to the current open Ethernet connection a “404: Not Found” HTTP error response page. The response goes directly from string text stored in flash to the XPort; no RAM buffer is used to send the data. This function is automatically called by HTTP_Server when a URL (Universal Resource Locator, or web address string) is received that does not match a string posted by HTTP_Add_Handler or HTTP_Add_GUI_Handler. You can customize this default handler by defining a function that serves out the appropriate HTTP header followed by a single blank line followed by the desired custom HTML text, and then storing the 32-bit execution address (function pointer) in the HTTP_Default_Handler_Ptr (see its glossary entry). The page served out reminds the user that each URL should start with a / (forward slash) character, and that URLs are case sensitive. This routine serves out the following HTTP header and HTML content, and the webserver then closes the connection:

HTTP/1.1 404 Not Found

Server: Mosaic Industries Embedded Webserver

Connection: close

Content-Type: text/html

<html><head><title>404 Not Found</title></head>

<body><H3>Requested URL was not found:</H3>

{the requested URL is printed here}

<p>Note: All URLs should start with the / character and are case sensitive.

</body></html>

C: xaddr HTTP_Default_Handler_Ptr ( int modulenum )

4th: HTTP_Default_Handler_Ptr ( modulenum -- xaddr )

Returns the 32-bit xaddress in the ether_info struct whose contents are the 32-bit xcfa (extended code field address, or execution address) of the default web handler routine that serves out the "Error 404: Page not found" response. This handler is called by the HTTP_Server when an incoming GET request from the browser specifies a URL (web address string) that has not been posted using HTTP_Add_Handler or HTTP_Add_GUI_Handler. The default contents of this pointer are set by Ether_Info_Init and its callers Ether_Init and Ether_Setup to point to HTTP_Default_Handler. To change the default handler, create a handler function and store its execution address (32-bit function pointer) in the 32-bit xaddress returned by HTTP_Default_Handler_Ptr. See the glossary entry of HTTP_Default_Handler for more details.

C: xaddr HTTP_Enable_Ptr ( int modulenum )

4th: HTTP_Enable_Ptr ( modulenum -- xaddr )

Returns the xaddress of a a 16-bit flag within the ether_info struct for the specified EtherSmart module. If the flag is true, the Ether_Command_Manager will input the first carriage-return/linefeed-delimited line from the remote into the HTTP_Inbuf and, if a leading GET substring is detected, will service the incoming web connection. If the contents of HTTP_Enable_Ptr equal zero, no characters will be automatically inputted from passive incoming connections and consequently, no attempt will be made to "identify" the connection as http or non-http. If the application does not support web connections, setting this flag false can simplify the handling of incoming "serial tunneling" connections, as the application program is solely in charge of accepting incoming chars, instead of having to look for the first incoming line placed in the HTTP_Inbuf. The default flag state set by Ether_Setup is true (web service is enabled).

C: int HTTP_Fieldname_Count ( int modulenum )

4th: HTTP_Fieldname_Count ( modulenum -- count )

Returns the count of the current query field between the ? (first field only) or & (all other fields) delimiter and the = sign of the URL (Universal Resource Locator string) for the specified EtherSmart module. The count does not include the ? or & leading delimitor, nor the = character or blank trailing 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_Fieldname_Ptr ( int modulenum )

4th: HTTP_Fieldname_Ptr ( modulenum -- xaddr )

Returns the 32-bit extended address of the first character 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

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

In this case the URL is defined as

/form_response.cgi

C: xaddr HTTP_Get_Timeout_Msec_Ptr ( int modulenum )

4th: HTTP_Get_Timeout_Msec_Ptr ( modulenum -- xaddr )

Returns the xaddress within the ether_info struct for the specified EtherSmart module that holds a 16-bit timeout used by the Ether_Connection_Manager during the attempt to identify an incoming web connection. If a carriage-return/linefeed-delimited line is not available from the remote within the specified timeout, and if the contents of HTTP_Enable_Ptr are nonzero, the input operation will cease when the timeout is reached, and the HTTP identification will then proceed. Increasing the value of this timeout beyond its default value of 5000 (5 seconds) may improve the robustness of web service on some networks. Note, however, that an incoming serial tunneling connection that does not promptly send a carriage-return/linefeed-delimited line effectively delays the recognition of an incoming serial tunneling (as monitored by Ether_Connect_Status) by the value of this delay parameter. See also HTTP_Timeout_Msec_Ptr.

C: void HTTP_GUI_Send_2Buffers ( xaddr xbuffer1, uint count1, xaddr xbuffer2, uint count2,

int modulenum )

4th: HTTP_GUI_Send_2Buffers ( xbuffer1\count1\xbuffer2\count2\module-- )

This function serves out web content to implement a web-based “remote front panel” for GUI (Graphical User Interface) touchscreen instruments. This function is coded into the user-specified handler function that is posted by HTTP_Add_GUI_Handler; the handler is invoked at runtime by Ether_Check_GUI running in the main application task when the webserver detects a URL that was declared as corresponding to a GUI handler. HTTP_GUI_Send_2Buffers is typically called in the user-specified handler after HTTP_Imagemap extracts the X,Y coordinates of the mouse click on the web-based screen image, and after Simulated_Touch_To_Image (defined in the GUI Toolkit driver) invokes the GUI routines and refreshes the screen image in the image buffer. HTTP_GUI_Send_2Buffers is used to send the HTTP header and HTML text in one buffer (see HTTP_Put_Header and HTTP_Put_Content_Type), followed immediately by sending the image data in another buffer, all combined as a single command. Http_GUI_Send_2Buffers stores the specified input parameters into the ether_info struct and SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). 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 sent. The total number of bytes actually sent is available via Ether_Numbytes_Sent. 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. After the transmission of the two buffers has completed, the web connection will be automatically closed by the Ethernet task. 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. Each of the two send operations exits within the time specified by the contents of HTTP_Timeout_Msec_Ptr whether or not the maximum number of bytes have been sent.

NOTE: Unlike Send_Buffer, this routine does not SEND the numbytes_sent return result via the ether_response mailbox back to the application program.

NOTE: A special rule applies to GUI-based web service routines because of task synchrony considerations: Each web response must be completed using a single send command. If an image is to be served out, then use this HTTP_GUI_Send_2Buffers function to send the HTTP header and required HTML tag text in xbuffer1, plus the separate image in xbuffer2.

Usage Notes: Note that a standard non-GUI webservice handler executes automatically without any intervention from the user’s application task, and is dispatched by the Ethernet task running the Ether_Service_Loop routine. On the other hand, a GUI handler is different than a standard webservice handler in that it requires an interaction with the GUI Toolkit, and, for task synchronization reasons, must be dispatched from the user’s application task. A GUI handler is used to implement a web-based “remote front panel” for an instrument that contains a touchscreen and graphics display. HTTP_Add_GUI_Handler posts the handler (the function containing the call to HTTP_GUI_Send_2Buffers) along with the associated URL to the autoserve array, and marks the function as a GUI Handler so that it will be dispatched via the application task from Ether_Check_GUI. When a user clicks on a screen image (typically the same image that is present on the graphics display) presented in a browser window and declared using the “imagemap” HTML attribute, the browser returns the X,Y coordinates in a query field. These coordinates are extracted by the HTTP_Imagemap function; see its glossary entry. By invoking the GUI toolkit function named Simulated_Touch_To_Image (see the GUI toolkit documentation), the GUI toolkit processes the input as if a touch on the touchscreen had occurred, calling the associated GUI action function, and updating the screen image both on the instrument and in a specified image buffer. Then this HTTP_GUI_Send_2Buffers function is used to serve the HTTP header and HTML text in xbuffer1, and the bitmap screen image data in xbuffer2 to the remote browser screen. The text xbuffer must include exactly 1 blank line between the HTTP header and and the HTML text; see HTTP_Put_Header and HTTP_Put_Content_Type.

C: void HTTP_GUI_Send_Buffer ( xaddr xbuffer, uint count, int modulenum )

4th: HTTP_GUI_Send_Buffer ( xbuffer\count\modulenum -- )

NOTE: Unlike Send_Buffer, this routine does not SEND the numbytes_sent return result via the ether_response mailbox back to the application program.

NOTE: A special rule applies to GUI-based web service routines because of task synchrony considerations: Each web response must be completed using a single send command. If an image is to be served out, then use the HTTP_GUI_Send_2Buffers function to send the HTTP header and required HTML tag text in one buffer, followed by the separate image buffer in a single send command.

Usage Notes: A GUI handler is used to implement a web-based “remote front panel” for an instrument that contains a touchscreen and graphics display. When a user clicks on a screen image (typically the same image that is present on the graphics display) presented in a browser window, the GUI toolkit processes the input as if a touch on the touchscreen had occurred, calling the associated GUI action function, and updating the screen image both on the instrument an on the remote browser screen. A standard non-GUI webservice handler executes automatically without any intervention from the user’s application task, and is dispatched by the Ethernet task running the Ether_Service_Loop routine. A GUI handler is different than a standard webservice handler in that it requires an interaction with the GUI Toolkit, and, for task synchronization reasons, must be dispatched from the user’s application task. The HTTP_Add_GUI_Handler function posts the handler function and the associated URL to the autoserve array, and marks the function as a GUI Handler so that it will be dispatched via the application task from Ether_Check_GUI. See also HTTP_Send_2Buffers, HTTP_Put_Header, and HTTP_Put_Content_Type.

C: void HTTP_GUI_Send_LBuffer ( xaddr xlbuffer, int modulenum )

4th: HTTP_GUI_Send_LBuffer ( xlbuffer\modulenum -- )

Sends the data contents of a “long buffer” which contains a 16-bit data byte count followed by the data bytes. This function “unpacks” the specified long buffer by fetching the 16-bit count from xlbuffer, and passing xlbuffer+2 and the extracted count to HTTP_GUI_Send_Buffer. See the glossary entry for HTTP_GUI_Send_Buffer.

C: HTTP_IMAGE_BITMAP_CONTENT

4th: HTTP_IMAGE_BITMAP_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 “image/bmp” (a bitmap image). It can also be passed as a format_id to the GUI functions Screen_To_Image and Graphic_To_Image (see the special GUI Toolkit section of this glossary document).

C: HTTP_IMAGE_GIF_CONTENT

4th: HTTP_IMAGE_GIF_CONTENT

A 16-bit constant that returns the value 3. 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 “image/gif” (an image compressed using the GIF format).

C: HTTP_IMAGE_JPEG_CONTENT

4th: HTTP_IMAGE_JPEG_CONTENT

A 16-bit constant that returns the value 4. 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 “image/jpeg” (an image compressed using the JPEG format).

C: HTTP_IMAGE_PNG_CONTENT

4th: HTTP_IMAGE_PNG_CONTENT

A 16-bit constant that returns the value 2. 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 “image/png” (an image compressed using the PNG format).

C: TWO_INTS HTTP_Imagemap ( int modulenum )

4th: HTTP_Imagemap ( modulenum -- y\x )

Extracts and returns the X and Y coordinates (relative to the upper left image corner) from the query field of an imagemap GET request from a web browser. Returns X = Y = -1 if the required comma is not found in the query field between X and Y. Returns garbage if the query field does not contain valid decimal integers before and after the required comma. Numeric conversion is performed in decimal base. The Forth version of the function returns Y under X. Because a C function can return only a single value, the X and Y values returned by the C function are considered to be a single 32-bit long that is typecast as a union equivalent to two 16-bit integers, with X in the most significant (ms) integer, and Y in the least significant (ls) integer. The types.h header file includes the following typedef that specifies the C return parameter:

typedef union

{ ulong int32;

struct

{ int msInt;

int lsInt;

} twoNums;

} TWO_INTS;

When an image object is declared as an HTML imagemap, then any click on the image causes the browser to issue a GET command to a specified response URL, passing the X and Y coordinates of the mouse click as a comma delimited query field. The X and Y coordinates are in units of pixels relative to the upper left corner of the image. An imagemap is declared as follows:

When a mouse click occurs, say, 73 pixels to the right and 103 pixels down from the upper left corner of a map image:

GET /gui_response.html?73,103

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. To properly manage HTTP GUI handlers, the main user application task (the same task that invokes the GUI functions) must call Ether_Check_GUI periodically to accept any incoming GUI web requests and dispatch the associated handler that was posted by this HTTP_Add_GUI_Handler function. In the HTTP GUI handler function associated with the URL string

/gui_response.html

this HTTP_Imagemap function is called to extract and return the X and Y coordinates from the query field. Then the Simulated_Touch_To_Image function can be invoked to simulate the touch at the specified screen coordinates, draw the press and release graphics, activate the screen button’s press handler, and, if the screen image changed, reload the screen image buffer with the updated screen bitmap image. Then HTTP_GUI_Send_2Buffers can be used to send the HTTP header and HTML text (in the first buffer) and graphics image (in the second buffer) to the browser to complete the operation. Careful examination of the demo code should clarify this technique.

C: xaddr HTTP_Inbuf ( int modulenum )

4th: HTTP_Inbuf ( modulenum -- xaddr )

Returns the 32-bit extended base address of the default HTTP web service buffer for incoming data from the Ethernet for the specified module. 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, waiting up to HTTP_Get_Timeout_Msec) and looks for a leading GET substring to decide whether the connection is HTTP or serial tunneling. If it is HTTP, the web server is called to parse the URL (web address) in place in the HTTP_Inbuf and the web service request is automatically fulfilled by dispatching the posted handler for the URL. See the glossary entries for HTTP_Parse_URL and HTTP_Add_Handler for further information about URLs. 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 and/or Ether_Passive_Non_Web_Connection on each pass through the program loop routine; see their glossary entries. See also the glossary entries for HTTP_Inbufsize and HTTP_Set_Inbuf.

<< Previous | Next>>

The EtherSmart Wildcard Glossary

Table of Contents