Home

Dynamic C TCP/IP Users Manual

1. and directory components These will be interpreted as same directory and one level up as is customary If components are included the resulting name cannot be above or out side the root directory specified in context gt rootdir 106 rabbit com Server Utility Library sspec open cont context Additional context information The ServerContext structure is set up by the caller It has the following fields typedef struct int userid User ID of the current user or 1if not applicable word server Server id e g SERVER_HTTP char rootdir Root directory Usually if the whole namespace is to be accessible Otherwise may bee g A to restrict access to just first DOS FAT partition First and last char must be 7 char cwd Current working directory Normally includes rootdir as aprefix First and last char must be 7 char dfltname A file name to be used as a resource name suffix in the case that the first parameter refers toadirectory name ServerContext mode Resource opening mode Bitwise OR of the following macros e O READ open for reading e O WRITE open for writing implies reading as well e O CREAT withO WRITE if file does not exist then create it with zero length and allocation e O TRUNC with O WRITE if file already exists truncate it to zero length e O APPEND with O WRITE if file
2. and the subtype column would directly follow Find the type subtype entry that matches your extension and add it to the http types table SSPEC MIMETABLE START SSPEC MIME html texel htm SSPEC_MIME pdf application pdt added this one SSPEC MIME gif image gif SSPEC MIMETABLE END 148 rabbit com HTTP Server 4 5 1 3 Handling of Files With No Extension The entry and files without an extension are dealt with by the handler specified in the first entry in the MIME table If you use the SSPEC_MIME macro the default handler is used It passes the information verbatim You can also use the macro SSPEC MIME FUNC to specify a non default text processor this is necessary for SSI and RabbitWeb scripts described later 4 5 2 Dynamic Web Pages Without HTML Forms Serving a dynamic web page without the use of HTML forms is done by sample program ssi c This program displays four lights and four buttons to toggle them Users can browse to the device and change the status of the lights The sample code follows but it has been edited for brevity Open ssi c in Dynamic C to see the fully commented source define TCPCONFIG 1 define HTTP MAXSERVERS 1 define MAX TCP SOCKET BUFFERS AL This is the address that the browser uses to access your server define REDIRECTHOST PRIMARY STATIC IP Used by the cgi of each ledxtoggle function to tell the browser which page to hit next define REDIR
3. in the guard is not enough Instead a different syntax is used where H is the th index being referenced If the user uses a simple for a wildcarded index it is implicitly replaced with 0 since in general is a shorthand notation for 0 If the error checking expression is not flexible enough a user defined function can be specified instead struct int a intb 00 web foo check foo Sfoo a foo b Remember that a variable must be a simple variable or a string char array It would be illegal to call the above function check foo with foo since foo is a structure 262 rabbit com RabbitWeb Consider the order of evaluation of each of the variable error checks to be undefined that is do not depend on the order Also only changed variables are checked for errors This must be taken into account when writing guards For example in the following code web low web high Shigh gt Slow let us say the value of high is 60 and the value of low is 40 If these variables are presented in an HTML form and a value of 65 for low is submitted while the value for high is kept the same it would be accepted because low has no guard Since the value of high did not change its guard was not activated Hence the guards for interdependent variables must be symmetric 5 2 2 1 Reporting Errors When a variable fails its error check the reason for the failure can be displayed in an
4. 11 2 5 A Simple but Realistic Application 13 2 6 Adding Access Controls mn 16 2 7 A Full Featured Application 22 2 8 Living Without RabbitWeb and FAT 26 Server Utility Library 31 3 1 Data Structures for Zserver lib 31 3 1 1 MIMETypeMap Structure 32 3 1 2 ServerSpec Structure 33 3 1 3 ServerAuth Structure 35 3 1 4 ServerPermissions Structure 35 3 1 5 RuleEntry Structure 36 3 1 6 ServerContext Structure 36 3 1 7 SSpecStat Structure 37 3 1 8 sspec_fatinfo Structure 37 3 1 9 Form Var Structure 38 3 1 10 SSpecFileHandle Structure 38 3 2 Constants Used in Zserver lib 38 3 2 1 ServerSpec Type Field 38 3 2 2 ServerSpec Vartype Field 39 3 2 3 ServerPermissions Servermask Field 39 3 2 4 Configuration Macros 39 3 2 5 Macros for Control Data Initialization 41 3 3 File Compression Support 43 3 4 HTML Forms eenennenenzzznnenannnnazi 44 3 5 API Functions sess ssseeenenzznnnnnnzznnnznzn 45 HTTP S rver eissii 137 4 1 HTTP Server Data Structures 138 4 1 1 HttpState 138 4 2 Configuration Macros 141 4 2 1 Sending Customized HTTP Headers to the Client 143 4 2 2 Saving Custom Headers from the Client 144 4 3 Authentication Methods eee 145 4 4 Setting the Time Zone 146 4 5 Sample Programs eeeceeseeeseeeeneees 146 4 5 1 Serving Static Web Pages 146 4 5 2 Dynamic Web Pages Without HTML Forms 149 4 5 3 Web Pages
5. PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE One of the following codes e HTTP METHOD GET GET i e normal retrieval without making any permanent state update e HTTP METHOD POST POST i e uploading some information to be stored or making some permanent state change This is the normal method for invoking CGIs e HTTP METHOD HEAD HEAD i e the client only wants the headers not the actual content e g it might be trying to determine the most recent modification date Other codes may be returned in the future LIBRARY HTTP LIB SEE ALSO http_getAction 208 rabbit com HTTP Server http getHTTPMethod str char http getHTTPMethod str HttpState state DESCRIPTION Return the HTTP request method of the current request protocol The CGI might need to look at this in order to generate the correct response headers PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE One of the following strings GET HTTP METHOD GET i e normal retrieval without making any permanent state up date POST HTTP_METHOD POST i e uploading some information to be stored or making some permanent state change This is the normal method for invoking CGIs HEAD HTTP_METHOD_ HEAD i e the client only wants the headers not the actual content e g it might be trying to determine the mo
6. and many other web sites and books In the Ssi shtml file the following line creates the clickable but ton viewable from the browser lt TD gt lt A HREF leditog cgi gt lt img SRC button gifi gt lt A gt lt TD gt When the user clicks on the button the browser will request the led1ltog cgi entity This causes the HTTP server to examine the contents of the http_flashspec structure looking for leditog cgi It finds it and notices that leditoggle needs to be called The leditoggle function changes the value of the 1ed1 variable then redirects the browser back to the original page When the original page is reloaded by the browser the LED image will have changed states to reflect the user s action This sample demonstrates the so called old style CGI New style CGIs are easier to write especially when they are doing something non trivial They are described in Section 4 6 HTTP File Upload Connection Abort Condition There are two fields in the HttpState structure that allow a CGI function to appropriately respond to a connection abort condition The user may set the field abort_notify to a non zero value in a CGI function to request that the CGI function be called one more time with the cancel field set to one if a connection abort occurs 4 5 3 Web Pages With HTML Forms With a web browser HTML forms enable users to input values With a CGI program those values can be sent back to the server and processe
7. 55 sauth setusermask int sauth setusermask int userid word userid void authdata DESCRIPTION Set the group access bit s and authorization data for a given user ID PARAMETERS userid User index userid Bitmask of group s of which this user is a member This should be non zero otherwise the user will not have access to any resources authdata Arbitrary data that can be used by specific servers RETURN VALUE 0 OK 1 Failed userid not valid 56 rabbit com Server Utility Library sauth setwriteaccess int sauth setwriteaccess int sauth int writeaccess DESCRIPTION Set whether or not a user has write access with the specified server s PARAMETERS sauth Index of the user in the user table writeaccess Server bitmask with bit set to 1 for write access 0 for no write access This is a bitwise OR of the server macros SERVER_ HTTP etc that you want the user to have write access to RETURN VALUE 0 Success 1 Failure SEE ALSO sauth getwriteaccess TCP IP Manual Vol 2 rabbit com 57 sspec access int sspec access char name ServerContext context DESCRIPTION Test access to a given resource by a specified user The userid is set in context gt userid or 1 for testing access by the server in general NOTE sspec checkpermissions performs a similar function except on a resource handle rather than a resource name PARAMETERS name Resource name as a null termi
8. DESCRIPTION Runs the telnet daemon must be called periodically RETURN VALUE 0 Success 1 Failure But call it periodically no matter the return value An error message can be seen when 1 is returned if you define VSERIAL DEBUG at the top of your program LIBRARY VSERIAL LIB 454 rabbit com Telnet 13 2 Telnet pre Dynamic C 7 05 The API available for telnet changed with Dynamic C version 7 05 This is the old API 13 2 1 Configuration Macros SERIAL PORT SPEED The baud rate of the serial port Defaults to 115 200 bps TELNET COOKED def ine this to have telnet control codes stripped out of the data stream This is useful if you are actually telneting to the device from another box It should not be defined if you are using two devices as a transparent bridge over the Ethernet 13 2 2 API Functions telnet init int telnet init int which longword addy int port DESCRIPTION Initializes the connection This function must not be called by an application program starting with Dynamic C 7 05 PARAMETERS which Is one of the following TELNET LISTEN Listens on a port for incoming connections TELNET _RECONNECT Connects to a remote host and reconnects if the connection dies TELNET _CONNECT Connects to a remote host and terminates if the connection dies addy IP address of the remote host or 0 if we are listening port Port to bind to if we are listening or the port of the remote host to connect to RE
9. On return pointers that were NULL on entry may be changed to point to val id default information In particular the ctrl and drive fields will point to defaults One and only one of the NULL part pointers may be set toa default partition structure if a default partition could be located on the drive If fat 1ib is not included the above structure is still defined but contains 6 void pointers This is just to avoid compilation problems since no infor mation will be used or returned fs2stuff This parameter is currently reserved for returning FS2 information For now pass as NULL reserved Reserved for other filesystems For now pass as NULL RETURN VALUE 0 OK Otherwise if a filesystem fails to mount the return code is the bitwise OR of the SSPEC_MOUNT _ constants of those filesystem s that failed to initialize SEE ALSO sspec fatregister sspec fatregistered TCP IP Manual Vol 2 rabbit com 73 sspec cd int sspec cd char path ServerContext context int check DESCRIPTION Change the current working directory in the ServerContext structure This function may be used by servers that support the concept of a current directory such as FTP but not HTTP Standard Unix like path names are used including support for and directory components The resulting directory name is not allowed to be closer to the root directory than context gt rootdir If there is any specification error then the
10. This library supports a single FTP session at any one time since the session state is maintained in a single global structure in root memory You can upload and download files to either a static buffer in root data memory for simple applications or starting with Dynamic C version 7 20 you can have the data passed to or generated by a data handler callback function that you specify The data handler function can implement large file transfers in extended memory buffers or it can be used to generate or process data on the fly with minimal buffering Starting with Dynamic C 7 20 you can specify passive mode transfers This is most important for clients which are inside a firewall Passive mode is specified by passing the FTP MODE PASSIVE option to ftp client setup When passive mode is specified the client will actively open the data transfer port to the server rather than the other way around This avoids the need for the server to penetrate the firewall with an active connection from the outside which is most often blocked by the firewall For this reason it is recommended that your FTP client application uses passive mode by default unless overrid den by an end user 7 1 Configuration Macros The following macros may be defined in a define statement before the inclusion of FTP CLIENT LIB in an application program Note that strings must contain the NULL byte so if a maximum string length is 16 the maximum number of characte
11. monitor that is not able to make an update then the Sorry mes sage will be printed Recall that the access to io state was set up when the variable was registered with web You may be asking how the application notices when the web variable is updated by the browser not just inthemv io polling function This is a good question since the HTTP server updates the variable just like a normal C variable The solution to this requires that you specify an update callback function in the web variable registration This is described in detail in Chapter 5 For the purposes of this section just remember that it is easy to do TCP IP Manual Vol 2 rabbit com 21 2 7 A Full Featured Application The previous examples have relied on ximport to store files in the program flash This is limiting in terms of storage capacity and does not allow for dynamic file updates Adding the ability to store files in a filesystem that is located somewhere besides the program flash is of high value because it adds storage capacity and allows for dynamic updates Figure 2 6 Components of a full featured web enabled application Application Compile Time Run Time Main Application CGI Initialization Initialization Loop Specifics 1 Q_ Functions web Variables Metadata l i Resources Requests MIMEJ Context Table Ni Zserver _ gt Rule EEV Resource Manager Table User 1 Table Static Dvnamic Res
12. world bits are set if any other server has access 1 is a constant for Unix compatibility user is the username who owns the file resource Since Zserver does not have the concept of resource ownership this is set to the user ID of the context gt userid field If context gt userid is l this is set to anon group is the resource group name Zserver does not support this Unix concept either so this field is set to the realm of the file resource if it has one otherwise it is set to anon length is set to the current length of the file resource or 0 if not known date is set to the modification date of the file resource in Mon dd yyyy format name is the name of the file resource in this directory Example dr r r 1 foo admin 0 Jan 1 1980 ftpfiles rw rw rw 1 foo admin 1250 Mar 6 2003 index htm RETURN VALUE EEOF there were no more entries in this directory Any other negative value parameter or I O error Otherwise non negative the return value should be passed back to this function as the item parameter value to retrieve the next entry SEE ALSO sspec cd TCP IP Manual Vol 2 rabbit com 81 sspec fatregister int sspec fatregister int partno fat part pt DESCRIPTION This function must be used to register all FAT partitions that will be accessible to Zserver 1ib Partitions are numbered consecutively from 0 and they correspond to mount points A B C
13. 1 switch http getAction s case CGI START if http _getField s 0 to upload n printf Found a file COND HANDLE http setCond s i sspec open http getField s http getContext s O WRITEJO CREATJO TRUNC 0 if http getCond s COND HANDLE lt http skipCGI 0 else http skipCGI s break case CGI DATA http _getCond s COND HANDLE http_getData s s handle sspec write handle http getDataLength break case CGI END http getCond s COND HANDLE handle sspec_close handle The following statement ensures that the handle is set back to 1 when we know it is closed http setCond s COND HANDLE 1 break case CGI EOF http switchCGI s index html break case CGI ABORT handle http getCond s COND HANDLE rabbit com 175 TCP IP Manual Vol 2 The following test is added so we don t try to close the handle if it is already closed if handle gt 0 sspec close handle break return 0 What Happens if the Write Fails There is still one point to cover That is the sspec write call is not guaranteed to swallow all of the data that it was told to write In fact sspec_write may completely fail for example if the file sys tem runs out of space First let s handle the case where sspec write returns an error that is its return code is negative In this case
14. 382 rabbit com SNMP 12 2 4 Creating the MIB The MIB is created by the following code define the root of this MIB tree b Sii append perse sSeemo S 1 1 z make the following managed objects both readable and writable p snmp set access p SNMP PUBLIC MASK SNMP PRIVATE MASK SNMP PRIVATE MASK Pp mmo acel ineto 1 10 sw imie p monindex snmp_last_index p Save index 4 later monitor call p snmp set callback p scale Setup for callback function p snmp_add_long p 1 2 0 amp rw_long Associate callback with var p snmp set callback p NULL Don t associate with other vars b sun ack cocci YL S 0 19w Fiqecl 20 5 sumo acl _siee gt 1 4 0 7 Be 0 5 sump ack oero 1 5 0 mw oct 22 7 p sumo _add_objectID p 1 6 0 amp rw_oid P smn aclkl_aoeckhke s YL 7 0 rapae tip b sumo ackl_cimecicks jo 1 8 0 ew EE 7 make the following managed objects read only p snmp_set_access p SNMP PUBLIC MASKISNMP PRIVATE MASK 0 sain ack almie o 72 1L 0W 630 dm trapindices 0 snmp last index p save index for trap message ji emmo ace long jo 2 A 0 wire lome D smn ack cocc s Y2 3 0 38 itisecl 20 i Sains ackl Bies jo 2 4 0 78 see 20 b sun acl oce is 2 5 0 6EE 22 trapindices 1 snmp last index p save index for trap message D gt smn ack _OojecerD js 2 6 0 ie_ icl 5 All of the API functions that were u
15. Dynamic C TCP IP User s Manual Volume 2 019 0144 090409 F The latest revision of this manual is available on the Rabbit Web site www rabbit com for free unregistered download Dynamic C TCP IP User s Manual Volume 2 Part Number 019 0144 e 090409 F 7 Printed in U S A Digi International Inc 2006 2008 All rights reserved No part of the contents of this manual may be reproduced or transmitted in any form or by any means without the express written permission of Digi International Inc Permission is granted to make one or more copies as long as the copyright page contained therein is included These copies of the manuals may not be let or sold for any reason without the express written permission of Digi International Inc Digi reserves the right to make changes and improvements to its products without providing notice Trademarks Rabbit and Dynamic C are registered trademarks of Digi International Inc Windows is a registered trademark of Microsoft Corporation Dynamic C TCP IP User s Manual RABE Tete Table of Contents 1 Imtroduction ss enenennnnnnnnnan 1 2 Web Enabling Your Application 3 2 1 Designing Your Application 3 2 2 The Smallest Web Server in the WWW 4 2 3 Web Server Architecture sse 6 2 3 1 Application Block 7 2 3 2 HTTP Block 8 2 3 3 HTTP Block Subcomponents 9 2 3 4 Zserver Block 9 2 4 Architecture of a Toy Application
16. Dynamic C 8 50 introduces file compression support The sample program samples tcpip http zimport c demonstrates how to use this functionality This sample is ori ented towards the HTTP server however under the covers HTTP is relying on Zserver to perform the compressed file handling In the sample program notice that the statement use zimport 1lib comes before the statement use http lib in the code This is required to have file compression support in Zserver and the web server The next thing to notice is the use of the compiler directive zimport instead of ximport zimport performs a standard ximport but compresses the file by invoking a com pression utility before emitting the file to the target When adding a compressed file to the static resource table use the macro SSPEC RESOURCE ZMEMFILE instead of SSPEC RESOURCE XMEMFILE When you add a com pressed file to the dynamic resource table using the sspec addxmemfile function it will be recog nized as a compressed file automatically sspec addxmemfile is thus used for both compressed and uncompressed imported files Each instance of a server will use a buffer for decompression this is necessary since multiple server instances can be decompressing files at the same time Make sure that the buffer macro INPUT COMPRESSION BUFFERS is at least as large as the number of servers which may need concur rently to decompress a compressed resource The buffer macro descr
17. Sets the form variable to be read only PARAMETERS form spec index of the form var Index into the FormVar array of the variable readonly O for read write this is the default 1 for read only RETURN VALUE 0 Success 1 Failure SEE ALSO sspec getfvreadonlv TCP IP Manual Vol 2 rabbit com 127 sspec setpermissions int sspec setpermissions int sspec char realm word readgroups word writegroups word servermask word method MIMETypeMap mimetype DESCRIPTION Set the permission access control attributes of a resource This only works for RAM table entries For entries in a filesystem use sspec_addrule PARAMETERS sspec spec index realm Realm string or NULL readgroups Mask of user groups who have read access writegroups Mask of user groups who have write access servermask Servers that can access this resource or SERVER ANY for all servers method Required authentication method 0 SERVER AUTH BASIC etc mimetype MIME table entry or NULL RETURN VALUE 0 Success lt 0 Failure For example not a RAM spec handle SEE ALSO sspec checkpermissions sspec getpermissions sspec_access 128 rabbit com Server Utility Library sspec setpreformfunction int sspec setpreformfunction int form void fptr DESCRIPTION Sets a user function that will be called just before form generation The user function is not called when the form is being generated because of errors in the fo
18. The destination page of a submitted form can be any page When the web server receives a POST request with new variable data it checks the data using the error checking expression in the web statement that registered the variable If there is an error then the destination web page is displayed in error mode The following text describes how error mode affects the display of the destination web page By default the print statement displays the new value of the variable when in error mode To override the default behavior and show the old committed value note that the erroneous value has not been com mitted do the following lt z print foo gt The symbol specifies the old value of the variable To execute some code only when a certain variable has an error do the following lt z if error foo gt This value is in error lt z gt 272 rabbit com RabbitWeb It is also possible to say error foo If a value submitted for a variable has an error then error var used in a print statement evaluates to an error string if one was defined using the method described in Section 5 2 2 1 Here is an example lt z if error foo gt This value is lt z print error foo gt lt z gt Although the ZHTML parser can output error messages into the HTTP stream these messages may not be visible on a web page depending on how the browser is displaying pages The surest way to find out exactly
19. http getUserState void http getUserState HttpState state DESCRIPTION Get the user state area of the HTTP server structure This is an area of memory that can be used by the CGI to keep track of its internal state from call to call The size of this areais HTTP USERDATA SIZE Ifthat macro is not defined it defaults to zero so use of the http getUserState macro will result in a compile time error NOTE This is implemented as a macro Example typedef struct myCGIdata define HTTP USERDATA SIZE sizeof myCGIdata use http lib int myCGI HttpState s myCGIdata d d myCGIdata http getUserState state PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Returns the address of the first byte of the user area This should be cast to the appropriate struc ture type LIBRARY HTTP LIB SEE ALSO http_getAction TCP IP Manual Vol 2 rabbit com 217 http handler void http handler void DESCRIPTION This is the basic control function for the HTTP server a tick function to run the HTTP daemon It must be called periodically for the daemon to work It parses the requests and passes control to the other handlers either html handler shtml handler or to the developer defined CGI handler based on the request s extension LIBRARY HTTP LIB SEE ALSO http_init http idle int http idle void DESCRIPTION
20. 1 the supplied index was outside the table bounds Otherwise returns the c_ index parameter LIBRARY SNMP LIB SEE ALSO snmp add community snmp set dflt communities snmp community name snmp community mask 428 rabbit com SNMP snmp set dflt communities int snmp set dflt communities char public char private char trapdest DESCRIPTION Sets the name i e password string of the first 3 default communities These communities are assigned the following access masks e public SNMP_PUBLIC_MASK read only access e private SNMP PRIVATE MASK read write access e trapdest SNMP_TRAPDEST MASK no local access used when sending traps to the net work management agent This function should be called once when the application is initialized All parameters are null terminated strings with a maximum length of SNMP MAX COMMUNITY NAME PARAMETERS public Public access password private Private access password trapdest Trap password sent with trap messages RETURN VALUE 0 LIBRARY SNMP LIB SEE ALSO snmp add communitv snmp set community snmp community name snmp communitv mask TCP IP Manual Vol 2 rabbit com 429 snmp set foct snmp parms snmp set foct snmp parms p char s DESCRIPTION Set the value of a fixed length object The OID of the object must be set in p If the object is not in fact a fixed length binary object then NULL will be returned and there will be no alteration
21. 25 lt UL gt Rn a gt After the usual opening lines of an HTML page the first server parsed tag we encounter is used with the call to error to display a form submission error message the same way we did in the humidity detec tor example in Section 5 1 2 2 Next is an example of a for loop used to print additional more focused 286 rabbit com RabbitWeb error messages regarding the local TCP port number and the baud rate for each serial port Again error is used with an if statement to verify the submission of particular web variables and display whatever error messages are chosen lt FORM ACTION index zhtml METHOD POST gt lt z for SA 0 A c count serial ports 0 A 2 siasseriejl Port lt 27 eco Ssexial ports SA ser pore P Serro lt H2 gt lt TABLE gt The form is defined next Another for loop allows us to have the same form entries for each serial port in turn When displayed without errors the page looks like this Figure 5 11 Web Page Served by RabbitWeb Eile Edit View Search Go Bookmarks Tasks Help B gt ee E e ay a ge i id id Ethernet to Serial Configuration Mozilla Build ID 2001090111 Izjjejjxi ra L There are two tables one for serial port E and if you could scroll down in Figure 5 11 you would see that it is fol lowed by a table for serial port F Each table consists of Serial Port E Setup five rows and two columns Ethernet to Serial C
22. B etc Variables appear in directory listing of the root directory however they cannot be opened using sspec_open variable Address of the variable in extended memory type Variable type one of INTS single character INT16 2 byte integer PTR16 string in root memory INT32 4 byte long integer FLOAT32 floating point variable format Output format of the variable as a printf conversion specifier e g d servermask Bitmask representing valid servers currently only useful with SERVER_HTTP RETURN VALUE 1 Failure 20 Success the index of the variable in the resource list SEE ALSO sspec addfsfile sspec addrootfile sspec addvariable sspec addfunction sspec addform sspec addxmemfile sspec aliasspec 70 rabbit com Server Utilitv Librarv sspec aliasspec int sspec aliasspec int sspec char name DESCRIPTION Creates an alias to an existing ServerSpec structure Make sure that SSPEC_MAXSPEC is large enough to hold this new entry This is NOT a deep copy That is any file variable or form that the alias the new spec entry references will be the same copy of the file variable or form that already exists in the old spec entry This should be called only when the original entry has been completely set up NOTE do not attempt to alias a sspec handle that was returned by sspec open because the handle may be dynamically allocated In such a case the alias will not w
23. DCinProg Samples tcpip http pages UPLOAD HTML z l Links File to upload rT to A new him _Browse File to upload mM to A new2 him Browse Upload E Done TE My Computer The construction of this page is outlined below but it has been simplified and reformatted slightly A blow by blow description of each line is added in italics lt html gt This introduces the page as an HTML document 166 rabbit com HTTP Server lt head gt lt title gt HTTP Upload Form lt title gt lt head gt This HTTP Upload Form gets displayed at the top of the browser window You can change this to what ever is appropriate for describing the overall purpose of this page lt body gt Introduce the main content of this page lt FORM ACTION upload cgi METHOD POST enctype multipart form data gt Start a form definition The parameters are action upload cgi this refers to the CGI function that will process the results of the form submission This is a URL name which is mapped to a C function on the server method post this is required since a post type request must be sent to the server enctype multipart form data this is also required and is the part that is different from the old style of processing The old style did not specify an encoding type thus the default of URL encoded was used lt TABLE BORDER 0 CELLSPACING 2 CELLPADDING 1 gt For neatness of screen layout
24. SA gt lt TD gt lt zZ print Sfoo SA gt lt z gt lt TR gt lt TABLE gt This code will display the variables foo 0 foo 1 foo 2 foo 3 and foo 4 in an HTML table It is also possible to get the number of elements in a one dimensional array by doing the following lt z for SA 0 A lt count foo 0 SA gt The second parameter to count indicates that we want the upper bound of the nth array index of foo From this you can infer that the first parameter must be an array For example if foo is a three dimen sional array then count foo 0 yields the array bound for the first dimension count foo 1 yields the array bound for the second dimension and count foo 2 yields the array bound for the third dimension 5 3 2 2 Conditional Code In addition to looping you can have conditional code with if statements The if statement is specified as follows lt z if SA 0 73 HTML code lt z gt where e A The variable to check in the conditional This can be anything that evaluates to a number whether it be a normal integral web registered variable a loop variable a numeric literal or a count expres sion e The relational operator in the if statement This can be lt gt lt or gt e 0 The number to which the variable should be compared This can be anything that evaluates to a num ber whether
25. e is not as fast because of the step by step protocol e uses fewer machine resources Because of the lack of authentication most TFTP servers restrict the set of accessible files to a small num ber of configuration files in a single directory For uploading files servers are usually configured to accept only certain file names that are writable by any user If these restrictions are acceptable TFTP has the advantage of requiring very little footprint in the client host 9 1 BOOTP DHCP In conjunction with DHCP BOOTP and appropriate server configuration TFTP is often used to download a kernel image to a diskless host The target TCP IP board does not currently support loading the BIOS in this way since the BIOS and application program are written to non volatile flash memory However the downloaded file does not have to be a binary executable it can be any reasonably small file such as an application configuration file TFTP and DHCP BOOTP can thus be used to administer the configuration of multiple targets from a central server Using TFTP with BOOTP DHCP requires minimal additional effort for the programmer Just define the symbol DHCP_USE_TFTP to an integer representing the maximum allowable boot file size 1 65535 See the description of the variables bootpsize bootpdata and bootperror in vol ume of the TCP IP User s Manual for further details TCP IP Manual Vol 2 rabbit com 345 9 2 Data Structure for TFTP T
26. echo vars io state gt lt P gt lt FORM ACTION update cgi METHOD POST enctype multipart form data gt lt P gt Enter a new value if you dare lt P gt lt INPUT TYPE text NAME io state SIZE 5 VALUE lt echo vars io state gt gt lt INPUT TVPE submit VALUE Submit gt lt INPUT TYPE reset VALUE Reset gt lt FORM gt lt BR gt lt FORM ACTION upload cgi METHOD POST enctype multipart form data gt lt TABLE BORDER 0 CELLSPACING 2 CELLPADDING 1 gt lt TR gt lt TD ALIGN RIGHT gt File to upload lt BR gt to A new htm lt TD gt lt TD gt lt INPUT TYPE FILE NAME fs2 extl new htm SIZE 50 gt lt TD gt lt TR gt lt TABLE gt lt INPUT TYPE SUBMIT VALUE Upload gt lt FORM gt lt BODY gt lt HTML gt The first change is the substitution of the new server parsed tags with SSI tags The next change is the absence of any error checking Without RabbitWeb it is difficult to achieve this same functionality The CGI responsible for the processing the variable update would need to do it Which brings us to the next change in this HTML page the need for a second CGI function The ACTION attribute in the FORM tag identifies the new CGI by name update cgi The FORM tag also has a parameter for the encoding type When no encoding type is specified it defaults to URL encoded All new style CGIs must set the encoding type in the FORM tag to multipart form data as shown a
27. of course does entirely different things The server needs to have a lookup table defined which translates URLs into the appropriate local type of resource This is the function of the resource table which is also known as the flashspec or ramspec table in Dynamic C parlance The static resource table is a statically defined constant table The dynamic resource table is generated at runtime Both types can be used in the same program with dynamic entries overriding static entries with the same URL With this release of Dynamic C there is no need to put anything in either of these tables provided that a filesystem FAT or FS2 is used However it is convenient to have at least a few entries in the dynamic table and it is mandatory to have entries in either or both the static and dynamic tables if CGI functions are used 180 rabbit com HTTP Server When using the HTTP upload facility you will need at least one CGI function to be defined and probably another entry for the initial form The resource table may be defined as follows SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE index html index html SSPEC RESOURCE CGI upload cgi mv CGI SSPEC RESOURCETABLE END This defines a static resource table with two entries The first is a static web page for the form index htm1 and the second points to the CGI that will be used to process the uploaded data Impor tant use SSPEC RESOURCE CGI not SSPEC RESOURCE FUN
28. or if there is no object with the given OID or if the object was not stored with variable length octet string type Otherwise returns p LIBRARY MIB LIB SEE ALSO snmp init parms snmp set stem snmp append stem snmp get indexed snmp get snmp add snmp xadd snmp set int snmp set long snmp set str snmp set foct snmp set objectID 434 rabbit com SNMP snmp set oid snmp oid snmp set oid snmp oid oid word len char eos DESCRIPTION This function is identical to snmp set stem except that it uses an snmp oid structure See documentation for snmp set stem PARAMETERS oid Pointer to snmp oid structure to set If NULL does nothing but return NULL len Length of eos eos Encoded OID string RETURN VALUE Returns oid unless the OID string is too long to fit in the snmp oid structure in which case NULL is returned If oid is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp append oid snmp set parse oid snmp set stem TCP IP Manual Vol 2 rabbit com 435 snmp set parse oid snmp oid snmp set parse oid snmp oid oid char name DESCRIPTION This function is identical to snmp set parse stem except that it uses an snmp_oid structure See documentation for snmp set parse stem PARAMETERS oid Pointer to snmp oid structure to set If it is NULL does nothing but return NULL name OID string in dotted decimal notation e g 4
29. we probably want to return an error indication to the client This can be done using the http switchCGI orcgi redirectto functions A special page will need to be created for this purpose If this page is called upld err htmI then the following code could be used case CGI DATA handle http getCond s COND HANDLE if sspec write handle http getData s http getDataLength s lt 0 sspec close handle http switchCGI s upld_err html break In the case of an error the handle is closed then the HTTP server presents the upld err html page to the client The current CGI is abandoned including any pending data that is still incoming This is why the handle is explicitly closed since upld err htmli probably doesn t know anything about itl Natu rally upld err html is a web page that tells the user that something went wrong In practice this would usually be an SSI rather than a static web page since you would probably want to give the user dif ferent feedback depending on the exact type of error The final consideration is what to do if sspec_write can only write some or perhaps none of the data it was given The normal course of action is to just retry later with the data that was not written You could just sit in a loop in the CGI function waiting for the data to be written This may be satisfactory in some cases but often this will unnecessarily reduce system performance since nothing else will
30. we put everything in an HTML table The following lt TR gt lt TR gt sections delimit each row of the table and the data for each cell is delimited by lt TD gt lt TD gt lt TR gt lt TD WIDTH 130 ALIGN RIGHT gt lt B gt Name lt B gt lt TD gt lt TD WIDTH 500 gt lt INPUT TYPE TEXT NAME user name SIZE 50 gt lt TD gt This is the first input field It is not a file to upload but it is information that the server may nevertheless be interested in This shows that not every form field needs to be a file to upload The order is important Brows ers will send back the form fields in the same order that they are defined in the HTML however it is probably best not to rely on this if you can help it lt TR gt lt TR gt lt TD ALIGN RIGHT gt lt B gt File to upload lt BR gt to A new htm lt B gt lt TD gt lt TD gt lt INPUT TYPE FILE NAME A new htm SIZE 50 gt lt TD gt This is the file to upload input field The browser displays this as a text input field with an additional browse button so that the user can easily navigate his local filesystem to find the appropriate file The crit ical distinction is that it contains a type file parameter as opposed to for example type text in the previous field The name A new htm parameter specifies the name of the input field not the name of the file on the user s system As it happens this looks like a file name and indeed the server may use it as t
31. word servermask DESCRIPTION Adds a file located in extended memory to the RAM resource list Make sure that SSPEC MAXSPEC is large enough to hold this new entry PARAMETERS name Name of the new file This must be unique but this function does not check The name should not conflict with the virtual filesystem hierarchy That is it should not start with fs2 A B etc fileloc Location of the beginning of the file The first 4 bvtes of the file must repre sent the length of the file ximport does this automatically servermask Bitmask representing servers for which this entrv will be valid e g SERVER HTTP SERVER FTP RETURN VALUE 1 Failure 20 Success the location of the file in the dynamic resource list SEE ALSO sspec addfsfile sspec addrootfile sspec addvariable sspec addxmemvar sspec addfunction sspec addform sspec aliasspec TCP IP Manual Vol 2 rabbit com 69 sspec addxmemvar int sspec addxmemvar char name long variable word type char format word servermask DESCRIPTION Add a variable located in extended memory to the RAM resource list Make sure that SSPEC MAXSPEC is large enough to hold this new entry Currently this function is useful only for the HTTP server PARAMETERS name Name of the new variable This must be unique but this function does not check The name should not conflict with the virtual filesystem hierarchy That is it should not start with fs2 A
32. 348 5 5 4 ZHTML Grammar 291 L 349 5 5 5 Rabbit Web Functions 292 titp TIC esseeri toss 350 l 295 titp EXEC nitie apoian 351 E tanti 10 SMTP Mail Client 353 jeanne MEER i a 10 1 Sample Conversation mn 353 UNCtIONS aerieni MA 6 2 1 Initialization Functions 296 10 2 SMTP A EA appia 354 6 2 2 Connect and Request Functions 296 10 3 sapi panang of an E mail 355 6 2 3 Read Server Response Functions 296 10 4 Configuration Macros 356 6 2 4 Miscellaneous Functions 296 10 5 API Functions sse eeesseenzznnenzi 357 6 2 5 Function Descriptions 297 smtp data handler n 357 A smtp mailtiek sse 359 7 FIPClienmt e eennnnzenznnnnzena 313 smtp sendmail B i att 360 7 1 Configuration Macros 313 ji ae area peernnzazzznnanzznnzz a l smtp_setauth e neennnn 7 2 API Functions A A A 314 SMEP SELSETVET ssesssceesesesseseeeeeeeee 363 ftp client SetUp ses mnn 314 smtp setserver p L mem 363 ftp client setup url L sen 315 smtp StatUS s sssessesenzanenzznznnzzznznzi 364 ftp client tiek sen 316 ftp client filesize sen 317 11 POP3 Client 365 EA Aapee neaei Sener Eia ee Eri a 11 1 Configuration aa tas 365 tp data handler sen feat cade A 319 11 2 Steps to Receive E mail 366 7 3 Sample FTP Transfer s sssesenennsnnenn 320 11 3 Call Back Function ee 366 11 3 1 Normal call back 366 8 FTP Server cccccccccccccceeeesersee
33. 6 Zconsole Execution Choices Zconsole can be used interactively with a terminal emulator or by sending commands from a program run ning on a device connected to the controller that is running the console 14 6 6 1 Terminal Emulator To manually enter Zconsole commands from a keyboard and view results in the Stdio window you must 1 Run Dynamic C 7 05 or later 2 Open a terminal emulator Windows HyperTerminal comes with Windows It does not work with binary files only ASCII Tera Term can handle both ASCII and binary It is available for free download at http hp vector co jp authors VA002416 teraterm html 3 Configure the terminal emulator as follows COM port 1 or 2 to which 3 wire serial cable is connected Baud Rate 57 600 bps Data Bits 8 Parity None Stop Bits 1 Flow Control None The terminal emulator should now accept Zconsole commands To avoid losing an lt LF gt at the beginning of a file when using the con_put command function select Setup gt Terminal from the Tera Term menu and set the Transmit option to CR LF This option might be located elsewhere if you are using a different terminal emulator TCP IP Manual Vol 2 rabbit com 483 14 7 Backup System Zconsole can save configuration parameters to the file system or starting with Dynamic C 7 30 to the User block The configuration is then available across power cycles The backup process is done by con backup Unlike the other Zconsole command
34. After the usual URL string and function pointer the next parameters are e newPages this is the so called realm of the CGI resource This is not particularly significant except that it notifies the client that this is a restricted resource and that a userid password will be required The user sees this string when prompted for his or her credentials e ADMIN GROUP this was the group defined above In this context it applies to the read access rights To read this resource that is to use the CGI the user needs to be in this group e 0x0000 this is also a group bit parameter for write access CGIs themselves do not have the concept of writabilitv that would imply the ability to change the CGI function so this is always zero for a CGI e SERVER_HTTP this specifies the server that can use the CGI function CGIs are currently only usable by the HTTP server thus there is no other sensible choice for this parameter e SERVER AUTH BASIC this specifies the required minimum authentication method BASIC means that a simple plain text userid and password will be required A better choice is SERVER AUTH DIGEST since that does not reveal the password to anyone listening in on the con versation however older web browsers do not support this 182 rabbit com HTTP Server Next the file system needs to be protected Usually you do not want the entire file system to be writable even to the privileged group members To
35. C 7 30 It indicates the number of arguments in the command line that are NOT part of the command name itself For instance for the command SET IP 10 10 6 112 ETHO state gt commandparams would be 2 but state gt numparams would be 4 This distinction is made to allow the commands in Zconsole to be insensitive to the number of words that make up the name of the command itself but still maintain backwards compatibility with custom commands that use state gt numparams The function that implements the custom command should return 0 when it has more processing to do and thus will be called again 1 for successful completion of its task and 1 to report an error The third and final field of the console commands entry is the physical address of the help text file for the custom command in question This file must be ximported along with all of the default com mand function help files that are being used IMPORTANT The fields discussed in the previous paragraph and the fields that have comments in the structure definition are the only ones that an application program should change The other fields must not be changed 14 4 2 Zconsole Error Messages ZCONSOLE LIB provides a list of default error messages for the default Zconsole commands An appli cation program must define an array for these error messages as well as for any custom error messages that are desired To include only the default error messages the following array is su
36. DESCRIPTION This function is used in conjunction with the FTP USE FS2 HANDLERS macro It loads the data structure i e the server spec list that keeps track of the association of filenames to file lo cations in the file system The information is loaded from the User block from the offset given in FTP USERBLOCK OFFSET The function removes anv entries from the server spec list that are not FS2 files RETURN VALUE 0 Success 1 Failure possibly due to the filenames having not yet been saved SEE ALSO ftp save filenames TCP IP Manual Vol 2 rabbit com 337 ftp save filenames int ftp save filenames void DESCRIPTION This function is used in conjunction with the FTP USE FS2 HANDLERS macro This function saves the data structure i e the server spec list that keeps track of the association of filenames to file locations in the file system The information is saved to the User block at the offset given in FTP USERBLOCK OFFSET RETURN VALUE 0 Success 1 Failure the information could not be saved due to a write error SEE ALSO ftp load filenames 338 rabbit com FTP Server ftp set anonymous int ftp set anonvmous int uid DESCRIPTION Set the anonymous user ID Resources belonging to this userID may be accessed by any user A typical use of this function would be ftp set anonymous sauth adduser anonvmous SERVER FTP which defines an anonymous login for the FTP s
37. LIBRARV HTTP LIB SEE ALSO http handler http init http shutdown TCP IP Manual Vol 2 rabbit com 241 http switchCGI int http switchCGI HttpState state char newURL DESCRIPTION Tell the HTTP server to switch processing to a different CGI function or resource The CGI is responsible for generating the correct HTTP response header s using http write etc If this function is used to pass control to a different CGI then both CGIs must coordinate so that only one header is written You can use the HTTP state variable http setState andhttp getState and orhttp getUserState to achieve the necessary coordination If newURL refers to a file or SSI resource not a CGI then the CGI function must NOT have already written the HTTP response header s the headers will be generated when the new re source is opened If newURL refers to a new style CGI that is a CGI resource added using SSPEC_ CGI not SSPEC FUNCTION then that CGI is presented with the remaining content of the current re quest data stream If newURL refers to an old style CGI that is a CGI added using SSPEC FUNCTION or HTTPSPEC FUNCTION then the HTTP server abandons parsing of the request data stream since old style CGIs are expected to read the HTTP socket themselves Rather than calling http switchCGI itis often more convenient to call cgi redirectto which tells the client to retrieve the next resource rather than the re source
38. Mail Address http nowhere org admin index zhtmi Go Links Configure the humidity device Humidity alarm level percent 75 Send email alarm to somebody nowhere org Minirnum time between alarms minutes feo Submit Return to the humidity monitor page 258 rabbit com RabbitWeb 5 2 Dynamic C Language Enhancements for RabbitWeb This section describes the RabbitWeb language enhancements and how to make use of them to create a RabbitWeb server These language enhancements are designed to interact with the ZHTML scripting language described in Section 5 3 They work together to provide an easy to program web enabled interface to your device 5 2 1 Registering Variables Arrays and Structures Registering variables arrays or structures with the web server is easy First we ll look at the simple case of an integer variable int foo web foo The variable foo is declared as an integer in the first expression and then registered with the web server in the second Variable registration can only be done at compile time Atrays and structures are registered in the same way as variables int temps 20 web temps Strings which are character arrays can also be registered char mystring 20 web mystring Strings receive special handling by RabbitWeb The bounds are always checked when updating a string through a RabbitWeb interface which means that the character buffer will not o
39. Managed variables Read write ine TAWX ALE long rw long char rw fixed 20 clieue 689 sies 20 5 char rw_oct 22 snmp_oid rw_oid longword trapdest_ip longword rw tt Managed variables Read only ag 12 amey long r_long Chear _iessKecl 20 Ghear Siew ZO 7 Glague i oe 22 5 snmp oid r oid The data structure snmp oid is an internal data structure defined in MIB LIB It is used to hold the OID of a managed object Another ubiquitous data structure snmp parms is also defined in MIB LIB It is used to pass parameters to most of the API functions described in Section 12 4 TCP IP Manual Vol 2 rabbit com 379 12 2 2 Callback Functions Callback functions provide a way to customize data handling The callback is invoked by the SNMP agent for each get or set request If there is no callback for a particular object then access to that object is always granted according to the read write masks The callback function should be defined as follows int mv callback snmp parms p int wr int commit void v word len word maxlen PARAMETERS p snmp parms contains most of the information about the access It is set up with the full OID of the object plus its current value wr This parameter is non zero if this is a write access otherwise it is a read ac cess commit This parameter implements a 2 stage query commit process It is necessary because any single SNMP request must be performed full
40. RETURN VALUE 0 No data is currently available If the 1en parameter was zero then a return value of zero def initely means end of file has been reached If 1en gt 0 there may be data available in the future e g because the underlying filesystem is socket based and this host has read all available data but the socket is still open to receive more data 1 len the specified number of characters has been copied to the supplied buffer and the cur rent file position has been advanced by that many bytes Possibly less than 1en bytes may be read in which case the server should test for EOF gt len no data was copied because the underlying filesystem is unable to return a partial record and maintain its current position The return value is the minimum sized buffer that should be passed on the next call Note this sort of return is not currently implemented by any of the file systems however servers should be coded to handle this case for future anticipated systems which have record level access rather than byte level The following return values are negatives of the values defined in errno lib e EINVA len parameter was lt 0 e EBADF The specified handle was not open or invalid e Any other negative values indicate an error SEE ALSO sspec close sspec write sspec seek sspec tell sspec open sspec readchr 110 rabbit com Server Utilitv Librarv sspec readchr int sspec readchr int sspec char far buf int le
41. Server 4 5 4 HTML Forms Using Zserver lib In this section we will step through a sample program Samples tcpip http forml1 c that uses HTML forms Through this step by step explanation the method of using the functions in zserver 1ib will become clear As of Dynamic C 8 50 you have the option of using the RabbitWeb server with its easier to use interface and completely flexible ZHTML page layout capabilities Defining FORM ERROR BUF is required in order to use the HTML form functionality in Zserver 1ib The value represents the number of bytes that will be reserved in root memory for the buffer that will be used for form processing This buffer must be large enough to hold the name and value for each variable plus four bytes for each variable Since we are building a small form 256 bytes is suffi cient define FORM ERROR BUF 256 Since we will not be using the static resource table we can define the following macro to remove some code for handling this table from Zserver define HTTP NO FLASHSPEC These lines are part of the standard TCP IP and MIME table configuration memmap xmem tuse UWeleiieejo lip use http lib SSPEC MIMETABLE START SSPEC MIME html1 text html SSPEC MIMETABLE END These are the declarations of the variables that will be included in the form int temphi int tempnow int templo float humidity Glague i en 2113 void main void An array of type FormVar must be declared to
42. Structure This structure is only relevant if you are using the FAT filesystem It allows the sspec automount function to return some FAT related information to your application The fields in this structure are ctrl Pointer to dos_ctr1 controller structure drive Pointer to mbr_ drive structure part 4 4 pointers to fat part partition structures Only the mounted partitions are returned Note that when used with sspec_automount some of the above fields may be set to non NULL in order to indicate to sspec_ automount that the application has already initialized some or all of the FAT TCP IP Manual Vol 2 rabbit com 37 3 1 9 FormVar Structure An array of FormVar structures represent the variables in an HTML form The developer will declare an array of these structures with the size needed to hold all variables for a particular form The FormVar structure contains e A server spec index that references the variable to be modified This is the location of the form variable in the server spec list e An integrity checking function pointer that ensures that the variables are set to valid values e High and low values for numerical types e Length for the string type and for the maximum length of the string representations of values e A Pointer to an array of values for when the value must be one of a specific and probably short list The developer can specify whether the variable is set through a text entr
43. The main C function should have a loop in it which calls http handler void main int uid sock init Initialize the network Mount the FAT filesystem sspec automount SSPEC MOUNT ANY NULL NULL NULL Create the authorized user as described in the previous section uid sauth adduser admin upload SERVER HTTP sauth setusermask uid ADMIN GROUP NULL sauth setwriteaccess uid SERVER HTTP http init Initialize the HTTP server tcp reserveport 80 Enable smooth handling of multiple HTTP requests for http _handler The big loop Drives everything All error handling has been pared out of the above code For full details please refer to the sample pro gram samples tcpip http upld_ fat c 184 rabbit com HTTP Server cgi_continue cgi_redirectto cgi_sendstring http_abortCGI http_addfile http_contentencode http_date_str http_defaultCGI http_delfile http_finderrbuf http_finishCGI http_getAction http_getCond http_getContentDisposition http_getContentLength http_getContentType http_getcontext http_getContext http_getData http_getDataLength http_getField http_getHTTPMethod http_getHTTPMethod_str 4 7 API Functions for HTTP Servers Below is a list of links to the function descriptions for each of the API functions for the HTTP server http get HTTPVersion http getHTTPVersion str http getRemainingLength http get sock http getSocket http getState http ge
44. There are several configuration macros that may be set up by the application to control the memory usage and behavior of Zserver These should be defined before use Zserver lib unless otherwise noted HTTP NO FLASHSPEC SSPEC NO STATIC When defined these macros save space bv not compiling in code that supports a static resource table Presumably the application is using only the dynamic resource table or filesystems are in use Historical note the name of HTTP NO FLASHSPEC implies HTTP however it actually ap plies to Zserver as a whole not any specific server Dynamic C 8 50 introduces SSPEC_NO_STATIC an alias for HTTP NO FLASHSPEC TCP IP Manual Vol 2 rabbit com 39 SAUTH MAXNAME Maximum length of the name and password strings in the ServerAuth structure Default is 20 Strings must include a NULL character so with its default value of 20 strings in this structure may be at most 19 characters long SAUTH MAXUSERS Define the maximum number of unique users Defaults to 4 This determines the size of the userid table Each table entry takes up 2 SAUTH_MAXNAME 8 bytes of root storage SERVER PASSWORD ONLY This is set to a bitmask of the server mask bits for each server that supports the concept of a pass word only user that is no user name Defaults to zero since currently no servers are implemented that use this facility SSPEC DEFAULT READGROUPS SSPEC DEFAULT WRITEGROUPS SSPEC DEFAULT SERVERMASK SSPEC DEFAULT REA
45. Up stem o oo eee 445 samp used A aka iappeiren ipsa be st 446 R Simp Radd persier rererere iseer k eat 447 Telnet resources telnet close cccccccesssssssssesecsescesesecsesceseseess 456 access Controls oss seeeneenenenzznnennenenenn nts nn 16 telnet init erreneren 455 ruletable iii ee E S 16 telnet k sisien ee g 456 S yserial CLOSE cvccsseicssvecsssecvavecseecedeccseteceees 450 yserialinit oo nn eneeeeeenenenennenenzann 451 sample programs vserial_Keepalive csccssecesseesseessssee 451 FTP a dias tintcnatenacaminedaneminaidanes 341 vserial listen Leemeesssenenmnzznnnezzzzonzenzznnnnnn 452 POP3 client eee en ee ne rere 370 vserial OPEN ssssseseesssseecsseseeeeesnnneeecenenes 453 SMTP client eeesesssnnzzzznnnzzzznznnzznzznznnzzzznzzzznu 355 yserial tiek sesseemeeenzznnnnzznnzenmnzzoninnnnzznn 454 telnet client agit atl te ee eee nce ene 458 TFTP Client telnet Se a ences 457 WP EXEC Leseeesssnnzzznzznnenzznznzznenzznenzzzzonaznzni 351 LLONSOLE sa a f Be ei 488 tpit a 347 SAUTH MAXNAME Menu 40 L ANTEX EE 348 SAUTH MAXUSERS semen 40 tftp tiek sessssesssnnnzzonzznzznzzonizznnnzanznznnzznnii 349 SECUN aer e n ae 145 CHOP TICK serina e 350 SERIAL PORT SPEED orrn 455 H server spec LSE Lis sis iai ii Area ina teriores 33 36 SERVER PASSWORD ONLX else eesenznzznnzz 40 HTML fOrMS cccccccccccccccececcccccceecececceceee 44 153 163 SMTP chent 4 224 ii niet 353 364 HTTP configuration Macro semm eeeenennznznzanan 141 SMTP co
46. Ver i ia EE E 142 f 10 L EE E E E E T 365 SMTP SEE sorei eni E EE EE 353 Z ZCOMNSOLE L Lee nnennnenzannnnenenzznnnnnennnzananannnnna 459 491 backup systemi s c s seesstesscoceeseresecsnessnsvordenes 484 Circular buffers cc esseenennenzznnnenznzzznnnnnnnza 474 commands cccccccesesssseeceeeesesseececesesseeteeecesseaees 460 custom commands sse ssrenenzazennnnnznnzzzznnnnnnnza 468 ITOPMESSABES is ikattar as nse 469 I O interfaces ss seseeenennennzannnnnnnnanzznnnnnnnza 472 MA TAS L istess reba 486 487 physical connection en 474 terminal emulator ss ssseenenzzzenennazzznnnnnnnza 483 USING TEP IB l is nsi use e 474 TCP IP Manual Vol 2 rabbit com 497 498 rabbit com Index
47. Vol 2 rabbit com 211 http getRemainingLength long http getRemainingLength HttpState state DESCRIPTION Return the remaining length of the incoming data stream This length includes all parts not just the current part and also includes the boundary separators and epilog data Normally this value will be zero when the action code is CGI_ EOF If the value is negative then the client might not have indicated the total data length or might not have set the right value NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Length of remaining data or negative if not known LIBRARY HTTP LIB SEE ALSO http_getAction 212 rabbit com HTTP Server http get sock tcp Socket http get sock HttpState state DESCRIPTION This function allows direct access to the TCP socket of an HTTP or HTTPS server This will always return the TCP socket associated with the server even if that server is HTTPS This is intended for READ ONLY operations Since this function returns a pointer to the actual socket changing fields directly affects the connection which could lead to problems especially with HTTPS servers PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Pointer to the TCP socket structure of the HTTP or HTTPS server LIBRARY HTTP LIB http getSocket tcp S
48. With HTML Forms 153 4 5 4 HTML Forms Using Zserver lib 159 4 6 HTTP File Upload 164 4 6 1 What is a CGI Function and Why is It Useful 164 4 6 2 How Do I Use the New CGI Facility 165 4 7 API Functions for HTTP Servers 185 BRP CD cast ontcncddeaneniteeeadendannctes 249 5 1 Getting Started A Simple Example 249 5 1 1 Dynamic C Application Code for Humidity Detector 249 5 1 2 HTML Pages for Humidity Detector 254 5 2 Dynamic C Language Enhancements for Rabbit Web nn 259 5 2 1 Registering Variables Arrays and Structures 259 5 2 2 Web Guards 260 5 2 3 Security Features 263 5 2 4 Handling Variable Changes 265 5 3 ZHTML Scripting Language 267 5 3 1 SSI Tags Statements and Variables 267 5 3 2 Flow Control 268 5 3 3 Selection Variables 270 5 3 4 Checkboxes and RadioButtons 271 5 3 5 Error Handling 272 5 3 6 Security Permissions and Authentica tion 273 5 4 TCP to Serial Port Configuration Example 274 5 4 1 Dynamic C Application Code 274 5 4 2 HTML Page for TCP to Serial Port Example 286 TCP IP Manual Vol 2 rabbit com iii 5 5 RabbitWeb Reference 288 9 1 BOOTP DHCP eee enenni 345 5 5 1 Language Enhancements Grammar 9 2 Data Structure for TFTP ssssssessezezz 346 288 9 3 API Functions ssesessenzznsznznzznnzza 346 5 5 2 Configuration Macros 289 tftp amit eeeececccccsesssesssssssssesssseeseesee 347 5 5 3 Compiler Directives 290 IA ec eeeceecceecsseesssessseesseesseeeens
49. a given upload the CGI is called with a typical sequence of action codes The first code is CGI START for the start of a new part CGI DATA for each chunk of data in that part then CGI_END for the end of the part Thus the typical sequence for a single part is CGI START CGI DATA CGI DATA CGI DATA CGI_END Finally at the end of all the parts the action code is set to CGI_EOF Most CGIs should also handle a special action code called CCI ABORT This code only occurs if the upload is terminated early by a network problem or by the user pressing the browser s cancel or stop but ton Let s examine a simple CGI that handles these five action codes This is the minimum requirement how ever there are some additional codes that may be used by more advanced CGIs The switch statement ignores action codes that are not listed This is deliberate since any other action codes may be safely ignored int mv CGI HttpState s switch http getAction s case CGI START break case CGI DATA break case CGI END break case CGI EOF break case CGI ABORT break return 0 The above code is a skeleton that does nothing In other words all incoming data is sent to the bit bucket It is ready to fill out with more useful actions To avoid repeating the code we just take each case condi tion and fill in the details 170 rabbit com HTTP Server Action Code CGI START When the action code CGI_ S
50. already exists position at end of file so as to append new data You can later seek to the existing portion of the file TCP IP Manual Vol 2 rabbit com 107 sspec open cont RETURN VALUE 20 Success The returned value should be passed to other functions that require a general han dle suchas sspec read sspec seek sspec write sspec tell and sspec_close The following return values are negatives of the values defined in errno lib e ENOENT The resource was not found when it was expected to exist e EACCES The context gt userid field was not 1 and the specified user is not allowed to access the resource using the specified mode EINVAL The resource name was malformed e g too long or context was NULL or the resource was not a file type or O_CREAT O_TRUNC or O_APPEND were speci fied without O WRITE ENOMEM Insufficient storage for handle or buffers Increase definition of SSPEC_MAX OPEN e EPERM Operation not permitted for example opening an xmem file for writing SEE ALSO sspec read sspec write sspec seek sspec tell sspec close 108 rabbit com Server Utilitv Librarv sspec pwd char sspec pwd ServerContext context char buf DESCRIPTION Print the current working directory in the ServerContext structure to the specified buffer The context gt cwd field contains the CWD This function removes the root directory compo nent context gt rootdir and copie
51. and earlier do not consider the query string to be part of the URL that is included in the cryptographic hash whereas newer browsers e g IE7 and later are just the opposite This means that digest authentication can work with one or the other but not both Therefore it is only safe to use digest authentication without a query string at the end of the URL To use HTTP Digest Authentication define USE HTTP DIGEST AUTHENTICATION as 1 When this USE_ macro is defined the macros HTTP MAX NONCES and HTTP DIGEST NONCE TIMEOUT are available they affect negotiation time between server and client For more details see Section 4 2 Configuration Macros In either case basic or digest you will need to add the appropriate rules and or permissions to the appro priate tables See the previous chapter for details on protecting resources The HTTP server applies the strongest applicable authentication mechanism depending on the information it retrieves from the resource manager Typically in addition to defining user IDs and groups you also need to associate an authentica tion mechanism with the resource using e g the SSPEC MM RULE macro or the sspec setpermissions function Starting with Dynamic C 8 50 Secure Socket Layer SSL as specified in RFC 2818 is supported It is also known by its newer official name TLS Transport Layer Security To use SSL you must create a secure HTTP server known as an HTTPS server To do this you must
52. as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Length of part data LIBRARY HTTP LIB SEE ALSO http_getAction 202 rabbit com HTTP Server http getContentType char http getContentType HttpState state DESCRIPTION Return the current content type of the data which is being provided by the client This is a MIME type string e g text html or image jpeg The CGI might need to look at this to determine the appropriate way to process the data Normal form fields will usually contain text plain however uploaded files may contain any type of da ta It is only valid to call this when the action code is CGI_ START CGI_DATA or CGI_ END NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Null terminated string containing the MIME type name LIBRARY HTTP LIB SEE ALSO http_getAction TCP IP Manual Vol 2 rabbit com 203 http getcontext ServerContext http getcontext int servno DESCRIPTION Return the ServerContext struct for the specified HTTP server instance NOTE This structure should not be modified by the application PARAMETER servno Server instance number 0 HTTP_MAXSERVERS 1 RETURN VALUE NULL invalid server instance Otherwise pointer to this server s ServerContext LIBRARY HTTP LIB http
53. bar a differentuser_callback Ifbar bis updated user callback is called but if bar a is updated the function differentuser callback is called and notuser callback TCP IP Manual Vol 2 rabbit com 265 5 2 4 1 Interleaving Problems Consider the following scenario Users A and B are operating a web interface on Device C User A gets a form page from Device C and then leaves the computer for a while User B then gets the same form page from Device C updates the data and then the new values are committed on Device C Then User A comes back to his computer makes changes to the form that was left on his screen from earlier and sub mits those values Keep in mind that User A never saw the update done by User B What should Device C do Should it allow A s update Or should it tell User A that an interim update has been made and that he should thus review his changes in light of that fact Ideally the developer should be in control of how this scenario is handled since different applications have different needs One way to avoid trashing a valid update is given here int foo web foo Sfoo foo 1 web update foo increment value void increment value void oo Some client side JavaScript is needed in the ZHTML file where the foo value is included lt SCRIPT gt document write lt INPUT TYPE hidden NAME foo VALUE lt z echo foo gt 1 gt lt SCRIPT gt This causes the var
54. bells and whistles but is useful for the basics of making valid requests of an HTTP server and understanding the subsequent responses The initial version of http client lib requires Dynamic C 10 54 or later The following programs demonstrate using the librarv Samples tcpip http http client c Samples tcpip http dvndns c 6 1 Configuration Macros The following macros may be defined in a tdef ine statement before the inclusion of http client 1ib in an application program HTTPC VERBOSE If defined library will print status messages to Stdio window HTTPC DEBUG If defined functions will be debuggable e g you can set breakpoints and single step into them HTTPC HEADER TIMEOUT Timeout in milliseconds to wait for headers to complete when calling httpc skip headers Defaults to 5000 5 seconds HTTPC PROXY AUTH STRLEN Length of authentication information printable string in username password format for proxy server Does not include null terminator at end of string TCP IP Manual Vol 2 rabbit com 295 6 2 API Functions This section contains a quick API overview followed by detailed function descriptions The functions are located in Lib tcpip http client 1ib relative to the Dynamic C installation folder 6 2 1 Initialization Functions The initialization function httpc init if must be called before any other HTTP client function This function lets you specify an interface httpc_init isamacro
55. can be done lt z for SA 0 SA lt count select var 0 SA 73 lt OPTION lt z if selected select var A gt SELECTED lt z gt gt lt z print_opt select_var A gt The page Samples tcpip rabbitweb pages selection zhtml uses the selected function updating This function can be used with an if statement to test whether the current page is being displayed as the result of a POST request instead of a GET request This is useful to redirect to another page on a success ful form submission Use this function as follows lt z if updating gt lt z if error gt lt META HTTP EQUIV Refresh CONTENT 0 URL http yoururl com gt lt z Is lt z gt coy This function can be preceded by the not operator varname This is a convenience function that gets around the limitation of no square brackets in the NAME attribute of the INPUT tag in HTML lt INPUT TYPE text NAME lt z varname Sfoo 3 72 VALUE lt z echo Sfoo 3 gt gt TCP IP Manual Vol 2 rabbit com 293 294 rabbit com RabbitWeb RABE Tete 6 HTTP CLIENT The HTTP client library http client lib is used for connecting to web servers A common HTTP client implementation that most of us have used is found in a web brower e g Internet Explorer or Mozilla Firefox The client that can be implemented by this library is far less ambitious in terms of
56. cases in Zconsole lib where help text is needed but is not associated with a particular command It is still necessary to allocate a Consol eCommand structure to access the help text The first case is the help overview given when HELP is entered by itself The command field should be and the emdfunc field should be NULL NULL help txt The second case is HELP SET This is an overview of the family of SET commands i e commands that set configuration values For HELP SET the command field should be SET and the cmdfunc field should be NULL SET NULL help set txt This second case illustrates the general case of displaying help for a family of commands The family name can not be the name of a command 14 4 Zconsole Command Array An array of ConsoleCommand structures must be defined in an application program as a constant global variable named console commands All commands available at the console those provided in Zconsole lib and custom commands must have an entry in this array TCP IP Manual Vol 2 rabbit com 461 14 4 1 Zconsole Commands The following is an example of a list of commands that may be defined in a Zconsole application When the command name i e the string in the command field is received by the console the function pointed to in the cmdfunc field is executed When the console receives the command HELP lt command name gt the text file located at physical address he lptex
57. current directory is not changed The re sulting absolute directory name cannot be longer than SSPEC_MAXNAME including a leading and trailing character PARAMETERS path New directory path string as a null terminated string If this starts with it is merely appended to the context gt rootdir string Otherwise it is appended to the current directory in context gt cwd Directory compo nents are separated by characters A trailing slash is optional A directo ry component means up one level towards the root means no change to this level and a component of context Server context structure Two fields in this are of interest root dir points to a virtual root directory for this server For example if the FTP server is only allowed to access files under the A directory then root dir points to a string A If the user entered a directory name of ftpfiles the full directory would be A ftpfiles The other field that is updated by this function is cwd This is an array of characters of length SSPEC MAXNAME It contains the absolute path of the current directory with leading and trailing slash including the rootdir part if any check If TRUE check the resulting directory name to see if it exists Otherwise no check is made RETURN VALUE 0 OK Any other negative values indicate an error E2BIG Resulting directory name too long EACCES Attempt t
58. define some macros and import the SSL certificate define USE_HTTP SSL define HTTP SSL SOCKETS 1 ximport cert mycert dcc SSL CERTIFICATE For complete documentation on the Dynamic C implementation of SSL see the Dynamic C Module docu ment entitled Rabbit Embedded Security Pack Another good source of information are the sample pro grams that demonstrate using SSL They are located in the Samples tcpip ss1 folder that will be created when the Rabbit Embedded Security Pack is installed TCP IP Manual Vol 2 rabbit com 145 4 4 Setting the Time Zone The HTTP specification requires the server to indicate its current clock time in the response to any request The HTTP implementation performs this function by consulting the rtc_timezone library function in RTCLOCK LIB The server uses the returned time zone to adjust the local real time clock RTC value so that it is always returned to the client in UTC Co ordinated Universal Time There are several macros which you can set to define e TIMEZONE The local timezone offset from UTC e RTC_IS_UTC Whether the RTC is already running on UTC The local timezone offset may be defined using the TIMEZONE macro or it may be obtained automati cally from a DHCP server if you are using DHCP to configure the network interface Failing that it defaults to zero If the RTC is already set to UTC not local time then you must define the macro RTC_IS_UTC in which case the loc
59. e httpc skip headers skip over the headers entirely blocking call e httpc use proxy configure client to use a proxy server for all new connections 296 rabbit com HTTP Client 6 2 5 Function Descriptions httpe close httpc get httpe get url httpc headermatch httpe init httpe init if httpc open httpc post httpc post ext httpe post url httpc close void httpc close httpc Socket far ts DESCRIPTION Closes an open socket to the web server PARAMETER S httpc read bodv httpc read header httpc request httpc skip headers httpc use proxy Pointer to socket structure to use for connection TCP IP Manual Vol 2 rabbit com 297 httpc get int httpc get httpc Socket far s const char host word port const char far file const char far auth DESCRIPTION Connect to host and GET file using auth credentials PARAMETERS s Pointer to socket structure to use for connection host Hostname or dotted IP to connect to port Port to connect to typically 80 file Filename to request should start with auth Optional username and password separated with to authenticate with Use NULL for no credentials RETURN VALUE 0 Success NETERR_DNSERROR Can t resolve hostname EIO Unable to send request over socket E2BIG Buffer full trying to create HTTP request 298 rabbit com HTTP Client httpc get url int httpc get url httpc Socket far s const c
60. establish this sort of protection you need to set up a rule based access control This is done using the SSPEC_RULETABLE method or equivalent runtime control define SSPEC FLASHRULES use http lib SSPEC RULETABLE START SSPEC MM RULE A new newPages OxFFFF ADMIN GROUP SERVER HTTP SERVER AUTH NONE NULL SSPEC RULETABLE END The SSPEC FLASHRULES macro must be defined before you use http lib The rule table has one entry in this example The parameters to this entry are e A new this is the string prefix of all file names to which this rule applies In this example every thing in the first FAT partition A with a filename starting with new is protected according to the remaining parameters This includes any file in the root directory whose name starts with new or any file in any subdirectory of the root directory where the subdirectory name starts with new e newPages this is the realm string assigned to these files This is the same as the CGI realm but need not be e OxFFFF this is the user groups who are allowed read access In this case everyone is allowed e ADMIN GROUP this is the writable group only the one defined for the CGI is allowed e SERVER_HTTP only the HTTP server can access e SERVER AUTH NONE this is only relevant when the resource is being read directly by the client When the file is written via the CGI the CGI has already authenticated the user in its own
61. etc It is assumed that by the time this function is called the required drives and partitions have been mounted For example call fat EnumDrive followed by as many fat MountPartition calls as required The fat part pointer returned by fat MountPartition should be passed to this function Up to SSPEC MAX PARTITIONS can be registered This number can be changed indirectiv bv de fining SSPEC MAX FATDRIVES before use zserver lib This defaults to one drive and the number of partitions is set to 4 times this number hence the default allows up to four par titions NOTE It is NOT necessary to call this function if you called sspec automount SSPEC MOUNT FAT since that function does all the necessary initializations for a single drive PARAMETERS partno Partition number to register This starts at 0 corresponding to the A mount point 1 for B etc pt Pointer to fat_part data structure returned by fat MountPartition etc To unregister a partition pass NULL for this parameter Note attempted access to an unregistered partition generallv results in an error code of ENXIO RETURN VALUE 20 Success ENXIO partno outside the allowable range of 0 SSPEC MAX PARTITIONS 1 SEE ALSO fat EnumDrive fat EnumPartition fat MountPartition sspec automount sspec fatregistered 82 rabbit com Server Utilitv Librarv sspec fatregistered fat part sspec fatregistered int partno DESCRI
62. explicitly in it will have no access to the variable to which it applies Also the order of the groups is important if the all group is mentioned For example the line web foo foo gt 0 groups all ro admin gives read write access to the admin group But the line web foo foo gt 0 groups admin all ro limits the admin group to read only access To add a user to a group you must first add the user to the list kept by the server by calling sauth_adduser The value returned by sauth_adduser identifies a unique user This value is passed to sauth setusermask to set the groups that the user will be in For example id sauth adduser me please HTTP SERVER sauth_setusermask id admin users NULL The user me is now in both the admin group and the users group The groups determine what server resources the user can access The user information only determines what username and password must be provided for the user to gain access to that group s resources The web server has no concept of which variables are located on which forms By allowing certain vari ables to be available to certain user groups it doesn t matter which variables are located on which forms any user can update variables through any POST capable resource as long as a group the user is a member of has access to that variable It may also be important to update certain variables only through certain authentication metho
63. files functions and variables to references to memory objects HTTP NO FLASHSPEC Define if there is to be NO static resource table that is all resources are in the dynamic RAM table or in the filesystem s If you define this then there is no point in using the SSPEC RESOURCE series of macros below SSPEC RESOURCETABLE START SSPEC RESOURCE ROOTFILE name addr len SSPEC RESOURCE XMEMFILE name addr SSPEC RESOURCE ZMEMFILE name addr SSPEC RESOURCE FSFILE name fnum SSPEC RESOURCE ROOTVAR name addr type format SSPEC RESOURCE XMEMVAR name addr type format SSPEC RESOURCE FUNCTION name addr SSPEC RESOURCE CGI name addr SSPEC RESOURCE P ROOTFILE name addr len realm rg wg sm meth SSPEC RESOURCE P XMEMFILE name addr realm rg wg sm meth SSPEC RESOURCE P ZMEMFILE name addr realm rg wg sm meth SSPEC RESOURCE P FSFILE name fnum realm rg wg sm meth SSPEC RESOURCE P ROOTVAR name addr type format realm rg wg sm meth SSPEC RESOURCE P XMEMVAR name addr type format realm rg wg sm meth SSPEC RESOURCE P FUNCTION name addr realm rg wg sm meth SSPEC RESOURCE P CGI name addr realm rg wg sm meth SSPEC RESOURCETABLE END These macros are used to initialize the static resource table Prior to Dynamic C 8 50 this had to be done by explicitly using C language initialization of a table declared as const HttpSpec http spec These macros perform the same function It is recomm
64. functions con backup does not take a parameter and it returns 0 if the backup was successful and 1 if it was not This function is called by sev eral of the Zconsole command functions that change configuration parameters or that add or delete files or variables from the file system Caution is advised when calling con backup since it writes to flash memory 14 7 1 Data Structure for Backup System The developer must define an array called console backup of ConsoleBackup structures typedef struct void data int len void postload void presave ConsoleBackup data This is a pointer to the data to be backed up len This is how many bytes of data need to be backed up postload This is a function pointer to a function that is called after configuration data is loaded in case the devel oper needs to do something with the newlv loaded configuration data presave This is a function pointer that is called just before the configuration data is saved so that the developer can fill in the data structure to be saved The functions referenced by postload and presave should have the following prototvpe void mv preload void dataptr The dataptr parameter is the address of the configuration data the same as the data pointer in the ConsoleBackup structure 484 rabbit com General Purpose Console 14 7 2 Array Definition for Backup System const ConsoleBackup console backup CONSOLE BAS
65. gateway of the board A command that uses this function takes one parameter the new gateway in dotted quad notation e g 192 168 1 1 con_set_icmp_config This function configures an interface to use directed ICMP echo request ping packets for configuration A command that uses this function takes two parameters The first is on or off to turn this feature on or off The second parameter is optional and specifies the intended interface ETHO or ETH1 Only non PPPoE Ethernet may be used for ping configuration con_set_icmp_config_reset Normally when an interface has been configured via a directed ping packet further configuration via a directed ping packet is disabled until the next power cycle This function allows the interface to be con figured via a ping packet again A command that uses this function takes an optional interface argument ETHO or ETH1 466 rabbit com General Purpose Console con_set_ip This function changes the IP address of the board A command that uses this function takes one parameter the new IP address in dotted quad notation e g 192 168 1 112 con_set_param This function sets the parameter for the current I O device Depending on the I O device this value could be a baud rate a port number or a channel number A command that uses this function takes one parame ter the value for the I O device parameter con_set_mail_from This function sets the return address for all e mail mes
66. generating dynamic content SSI Server Side Includes is also a scripting language It is not nearly as easy to use SSI as it is to use Rabbit Web however an SSI can generate the same content as a RabbitWeb script It is just that you will need to write CGI functions and such functions can get large and complicated fairly quickly In fact SSI has the ability to invoke CGI functions whereas RabbitWeb does not In addition SSIs have the ability to include other resources directly in the primary returned resource much like how include works in ANSI C The server also communicates with lower layers in the diagram On the right hand side is the TCP IP block This is the pipeline to the outside world i e the browser Usually only the server needs to talk directly to TCP IP via a TCP socket Prior to Dynamic C 8 50 it was often necessary for the applica tion s CGI functions to call TCP IP functions This is no longer recommended Instead there are functions in the HTTP server that should be called to mediate all networking calls 2 3 4 Zserver Block Directly under the HTTP server block is the Zserver or resource manager block This is the central tele phone exchange of the entire application It controls access to many of the other blocks in the diagram In spite of its importance and central placing you do not usually need to be aware of its inner workings Zserver has applicability to other types of servers such as FTP because it
67. how long in seconds to try to send the e mail before timing out It defaults to 20 seconds define SMTP TIMEOUT 10 USE SMTP AUTH Define this macro to enable SMTP authentication 356 rabbit com SMTP Mail Client 10 5 API Functions The user callable functions described in this section are found in the Dynamic C library Lib tcpip smtp 1lib smtp data handler void smtp data_handler int dhnd void dhnd data word opts DESCRIPTION Sets a data handler for generating mail message content This function should be called after call ing smtp sendmail etc It overrides any message parameter set by the smtp sendmail call since the message is generated dynamically by the callback function Note you can use the same data handler as used for the FTP library see the ftp data handler description The flags values are numerically equivalent to those of the same meaning for ftp data handler The SMTP data handler is only used to gen erate data not receive it The handler is a function that must be coded according to the following prototype int my_handler char data int len longword offset int flags void dhnd_ data The data handler function must be called with the following parameters data Pointer to a data buffer len The length of the above data buffer This parameter is set to SMTP MAX DATALEN 256 by default You can override that macro to allow larger chunks offset The byte number
68. in a DOS FAT file e SSPEC FILE The data resides ina file generic type returned by sspec_gettype e SSPEC ROOTVAR The data is a variable in root memory for HTTP 38 rabbit com Server Utility Library e SSPEC XMEMVAR The data is a variable in xmem for HTTP e SSPEC VARIABLE The data is a variable for HTTP generic type returned by sspec gettvpe e SSPEC FUNCTION The data is a function for HTTP e SSPEC FORM A setof modifiable variables e SSPEC CGI The data is a CGI function for HTTP new style CGIs with better interface e SSPEC LINK Symbolic link alias to another resource name e SSPEC HARDLINK Symbolic link alias to another resource table entry 3 2 2 ServerSpec Vartype Field If the object is a variable then this field will tell you what type of variable it is INT8 INT16 INT32 PTR16 FLOAT32 3 2 3 ServerPermissions Servermask Field The type of server HTTP and or FTP that has access to a particular resource is determined by the servermask field in the ServerPermissions structure e SERVER_HTTP Web server e SERVER_FTP File transfer server e SERVER_SMTP Mail server e SERVER_HTTPS Secure web server e SERVER_SNMP SNMP agent e SERVER USER Placeholder for first user defined server e SERVER_USER2 Placeholder for second user defined server etc grow down e SERVER ANY Any server May be passed in most cases when any server will do 3 2 4 Configuration Macros
69. int sspec DESCRIPTION Returns the kind of variable represented by sspec PARAMETERS sspec spec index RETURN VALUE O Failure On success returns one of e INTS8 single character e INT16 2 byte integer e PIRIG string in root memory e INT32 4 byte long integer e FLOAT32 floating point variable SEE ALSO sspec getvaraddr sspec getvartype sspec gettype sspec getvartvpe word sspec getvartype int sspec DESCRIPTION Gets the tvpe of variable represented bv the spec index PARAMETERS sspec spec index RETURN VALUE SSPEC ERROR Failure SSPEC ROOTVAR or SSPEC XMEMVAR Success SEE ALSO sspec getvaraddr sspec getvarkind sspec gettvpe TCP IP Manual Vol 2 rabbit com 103 sspec getxvaraddr long sspec getxvaraddr int sspec DESCRIPTION Returns a pointer to the variable in xmem represented by the sspec index PARAMETER sspec spec index RETURN VALUE 2 0 Variable pointer 1 Failure SEE ALSO sspec readvariable sspec mkdir int sspec mkdir char name ServerContext context DESCRIPTION Create a named directory in the FAT filesystem PARAMETERS name Name of new directory context Current server context RETURN VALUE 0 OK EPERM Not a filesystem that supports creation of new directories EACCES Not authorized Any other negative values indicate an error SEE ALSO sspec delete sspec rmdir sspec open 104 rabbit com Server Uti
70. is IF DEFAULT SNMP TOS Specifies the IP TOS for SNMP The default is IPTOS RELIABLE SNMP MIN TRAP INTVL Minimum interval between transmission of trap messages specified in milliseconds Helps pre vent inadvertent network overload Must not be more than 30 000 milliseconds The default is 1000 ms 390 rabbit com SNMP SNMP MAX MONITOR Maximum number of monitored variables Each monitored variable requires SNMP MAX MON DATA 2 33 bytes of root data SNMP MAX MON DATA Maximum number of additional variables sent with a monitor trap The default is 2 SNMP MAX DATA Largest size of SNMP datagram supported input or output This must be at least 484 bytes to conform with RFC1157 Currently this should not be larger than the default value since outgoing fragmentation is not supported The default value is MIN_MTU 28 SNMP MAX NAME Maximum size of an encoded object identifier OID The default is 32 SNMP MAX STRING The largest octet string that may be retrieved or set via SNMP Making this larger only affects the amount of stack space used by the SNMP handler functions It does not limit internal storage of string values in the MIB tree The largest practical size would be a few bytes less than SNMP MAX DATA The minimum allowable size is 2 SNMP_MAX NAME The default is 128 SNMP MAX BINDINGS The maximum number of variables supported in any one message This has a bearing on stack space usage Each additional binding w
71. is necessary for CGI functions whether or not they were written prior to Dynamic C 8 50 Some of the fields are off limits to developers The field that are available for use are described in the next section Historical note prior to Dynamic C 8 50 it was sometimes necessary for CGI functions to access directly the fields of this structure New programs should not directly access the fields since it reduces the chance of upward compatibility There is a new suite of macros see http getAction and related macros that should be used instead Where applicable the equivalent macro is documented with the field Some fields do not have an equivalent macro such as the cookie field for now use read only access to such fields A pointer to Ht tpState is the first and only parameter to all CGI functions Most of the time this pointer should be passed on to other HTTP library functions Note that the Ht tpState structure is only valid within a CGI function that has been called from the HTTP server Outside of this for example in your main function none of the fields are guaranteed to be meaningful or consistent 4 1 1 1 HttpState Fields The fields discussed here are available for developers to use in their CGI functions s This is the socket associated with the given HTTP server A developer can use this in a CGI function to output dynamic data although there are better safer ways of doing this see the section on Writing a CGI F
72. it If the data cannot be sent for example because the socket transmit buffer is already full then a special return code indicates that the CGI should try again on the next call Often the CGI itself will not need to write anything to the client the http_switchcCGI function takes care of most needs If this function is used then the CGI is responsible for gener ating the correct HTTP response including headers and http _switchCGI and similar functions should NOT be called Use of this function can often be avoided Instead the CGI can copy a string to the pointer pro vided by http_getData then return CGI_ SEND This will cause the server to send out the null terminated string in the buffer and not call the CGI until the string is sent to the client See the source to http defaultCGI for an example of this method PARAMETERS state HTTP state pointer as provided to the CGI function data Pointer to first char to transmit It is OK to make this the same pointer that was returned by http getData since that buffer can be used for out put as well as input In any case the CGI must ensure that it has processed any incoming data before writing new data to that buffer length Length of data to transmit There is a limit to the amount of data that http write can write on any given call This limit is set by the HTTP server socket transmit buffer size This buffer size is given by TCP BUF SIZE 2 The transmit buffer is us
73. it is assumed to be the name of a resource which is to be created if it does not already exist and overwritten with the uploaded file contents There are three steps required to use this CGI 1 Define a CGI resource in the flash or ram spec table If using flashspec for example there would be an entry like SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE index html index html SSPEC RESOURCE CGI upload cgi http defaultcCGI SSPEC RESOURCETABLE END There may be other resources but at least two are normally required One resource is a web page see below that contains a form the user can fill in with the name of the file to upload The other resource CGT is a reference to this function giving ita URL name that identifies it to the browser 2 Create a web page which contains a form like the following skeleton example lt FORM ACTION upload cgi METHOD POST enctype multipart form data gt lt INPUT TYPE FILE NAME A incoming new htm gt lt INPUT TYPE SUBMIT VALUE Upload gt lt FORM gt in the lt FORM gt element the ACTION parameter specifies the URL assigned to this CGI In the lt INPUT TYPE FILE gt element the NAME parameter specifies the resource name used to contain the uploaded file contents In this example the resource is called A incoming new htm which will work if you are using the FAT filesystem If uploading to a subdirectory incoming in the above example the subdire
74. let the library handle writing it to the network PARAMETERS state Current server struct as received by the CGI function str String to send RETURN VALUE None sets the state so the CGI must immediately return with a value of 0 LIBRARY HTTP LIB SEE ALSO cgi_redirectto 188 rabbit com HTTP Server http _abortcCGI int http _abortCGI HttpState state DESCRIPTION Terminate this CGI request The client will receive an error message indicating the connection was closed The CGI should not make any further HTTP calls after calling this function It should clean up any resources that it opened since no further calls are made to this CGI for this request PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE 0 LIBRARY HTTP LIB SEE ALSO http_getAction http_skipCGI http_switchCGI http_finishCGI http_write TCP IP Manual Vol 2 rabbit com 189 http addfile int http addfile char name long location DESCRIPTION Adds a file to the dvnamic resource table PARAMETERS name Name of the file for example index html location Address of the file data Return value from ximport RETURN VALUE 0 Success 1 Failure LIBRARV HTTP LIB SEE ALSO http delfile 190 rabbit com HTTP Server http contentencode char http contentencode char dest const char src int len DESCRIPTION Converts a string to inc
75. lt 4 SNMP_P_INTEGER lt lt 4 SNMP P OCTETSTR lt lt 4 SNMP_P_OCTETSTR lt lt 4 SNMP P OCTETSTR lt lt 4 SNMP P IPADDRecA SNMP_P_TPADDR lt lt 4 SNMP_P_COUNTER lt lt 4 SNMP_P_COUNTER lt lt 4 SNMP_P_GAUGE lt lt 4 SNMP_P_GAUGE lt lt 4 SNMP GAUGE AS LONG SNMP_INTEGER_AS LONG SNMP_OCTETSTR_NULLTERM SNMP SHORT SNMP_LONG SNMP_OCT SNMP STR SNMP_FOCT SNMP P OID lt lt 4 SNMP OTD SNMP_FOCT SNMP_LONG SNMP_ SHORT SNMP LONG SNMP COUNTER AS LONG SNMP SHORT SNMP LONG SNMP P TIMETICKS lt lt 4 SNMP LONG 394 rabbit com SNMP maxlen RETURN VALUE snmp add continued Pointer to the actual object in root data storage This storage becomes man aged by SNMP MIB which is why it must be static To alter the value of the object it is permissible in fact recommended to simplv update the object directly Note that it is this pointer value that is stored in the MIB tree nota copy of the object Note that variable length octet strings are stored in a spe cial format the 1st two bytes of the location are used to store the current length The specified maximum length maxlen includes the length of this 2 byte prefix The actual length of the object can thus be no more than the maxlen 2 Maximum permissible length of the object This is applicable to variable length objects since SNMP needs to know the allowable size bounds for the objec
76. mn 239 FTP Client http sock xfastwrite mm 239 ftp client filesize mn 317 http switchCGI ee 242 ftp client setup sen 314 http WIE ii ke re e e 244 ftp client setup url L 315 Console ftp client tiek L 316 con backup em neneenennznnanzznnnna 476 Ftp chent X ET sissa kiber ferti reirei 317 con backup DVtes Lee 476 ftp data handler mn 318 con backup Teserve ve eeennn 477 ftp TASES COME siririca tesisse 319 con chk timeout ss sseeeenenezzennzzzzn 477 FTP Server con load backup nsss 478 A 336 Gon TES CELIO i a a a eiri 478 ftp set anONVMOUS Lee 339 con set backup IX Lee 479 ftp shutdown nee 340 conset files IR ssmisiseiiunieni ini eee jeb 479 ftp CK iii iet apert 340 con set timeout 6 eeeeeeenenenzenenzenn 480 HTML Forms con set user idle ss eenenennenennnnn 480 http finderrbuf nn 195 con set user timeout sssseeeeenennenzennnz 481 http nextfVverr mensa 220 CONSOLE AMIE iss a iinis 475 http parseform 0 00 ena 221 console tiek nn eeeeenenenennenenzenn 475 http scanpost e eneenennennnnzna 223 Cookie sspec addfV i rei do eroj 63 http SetCookie sioiias 227 sspec TNIV srir Vecviscavesvetervencoteteotesieece 84 Data Conversion sspec_getformtitle L nn 89 http contentencode m mn 191 Sspec_getfVdese oo eee eee 90 hitp date SUL susieina 192 sspec_getfventrytype even 91 http_urldecode oe nn 243 sspec_getfylen s sssisseenszesreszinntosijosieszezttji 92 Di
77. more headers or incomplete header read from socket NETERR REMOTE RESET connection closed before end of headers EEOF socket is not readable EXAMPLE do retval httpc read header amp hsock buffer sizeof buffer 1 while hsock status HTTPC STATE HEADER 308 rabbit com HTTP Client httpc request int httpc request char buffer int bufsize const char far method const char far host word port const char far file const char far auth DESCRIPTION Generate HTTP headers to request a file from an HTTP server PARAMETERS buffer Pointer to socket structure to use for connection bufsize Length of buffer for storing header method Method typically GET POST or maybe HEAD host Hostname or dotted IP to connect to port Port to connect to or 0 for default 80 Only used with proxy servers ig nored otherwise file Filename to request must start with auth Optional username and password separated with to authenticate with Use NULL for no credentials RETURN VALUE Number of bytes written to buffer Caller can add additional headers but must append r n CRLF before sending E2BIG request would overflow buffer SEE ALSO hittpe et hbepe et url httpe post url httpe post httpc post ext TCP IP Manual Vol 2 rabbit com 309 httpc skip headers int httpc skip headers httpc Socket far ts DESCRIPTION Skip through the headers to get to the body of the HTTP response Blocks
78. namespace as a C variable web update statement gt web update variable list function spec variable list gt variable variable list function spec is the name of a previously declared C function 288 rabbit com RabbitWeb 5 5 2 Configuration Macros There are several macros that can be used when setting up a RabbitWeb server USE RABBITWEB Define to 1 to enable the HTTP extensions including the ZHTML scripting language Defaults to 0 RWEB POST MAXBUFFER This defines the size of a buffer that is created in xmem This buffer stores POST requests that contain variable updates Hence this macro limits the size of POST requests that can be processed Defaults to 2048 RWEB POST MAXVARS This macro defines the maximum number of variables that can be processed in a single POST request That is it limits the number of variables that can be updated in a single request Each variable requires 20 bytes of root memory for bookkeeping information so the total memory usage is 20 RWEB POST MAXVARS Defaults to 64 RWEB ZHTML MAXBLOCKS This macro determines the number of if and for blocks that can be nested in ZHTML Each additional block allowed adds 11 bytes for each HTTP server instance defined by HTTP MAXSERVERS Defaults to 4 RWEB ZHTML MAXVARLEN This defines the size of a root buffer in bytes that is used to store variable names and values and hence limits the maximum length of a variable name or value Only str
79. not exist SEE ALSO sspec mkdir sspec rmdir sspec open 78 rabbit com Server Utility Library sspec dirlist int sspec dirlist int item char line int linelen ServerContext context word options DESCRIPTION Return formatted directory listing line To use this function call it with item O the first time then keep calling it with item lt previous return value gt until it returns negative This allows you to iterate through all entries in a directory The ServerContext structure contains the current user ID server and the name of the direc tory to list Note For a given directory you should call this function with item 0 followed by more calls until it returns 1 If you want to terminate the directory listing without iterating through every en try pass the SSPEC_LIST_END option flag see below This allows Zserver to release any tem porary resources acquired for the purpose of iterating through the directory This is especially important for FAT filesystem listings After this function returns negative you must start the next directory listing from the top that is item 0 If you do not complete the listing then your application may not be able to perform further listings owing to internal resource leakage This is similar to the need to close file resources that are opened See the second example below Pass the same ServerContext structure for the entire directory list sequence since Zserver kee
80. of the value s is always assumed to point to an area of storage of the required length See snmp set int for other general considerations PARAMETERS p Parameter structure that was previously initialized by calls to snmp init parms snmp set stem etc s New value for the object RETURN VALUE NULL if p was NULL or if there is no object with the given OID or if the object was not stored with foct internal type Otherwise returns p LIBRARY MIB LIB SEE ALSO snmp init parms snmp set stem snmp append stem snmp get indexed snmp get snmp add snmp xadd snmp set int snmp set long snmp set oct snmp set str snmp set objectID 430 rabbit com SNMP snmp set int snmp parms snmp set int snmp parms p int i DESCRIPTION Set the value of a short integer object The OID of the object must be set in p If the object is not in fact a short integer then NULL will be returned and there will be no alteration of the value The object may reside in either root or xmem data space This function only needs to be called when the address of the object itself is not known Typically this would be in functions which perform general processing of MIB objects If the address of the object is known it is far more efficient to update the object directly PARAMETERS p Parameter structure that was previously initialized by calls to snmp init parms snmp set stem etc i New value for the object RETURN VALUE NUL
81. of bytes of data following the initial header Content Type multipart form data boundary 3vAL1QsFOUg2GsY3p6n3YQ The multipart form data type indicates that this is a multipart form data submission The boundary parameter specifies a unique character sequence that separates each part The boundary is deliberately chosen as a long random string of characters so that it is unlikely to be confused with the actual data content The above blank line is significant it indicates the end of the initial header lines and the start of data 3vAL1Q0sFOUg2GSY3p6n3YQ This is the first boundary Boundary strings are always prefixed by an additional sequence The following lines are header lines for the individual part The actual data follows the first empty line Content Disposition form data name A new htm filename test txt The Content Disposition header indicates the presentation of the data The only type which is relevant is form data The name parameter indicates the field name which was originally part of the name parameter of the lt input gt element The filename parameter is only set if this is an uploaded file It gives the name of the file on the remote client side This is not usually relevant to the server The name of the file as it is stored on the server is not specified since the browser does not know it or have control over where the file is stored We are using the convention that the field name indicates the lo
82. of creating the MIME type mapping table is new with Dynamic C version 8 5 TCP IP Manual Vol 2 rabbit com 181 Step 9 Rule Creation There must be rules to limit the upload facility to select user groups This access control adds security to the system by disallowing unauthorized tampering This is done be assigning a unique user or user group the privilege of uploading new files All other users will be permitted only read access To do this there are several things that need to be coordinated First the user s need to be created and assigned the correct group bit which defines the upload privilege Then the CGI and the file system need to be protected so that only the privileged group can use the CGI and only the privileged group can write to a defined subset of the file system Let s take this step by step In the main program define a group bit to represent the privileged user s define ADMIN GROUP 0x0002 Groups are assigned one bit out of 16 In this case we select bit 1 Bit 0 or 0x0001 will be used for all other users Next augment the resource table so that the CGI is accessible only to users in ADMIN GROUP SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE index html index html SSPEC RESOURCE P CGI upload cgi mv CGI newPages ADMIN GROUP 0x0000 SERVER HTTP SERVER AUTH BASIC SSPEC RESOURCETABLE END The SSPEC RESOURCE P CGI isa macro that allows specification of access control parameters
83. of the HTTP server the larger the buffer up to a point the faster the server will run The buffer size is also important for use in CGI functions because it is a work space the programmer can use HTTP_MAXBUFFER must be at least 180 bytes for CGI functionality HTTP MAX COND Support for conditional SSI error feedback etc It defaults to 4 This is the maximum number of state variables that may be accessed using the http_getCond orhttp setCond macros HTTP MAX NONCES This macro is used when USE HTTP DIGEST AUTHENTICATION is set to one Defined to 5 by default it specifies the number of nonces the HTTP server will allow as valid at any one time This value should be somewhat larger than the maximum number of clients expected to be access ing the server simultaneously Otherwise performance could suffer as clients are forced to retry authorization in order to acquire a fresh nonce HTTP MAXSERVERS This is the maximum number of HTTP servers listening on port 80 The default is 2 You may increase this value to the maximum number of independent entities on your page For example for a Web page with four pictures two of which are the same set HTTP MAXSERVERS to 4 one for the page one for the duplicate images and one for each of the other two images By default each server takes 2500 bytes of RAM This RAM usage can be changed by the macro SOCK BUF SIZE ortcp MaxBufSize which is deprecated as of Dynamic C ver 6 57 Another op
84. of the user groups is to protect directories and variables from unauthorized access User groups are fullv described in Section 5 2 3 int hum web hum groups all ro This declares a variable named hum of tvpe integer using normal Dvnamic C svntax It will be used to store the current humidity reported by the humidity detector The web expression registers this C vari able with the web server The read only attribute is assigned by the groups all ro part which gives read only access to this variable to all user groups More information on registering variables is given in Section 5 2 1 int hum_alarm web hum_alarm O lt Shum_alarm amp amp hum alarm lt 100 groups all ro admin This code creates a variable called hum_alarm to indicate the level at which the device should send an alarm Unlike the web statement for hum there is a guard added when hum_alarmis registered A guard is an error checking expression used to evaluate the validity of submissions for its variable The guard given for hum alarm ensures only the range of values from 1 to 100 inclusive are accepted for this variable More information on the syntax of the error checking expression is in Section 5 2 2 The way error information is used in the HTML form is described in Section 5 3 5 The dollar sign symbol in hum_alarm specifies the latest submitted value of the variable not necessar ily the latest committed value of the variab
85. open on each of them LIBRARV zconsole lib 478 rabbit com General Purpose Console con set backup 1x void con set backup 1x FSLXnum backuplx DESCRIPTION Sets the logical extent LX that will be used to store the backup configuration data For more information on the file system see the Dynamic C User s Manual This is only useful in conjunction with FS2 LIB This should be called once before console init Care should be taken that enough space is avail able in this logical extent for the configuration files See con backup bvtes for more information PARAMETER backuplx LX number to use for backup LIBRARV zconsole lib SEE ALSO con set files 1x con backup bvtes con set files 1x void con set files 1x FSLXnum filesix DESCRIPTION Sets the logical extent LX that will be used to store files For more information on the file svstem see the Dynamic C User s Manual This is only useful in conjunction with FS2 LIB This should be called once before console init PARAMETER fileslx LX number to use for files LIBRARY zconsole lib SEE ALSO con set backup lx TCP IP Manual Vol 2 rabbit com 479 con set_user idle void con set user idle void funcptr DESCRIPTION Sets a user defined function that will be called when the console for a particular I O channel is idle The user defined function should take an argument of type ConsoleState LIBRARY zcons
86. option list with a form variable The third parameter gives the developer defined option array and the fourth parameter gives the length of the array The form variable can now only take on values listed in the option list sspec setfvoptlist form var fail options 4 This function sets the tvpe of form element that is used to represent the variable The default is HTML FORM TEXT which is a standard text entry box This line sets the type to HTML FORM PULLDOWN which is a pull down menu sspec setfventrvtvpe form var HTML FORM PULLDOWN Finally this code sets up the last variable Note that it is a float so F LOAT32 is given in the sspec addvariable call The last function call is sspec setfvfloatrange instead of sspec setfvrange since this is a floating point variable 162 rabbit com HTTP Server var sspec_addvariable humidity amp humidity FLOAT32 ME es Oana SERVER_HTTP 8 var sspec addfv form var sspec setfvname form var Humidity sspec setfvdesc form var Target humidity between 0 0 and 1 0 SSOSC_sSecivilea term var B sspec setfvfloatrange form var 0 0 1 0 These calls create aliases in the dvnamic resource table for the HTML form That is the same form can now be generated by requesting index html or 7 7 Note that sspec aliasspec should be called after the form has already been set up The aliasing is done by creating a new entry in the resource table and c
87. port Port to connect to or O for default port 80 RETURN VALUE 0 Success NETERR_DNSERROR Cannot resolve hostname NETERR NOHOST ARP Local host or gateway unreachable EXAMPLE httpc open amp hsock 192 168 1 1 80 TCP IP Manual Vol 2 rabbit com 303 httpc post int httpc post httpc Socket far s const char host word port const char file const char auth const char far postdata DESCRIPTION Connect to host and POST postdata to file using auth credentials PARAMETERS s Pointer to socket structure to use for connection host Hostname or dotted IP to connect to port Port to connect to typically 80 file Filename to request should start with auth Optional username and password separated with to authenticate with or NULL for no authentication postdata Data to post already URL encoded and null terminated RETURN VALUE 0 Success NETERR_DNSERROR Can t resolve hostname SEE ALSO httpc post_url httpc_post_ext 304 rabbit com HTTP Client httpc post ext int httpc post ext httpc Socket far s const char host word port const char file const char auth const char far postdata word postlen const char contenttype DESCRIPTION Connect to host on port and POST postlen bytes from postdata to file using auth credentials PARAMETERS s Pointer to socket structure to use for connection host Hostname or dotte
88. provided by the user The function returns 1 on error and the number of bytes in the header on success The second function http xgetheader simply returns a long pointer into the internal header buffer for the given header It returns 1 on error and the number of bytes in the header on success Note that some headers are saved by the HTTP server by default into the HTTP state structure such as Content Length We will also begin saving the Host header which is useful in performing CGI redi rection Hence we can change the semantics of the cgi_redirectto function int cgi redirectto HttpState state char url j such that the url parameter no longer needs to be an absolute URL 144 rabbit com HTTP Server 4 3 Authentication Methods HTTP 1 0 Basic Authentication is used by default This scheme is not a secure method of user authentica tion across an insecure network e g the Internet HTTP 1 0 does not however prevent additional authentication schemes and encryption mechanisms from being employed to increase security Starting with Dynamic C version 8 01 HTTP Digest Authentication as specified in RFC 2617 is sup ported Instead of sending the password in cleartext as is done using Basic Authentication MDS is used to perform a cryptographic hash In general adding a query string to the end of a GET request is poorly supported by digest authentication Users should be aware that older browsers e g IE6
89. provides a consistent interface to the various different types of resource As indicated in the diagram Zserver is architected as a resource manager and a virtual filesystem The virtual filesystem is basically a notational convenience for accessing all resources using a uniform naming scheme The external appearance of the virtual filesystem is mod elled on the Unix approach In Unix all storage devices and the filesystems contained therein are accessed from a single starting point known as the root directory written as a single slash character Under the root directory may be any number of files and directories Some of these directories may actu ally refer to a completely different device and filesystem The term for such directory entries is mount point Note the distinction between this naming convention and the one used by PC DOS and similar operating systems In DOS you have to explicitly indicate the device by prefixing the file name For example C index htm and A index htm are different files on different devices On Unix you create two mount points in the root directory backup and production for example Then the above mentioned files are known as backup index htm and production index htm This may seem like a fine distinction however it TCP IP Manual Vol 2 rabbit com 9 matches better with the naming convention used by HTTP i e the URL It also offers greater flexibility with regards to naming devices Zser
90. red green 10 This causes blue to be 5 red to be 6 and green to be 10 Unlike an enum a selection type variable can be of type long as well as int 5 2 2 Web Guards Registering variables arrays and structures with the server is not enough when data is received from the user it should be checked for errors before being committed to the actual C variables The web syntax allows an optional expression to be added that is evaluated when the user submits a new value for that variable int foo web foo sfoo gt 0 amp amp foo lt 16 If the C expression evaluates to TRUE i e 10 the new value is accepted If it evaluates to FALSE i e 0 the new value is rejected The new values are not applied until all variables in a submission have been checked 260 rabbit com RabbitWeb To reference the old committed and therefore guaranteed correct value reference the variable directly int foo web foo 0 lt foo amp amp foo lt foo One variable can reference another variable in an error checking expression int low int high web low web high Shigh gt Slow web low Slow c high Notice that the variable 1 ow is registered with the web server before it is used in the error checking expression for the variable high This ordering lets the guard for high know that low is a web variable Arravs also need to be considered when doing error checking The char
91. relative to the first byte of the entire message stream This is useful for data handler functions that do not wish to keep track of the cur rent state of the data source flags Contains an indicator of the current operation SMTPDH_OUT data is to be filled with the next data to send to the mail server The maximum allowable chunk of data is specified by len The data must not contain the sequence lt CRLF gt lt CRLF gt since that will confuse the process SMTPDH_ABORT end of data error encountered during SMTP operation The mail was prob ably not delivered dhnd data The pointer that was passed to ftp data handler TCP IP Manual Vol 2 rabbit com 357 PARAMETERS dhnd Pointer to data handler function or NULL to remove the current data han dler dhnd data A pointer that is passed to the data handler function This may be used to point to any further data required by the data handler such as an open file de scriptor opts Options word currently reserved set to zero RETURN VALUE The return value from this function should be the actual number of bytes placed in the data buffer or 1 to abort If 0 is returned then this is considered to be the end of data You can write up to and including len bytes into the buffer but at least one byte must be written otherwise it is assumed that no more data is following For SMTPDH_ABORT the return code is ignored SEE ALSO smtp sendmail smtp sendmailxmem smtp mailti
92. resources available to clients that is web browsers HTTP is implemented by HTTP LIB thus you need to write use http lib near the top of your program HTTP depends on the Dynamic C net working suite which is included in your program by writing use dcrtcp 1lib Setting up the network subsystem is a necessary pre requisite for use of HTTP This is described in the Dynamic C TCP IP User s Manual Vol 1 However it can be quite simple for test applications and sam ples to initialize the network subsystem In the file tcp config lib are predefined configurations that may be accessed by a define of the macro TCPCONFIG For instructions on how to set up different con figurations please see the Dynamic C TCP IP User s Manual Vol 1 or look in the file LIB TCPIP TCP_ CONFIG LIB HTTP makes use of the Zserver library to manage resources and access control The previous chapter dis cusses Zserver When reading this chapter on the HTTP server it will help if you are familiar with Zserver its interfaces and capabilities Much of this chapter contains material that could be considered advanced usage There is also some mate rial of a historical nature with relevant sections marked as such TCP IP Manual Vol 2 rabbit com 137 4 1 HTTP Server Data Structures The single data structure in HTTP LIB of interest to developers of CGI functions is discussed in this sec tion 4 1 1 HttpState Use of the Ht tpState structure
93. retain the html suffix The other reason for this relates to the way the HTTP server handles requests for a directory If given a URL of 7 the HTTP server will append index htm to determine the actual resource We take advantage of this default behavior so that this sample would work as expected 14 rabbit com Web Enabling Your Application mv io polling isa function that is part of the Application Specifics sub block As the name sug gests it is called regularly to poll some external device so as to keep the web variable up to date The implementation of the my io polling function is shown updating the web variable but we don t specify the actual I O reading function since that is too well application specific Now you may be wondering what this scripting language ZHTML looks like The following code shows the contents of themv app zhtml file lt HTML gt lt HEAD gt lt TITLE gt Web Variables lt TITLE gt lt HEAD gt lt BODY gt lt H1 gt Web Variables lt H1 gt lt P gt The current value of io state is lt z echo io state gt lt P gt lt BODY gt lt HTML gt This looks like plain HTML and it is with the only difference being the existence of special commands flanked by lt z and gt In this case the command simply echos the current value of the web variable that was registered The value binary in the global variable is converted to ASCII text by a default printf conve
94. snmp_append_Oid own 399 sspec getrealm oo eee enenennennni 99 snmp_append_parse_oid wn 400 sspec setpermissions mn 128 snmp_append_parse_stem u 401 sspec setrealm Lee 130 snmp append stem u 402 Resource Location and Information snmp communitv mask 2 403 sspec findfsname eee 86 snmp communitv NAME LL nn 404 sspec findname nn 85 SNMP_COPY_OId Lewn nennnnnnni 405 sspec findnextfile 2 sen 87 snmp delete en 406 sspec getfileloc over 88 snmp format Id L 407 sspec_getfiletype nn 89 SNMP et iss iii pie 408 sspec getfunction oe eenennnnn 90 snmp get indexed mn 409 sspec_getlength Les nee 95 snmp get nekt ranri 410 Sspe Setmame ii sisssiiniesiresjentonzezontesenzzzjni 97 snmp init Parms ewwa 411 sspec_getservermask s ss meeennenri 100 snmp_last_indeX L 412 SSpe gettype ii scessssesnevecceontcessecetersensots 100 somp dast int s s 2s0sseinesiiizzosusipnizzomesjenni 413 sspec getvaraddr sse 102 snmp last len nn 414 sspec getvarkind nn 103 snmp last long Lee 415 sspec getvartVvpe esssemseennnenneneznn 103 snmp last maxlen nn 416 sspec getxvaraddr Les 104 snmp last mem Lm 417 TCP IP Manual Vol 2 rabbit com 495 snmp_last_objectID nn 418 L snmp last snmp tVPE L 419 Snmp_last_tyPe usses 420 listing directory entries L 79 snmp last xmem 20 0 0 eeeennen 421 M snmp MONILOT oo eee eee nnenzznnnnnnn 422 snmp print tree Lu enenennnn 425 macros SNMp SEt ACCESS Liem
95. sspec setfvname int form int var char name DESCRIPTION Sets the name of a variable that is displayed in the HTML form PARAMETERS form spec index of the form var Index into the FormVar array of the variable name Display name of the variable RETURN VALUE 0 Success 1 Failure SEE ALSO sspec getfvname 124 rabbit com Server Utilitv Librarv sspec setfvoptlist int sspec setfvoptlist int form int var char list int listlen DESCRIPTION Sets an enumerated list of possible values for a string variable PARAMETERS form spec index of the form var Index into the FormVar array of the variable list Array of string values that the variable can assume listlen Length of the array RETURN VALUE 0 Success 1 Failure SEE ALSO sspec getfvopt sspec getfvoptlistlen sspec setfvfloatrange sspec setfvrange TCP IP Manual Vol 2 rabbit com 125 sspec setfvrange int sspec setfvrange int form int var long low long high DESCRIPTION Sets the range of an integer variable PARAMETERS form spec index of the form var Index into the FormVar array of the variable low Minimum value of the variable high Maximum value of the variable RETURN VALUE 0 Success 1 Failure SEE ALSO sspec_setfvfloatrange sspec_setfvoptlist 126 rabbit com Server Utility Library sspec setfvreadonly int sspec setfvreadonly int form int var int readonly DESCRIPTION
96. subject char body int len GLOBAL INIT n 1 if ml mum 4 ial dakbiieg printf RECEIVING MESSAGE lt d gt n n printf tFrom s n from primer Uero Be ial ic p 1 printf INtSubject s n subject printbt MSETDATAST sl n body Tert Op main static long address static int ret sock init Or pop3 init storemsg set up call back printf Resolving name n address resolve POP HOST prine Calling pops getmai ly 2 2 n pop3_getmail POP_USER POP PASS address Request to server primer YHimieewsing DODI CLE ooo NAT wairle ret pops cick POB DINIDINIG continue if ret POP SUCCESS printf POP was successful n if ret POP TIME printf POP timed out n if ret POP_ERROR printf POP returned a general error n prime VALL done n 370 rabbit com POP3 Client 11 5 1 Sample Conversation The following is an example POP3 session from the specification in RFC1939 For more information see www rfc editor org rfc std std53 txt In the following example lines starting with S are from the server and lines starting with C are from the client lt wait for connection on TCP port 110 gt lt open connections OK POP3 server ready lt 1896 697170952 dbc mtview ca us gt APOP mrose c4c9334bac560ecc979e58001b3e22fb HOK mrose s maildrop has 2 messages 320 octets STAT OK 2 320 L
97. systems for additional control and monitoring The console may also be used for configuration when a serial port is available HTML forms and the console are discussed in Chapter 4 and Chapter 14 respectively Multiple interfaces are supported starting with Dynamic C version 7 30 TCP IP Manual Vol 2 rabbit com 1 rabbit com Introduction RABE Tete 2 WEB ENABLING YOUR APPLICATION This chapter and the next three describe how to add web browser control to your application Web enabling is a logical and appealing choice for adding a user interface to your application since the neces sary hardware an Ethernet or serial port is available on all Rabbit core modules and SBCs Most users of your application will be familiar with at least one web browser Netscape Mozilla Internet Explorer Opera with its graphical user interface so they will be ready to start controlling your application with minimal training This chapter provides an overview of the steps you will need to take to web enable an application Knowl edge of browsers and something of their capability is assumed With this knowledge you can understand the concepts described in this chapter The following chapters go into more detail about the specific librar ies but for simple programs you may be able to use just the information in this chapter along with the sample code to write a working application Dynamic C provides libraries that implement most of
98. text of the cookie will be stored in state gt cookie This is a char and if no cookie was available then state gt cookie 0 will equal XO PARAMETERS buf Buffer to store cookie generation header that is the name of the cookie value Text to store in cookie generation header that is the value of the cookie LIBRARY HTTP LIB TCP IP Manual Vol 2 rabbit com 227 http set path int http set path char rootdir char dfltname DESCRIPTION Set the default root directory and resource name for all HTTP server instances In general this function should be called once only after http init but before http handler The root directory is the base directory and is used as a prefix for all resource requests from clients For example if the root directory is set to A then a client request for http lt hostname gt foo htm will look up the resource called A foo htm on this server The default resource name is used if the client s URL requests a directory For example if dfltname is set to index htm and rootdir is A then a client request for http lt hostname gt admin will look up the resource called A admin If that resource is actually a directory then it will look up a resource called A admin index htm If it is not a directory then the default name is not used PARAMETERS rootdir Root directory name to use This must be a null terminated string and MUST start and end with a forward s
99. that is allocated for each I O method This limits the length of a command line It is allocated in root data space Defaults to 128 bytes CON CMD DATA SIZE Default is 16 Adjusts the size of the user data area within the state structure so that user com mands may preserve arbitrary information across calls The user data area is allocated in root data space CON DHCP ACQUIRE RETRY TIMEOUT Defaults to 120 seconds If DHCP is enabled then Zconsole will maintain the DHCP lease This macro specifies the number of seconds after which a DHCP lease has been dropped that the board will attempt to reacquire the lease Note that in the normal course of operation a lease will never be dropped Generally that will only happen if the DHCP server is inoperable for an extended pe riod of time subject to the lengths of the leases that the DHCP server issues CON HELP VERSION This macro should be defined if the developer wants a version message to be displayed when the HELP command is issued with no parameters If this macro is defined then the macro CON VERSION MESSAGE must also be defined 486 rabbit com General Purpose Console CON INIT MESSAGE Defines the message that is displayed on all Zconsole I O methods upon startup Defaults to Con sole Ready r n CON MAIL BUF SIZE Maximum length of a mail message Defaults to 1024 CON MAIL FROM SIZE Maximum length of mail from address to NULL terminator Default to 51 CON MAIL SERV SI
100. the parameter structure in which case NULL is returned If p is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp set stem snmp set parse stem TCP IP Manual Vol 2 rabbit com 401 snmp append stem snmp parms snmp append stem snmp parms p word len char eos DESCRIPTION Appends the encoded object identifier string to the OID already set in p See snmp set stem fora description of OID encoding This function is identical except that it appends rather than replaces the OID PARAMETERS p Pointer to parameter structure to append to If NULL does nothing but re turn NULL len Length of eos eos Encoded OID string RETURN VALUE Returns p unless the OID string is too long to fit in the parameter structure in which case NULL is returned If p is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp set stem snmp append parse stem snmp append oid 402 rabbit com SNMP snmp community mask int snmp community mask word c index DESCRIPTION Return the community access mask of the specified community PARAMETERS c index Community table index This is the value returned by snmp add communitv ormav be SNMP PUBLIC SNMP PRIVATE or SNMP TRAPDEST for the predefined default com munities RETURN VALUE 1 The index was outside the table bounds 0 255 The requested bit mask LIBRA
101. the registered MIME type for HTML The next three lines starting with SSPEC_RESOURCETABLE START set up the static resource table Again this contains a single entry that associates the resource name hellowww html with the file that was ximported on the first line Note that the resource name suffix html matches the first parameter of the SSPEC_MIME entry Although not directly indicated on the diagram the other compile time initialization that is always required is the use of the appropriate libraries In this case the first three lines create a default TCP IP configuration TCPCONFIG 1 and bring in the networking and HTTP libraries Note that http lib automatically includes zserver lib Back in the Application block of the diagram we move right and consider the runtime initialization block This is contained in the main function sock init comes first to initialize the TCP IP network library and bring up the necessary interface s http init resets the HTTP library to a known state The last statement embodies the Main Loop sub block This is always required Typically only http handler needs to be called however your application can insert calls to its own polling and event handling code Since this is such a simple example there is not even any application specific code 12 rabbit com Web Enabling Your Application 2 5 A Simple but Realistic Application To turn the above toy example into something more
102. them with the new parameters void restart_serial int ex prime Uke starting Serna joe Eea e2s_state i close Close the serial port serial open i Open the serial port The function restart serial closes and then reopens the serial port specified by its parameter TCP IP Manual Vol 2 rabbit com 279 void update_serial void AMES salmi aL Check which serial port s changed ioe 2 07 1 a Gizer DOMES CONNIE 7 Wid if memcmp amp serial portslil ser amp serial ports copvlil ser sizeof serial ports i ser This serial port has changed so re open the serial port with the new parms Tescare Sera i Save the new parameters so we can check which one changed on the next update memcpy amp serial_ ports copvlil ser amp serial portslil ser sizeof serial portslil ser The function update serial is called when a serial port is updated via the HTML interface It determines which serial port s changed and then restarts them with the new parameters 280 rabbit com RabbitWeb void serial _ opem amie il Open the serial port e2s statelil open serial ports i ser baud Set the data bits i serial portelij ser dacabics 7 4 e2s_state i setdatabits PARAM 7BIT else e2s statelil setdatabits PARAM 8BIT Set the stop bits i erial portelij ser stoggoics 1 1E serial porte i ser parity 0 4 No parity e2s_state i s
103. then the cwd parameter indicates the current directory PARAMETERS name The file to open options File access options O RDONLX marks file as read only O WRONLY not currently supported by the default handler O_RDWR not used since it s not supported by the FTP protocol uid The userid of the currently logged in user cwd Current directory not currently supported by the default handler RETURN VALUE 20 File descriptor of the opened file FTP ERR NOTFOUND File not found FTP ERR NOTAUTH Unauthorized user FTP ERR BADMODE Requested option 2nd parameter is not supported FTP ERR UNAVAIL Resource temporarilv unavailable In the first case the returned value is passed to subsequent handler routines to identify the partic ular file or resource as the fd parameter If necessary you can use this number to index an array of any other state information needed to communicate with the other handlers The number re turned should be unique with respect to all other open resource instances so that your handler does not get confused if multiple FTP data transfers are active simultaneously Note that the given file name may be an absolute or relative path if the handler supports the concept of directories then it should handle the path name as appropriate and not just assume that the file is in the current di rectory If the filename is relative then the cwd parameter indicates the current directory TCP IP Manual
104. ue of this handler function is the number of seconds that have passed since January 1 1980 A return value of zero will cause the reply code 213 followed by a space and then the value 19800101000000 yyyymmddhhmmss to be sent by the server The FTP server assumes that this return value is in UTC Coordinated Universal Time If SEC_TIMER is running in local time the handler should make the necessary time zone adjust ment so that the return value is expressed in UTC The handler is only recognized if FTP EXTENSIONS is defined PARAMETERS fd File descriptor for the currently opened file RETURN VALUE The number of seconds that have passed since January 1 1980 The default handler always returns zero The number of seconds will be converted to a date and time value of the form yyyymmddh hmmss TCP IP Manual Vol 2 rabbit com 333 ftp dflt delete int ftp dflt delete char name int uid int cwd DESCRIPTION The default handler does not support the delete command It simply returns the error code for an unauthorized user The delete handler is only recognized by the server if FTP_ EXTENSIONS is defined It is called when the DELE command is received The given file name possibly relative to cwd should be deleted PARAMETERS name Pointer to the name of a file uid The currently logged in user cwd The current directory RETURN VALUE 0 File was successfully deleted FTP ERR NOTFOUND File not found FTP ERR
105. way and doesn t need to re authenticate In this example no authentication is required for retrieval read only of the file e NULL this is an additional parameter that is not relevant to this discussion By default every other file in the filesystem s that is not covered by this rule is denied write access In general a rule is only required when it is desired to permit write access not deny it 4 6 2 1 Step 10 Create Set of User IDs The last step is to actually define the users This must be done at runtime using the sauth_ func tions The following code illustrates int uid uid sauth adduser admin upload SERVER HTTP sauth setusermask uid ADMIN GROUP NULL sauth setwriteaccess uid SERVER HTTP This sets up a single user with userid admin and password upload The user is only known to the HTTP server sauth setusermask is required when a userid is created since the default may not be satisfactory It makes sure the user is placed into the correct group s in this case the ADMIN GROUP that we defined above Finally each user must be individually granted write access using the sauth setwriteaccess function If this is not done the user will not be able to write the file in spite of passing other tests TCP IP Manual Vol 2 rabbit com 183 Step 11 Tying It All Together After performing the above steps the actual running of the HTTP server and CGI is almost trivial
106. which obviates the need to manipulate these fields cond Support for conditional SSI error feedback etc New code should use the macros http_getCond and http setCond userdatall This field is included if HTTP USERDATA SIZE is defined It is an op tional user data area The area is cleared to zero when the structure is ini tialized otherwise it is not touched Its size must be greater than zero New code should use the http getUserData macro to obtain a pointer to user defined storage in this structure 4 2 Configuration Macros The following macros are specified in HTTP LIB Unless otherwise noted you can override the default values by defining the macro same name different value before you use http lib HTTP HOMEDIR Specify the home directory for the server This is the root directory to which all URLs are ap pended The default is which means that all resources are accessible If this is set to say ht docs then an incoming URL of foo bar html gets turned into htdocs foo bar html You can use this to restrict the HTTP server s access to all but a specific branch of resources Note the string value for this macro must start and end with a character HTTP DFLTFILE HTTP Specify the default file name to append to the URL if the URL refers to a directory This is only applicable if the URL is or is in a filesystem not the static or dyn
107. with that class giving equal access to all its members Considering the class i e group as the entity that is requesting a resource reduces the amount of infor mation that needs to be stored 8 rabbit com Web Enabling Your Application 2 3 3 HTTP Block Subcomponents The inner circles represent subcomponents of the server The first of these RabbitWeb was introduced in Dynamic C 8 50 RabbitWeb is an extension to C language syntax to simplify presentation of C language objects variables structures to a browser RabbitWeb allows you to write web pages in a special scripting language The script makes it easy to generate HTTP which is the format expected by the browser In addi tion the script allows the contents of your C language objects to be turned into HTML fragments for pre sentation by the browser See Chapter 5 for details about RabbitWeb The small block named web Variables between the Application block and the RabbitWeb circle indi cates that the web variables are the means of communication between your application and the server Since web variables are really just ordinary C variables arrays or structures they are extremely easy to manipulate by your application Since they also have the property of being registered with the web server the server has easy access too Registering an object with the web server is discussed in Chapter 5 The second circle in the HTTP server block represents the classic way of
108. with the use of print the value of the text fields are filled in by the server before the page is given to the browser Before the INPUT tag there is some code that displays text to describe the input field along with some error checking lt z if error ghum alarm gt lt FONT COLOR f 0000 gt lt Z RE Humidity alarm level percent lt z if error hum alarm gt lt FONT gt SRZ Re Instead of calling error with no parameters the variable whose input field we are considering is passed to error Used with an if statement this call to error lets us change the font color to red if the value for that variable was invalid in the last form submission Note that it is the text we have used to describe the web variable on the HTML page that is shown in red not the value of the web variable itself Also note that it is necessary to call error twice the second call is to close the FONT tag If in the last form submission the web variable had a valid value the code above will still display the descriptive text but its font color will not be changed If there were no errors with any of the web variables in the last form submission the page display reflects this status Figure 5 10 Web Page with No Error Message E Configure the humidity device Microsoft Internet Explorer File Edit View Favorites Tools Help ag ME a ala u g 1 Back bi Forward kl Stop Refresh Home Search Favorites History
109. z Resource Manager nerung Virtual File System 3 eee File Systems Static Dynamic Resource Resource FAT T Table Table l Met at Storage Program Second i Serial i Flash Flash RAM Flash 6 rabbit com Web Enabling Your Application 2 3 1 Application Block At the top of this diagram is a block called Application consisting of five sub blocks The Application block represents the code that you have to create Everything below this is provided by the libraries although you will need to specify some parts of the interface to these components This will be described in detail in the following sections The application block is subdivided into 5 parts 1 Compile time initialization This includes things like selection of the appropriate library modules ini tialization of static constant data structures and tables selecting default network configuration and inclusion of static resources external files via the ximport or zimport directives The arrows leading from the Compile Time Initialization sub block indicate the tables that may be set up at com pile time namely e The MIME type mapping table This mandatory table indicates to the browser how the content is to be presented to the user This is necessary for the browser and needs to be specified by the server however the server does not need to be particularly aware of the details e The rule table This is only necessary if a filesystem
110. z if auth Sfeo rw gt You have read write access to the variable foo lt z gt coy This function can be preceded by the not operator count This function is for arrays and selection type variables If the first parameter is an array the second parameter specifies an array dimension For a one dimensional array the second parameter must be zero For a two dimensional array the second parameter must be zero or one And so on If the first parameter is an array the return value of the function is the upper bound for the specified array dimension If the first parameter is a selection variable there is no second parameter The count function returns the number of options for a selection variable The return value of count can be used ina for loop to cycle through all elements of an array lt z for SA 0 A lt count foo 0 SA gt echo print These are display functions to make web variables visible on an HTML page They display the variable passed to them using a default conversion specifier The function echo is an alias for print lt zZ print foo gt error The error function can be called both with and without a parameter If it is called without a parameter it will return TRUE if there were any errors in the form submission and FALSE otherwise To call error with a parameter you must pass it the name of a web variable The function will return TR
111. 00 1 16 6 amp trapdest_ip SNMP TRAPDEST 30 2 trapindices See what we ve got snmp print tree printf MIB tree used 1d out of ld bytes n snmp used long SNMP MIB SIZE Now start up the network pock dmit TCP IP Manual Vol 2 rabbit com 389 The SNMP handler is called the same way all the other TCP IP handlers are called by tcp tick tt SET SHORT TIMEOUT 5000 for 77 4 if CHK SHORT TIMEOUT tt tifdef SEND TRAPS snmp trap trapdest ip SNMP TRAPDEST 20 2 trapindi ces tendif tt SET SHORT TIMEOUT 5000 tcp tick NULL The macros SET SHORT TIMEOUT and CHK SHORT TIMEOUT are defined in net lib They are based on MS TIMER and offer a consistent way of setting time outs of Ims thru 32 seconds using only 16 bit arithmetic This SNMP agent will send a trap message every 5 seconds 12 3 Configuration Macros These macros may be defined in the initialization code of the SNMP agent before the inclusion of dertcp lib SNMP DFLT READMASK The mask used to grant read access The default is 0x03 which gives read access to both the pri vate and public communities SNMP DFLT WRITEMASK The mask used to grant write access The default is 0x02 which gives write access to only the pri vate community SNMP INTERFACE Specify the network interface to listen for SNMP messages May be set to a fixed interface or IF_ANY to listen on all interfaces The default
112. 05 snmp delete snmp parms snmp delete snmp parms p DESCRIPTION Delete a node or a subtree of the MIB tree The object ID to delete is specified in p All objects whose OID has a complete initial match with the specified OID will be deleted Note that the indices which may have been retrieved for a deleted object will no longer be valid PARAMETERS p Pointer to parameter structure whose stem is set up with the OID to delete If NULL does nothing but return NULL RETURN VALUE Returns p unless it is NULL on entrv then nothing is done except to return NULL If no objects were deleted then the function also returns NULL LIBRARV MIB LIB SEE ALSO snmp init parms snmp set stem snmp set parse stem snmp append stem snmp_append parse stem snmp up stem snmp add snmp xadd snmp last index 406 rabbit com SNMP snmp format oid char snmp format oid snmp oid oid DESCRIPTION Debugging only format OID in dotted decimal and return static buffer PARAMETERS oid oid to format RETURN VALUE Address of string in static storage LIBRARY MIB LIB TCP IP Manual Vol 2 rabbit com 407 snmp get snmp parms snmp get snmp parms p DESCRIPTION Retrieves the object whose OID is set in p The retrieved object information is stored back in xp and can be examined using the snmp last series of functions PARAMETERS p Parameter structure that was previously initialized by calls to s
113. 2 rabbit com 67 sspec addvariable int sspec addvariable char name void variable word type char format word servermask DESCRIPTION Adds a variable to the dynamic resource table aka the RAM resource list Make sure that SSPEC MAXSPEC is large enough to hold this new spec entry This function is currently only useful for the HTTP server PARAMETERS name Name of the new variable This must be unique but this function does not check The name should not conflict with the virtual filesystem hierarchy That is it should not start with fs2 A B etc Variables appear in a directory listing of the root directory however they cannot be opened using sspec_open variable Address of actual variable type Variable type one of e INTS8 single character e INT16 2 byte integer e PIRIG string in root memory e INT32 4 byte long integer e FLOAT32 floating point variable format Output format of the variable as a printf conversion specifier e g d servermask Bitmask representing servers for which this function will be valid currently only useful with SERVER_HTTP RETURN VALUE 1 Failure 20 Success the index of the variable in the resource list SEE ALSO sspec addfsfile sspec addrootfile sspec addxmemfile sspec addxmemvar sspec addfunction sspec addform sspec aliasspec 68 rabbit com Server Utilitv Librarv sspec addxmemfile int sspec addxmemfile char name long fileloc
114. 3 6 1 RETURN VALUE Returns oid unless the OID string is too long to fit in the snmp oid structure in which case NULL is returned If oid is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp append oid snmp set parse stem snmp set stem 436 rabbit com SNMP snmp set parse stem snmp parms snmp set parse stem snmp parms p char name DESCRIPTION If p is not NULL set the OID stem in p to the OID expressed in dotted decimal notation in name This function is easier to use than snmp set stem but has the disadvantage of being less efficient Apart from the method of expressing the OID the semantics are identical to snmp set stem PARAMETERS p Pointer to parameter structure to set If NULL does nothing but return NULL name OID string in dotted decimal notation e g 43 6 1 RETURN VALUE Returns p unless the OID string is too long to fit in the parameter structure in which case NULL is returned If p is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp set stem snmp set parse oid TCP IP Manual Vol 2 rabbit com 437 snmp set stem snmp parms snmp set stem snmp parms p word len char eos DESCRIPTION If p is not NULL the OID stem is set to the encoded OID string specified by eos with length len eos must be a fully qualified OID encoded using the internal represe
115. 426 FTP server loo sse sessenenznnznnzznnnzznnzznnezzanannnnznnnza 322 snmp set callbaek 0 0 0 427 HTTP seryer a cisecrs iss her measte eeaee iis 141 snmp_set_COMMUMNILY Lumen 428 serial ports for telnet ss sseseeensenzenanezznnnznnza 450 snmp_set_dflt_communities 000 429 SMTP CHEM ik a A 356 snmp set fOCt Lee 430 telnet 7 05 and later ss ss seseseeeeneenezensenzzni 450 STUMP SU MG sikkina sissa 431 telnet pre 7 05 sensisset 455 snmp set long oo eects eee 432 ZCOMSOLES o ecesesseccecsessceceecsessceceecsesseececesenseeeeees 486 snmp_set_objectID sssssereemzzzzznnnnenzznnzzn 433 MIME A nni 32 148 SAMP Set OCt asorr 434 snmp set OiId Lewn 435 P snmp set parse Oid lower 436 simp Sel parE GT eenei 437 passive open srrennznznzzzinnnnznznzzttnnnznsnszznnnnnnnsstzzzn 321 Sp NEU STEHT nani 438 password protection sspesesnnznnesnennenennanzensas 46 54 l permissions Sa defaults oosssecsccssssssssssesssssssssecessssssssseseessseseeseee 40 sample NA i 440 POP BUFFER SIZE nccrne 365 ap mie BA ait cana cee dean 4A POP DEBUG llli seenssnenzznnznnnzznnannnnananannnannnn za 365 sittin tirnetiekk sade ari a IA a sate 441 POP NODELETE vcnos Wess i 365 POP_PARSE_EXTRA o ecceccccessecesseeseceseeeneeeens 365 samp trap sereine neriie rri eniris 442 snmp UNMONItOT Llum 443 POPS i Smp Old aretan 444 configuration eee ernnznenennnnnnnanznn enza 365 POST command sssrinin 155 snmp
116. Address of the IP address of the network management agent to which trap messages should be directed A pointer is used for this parameter to allow sharing the same destination address between multiple monitor calls The pointer must point to static storage Community table index This is the value returned by snmp add communitv ormav be SNMP TRAPDEST for the pre defined default trap destination communitv Trap number to use This must be 20 Negative numbers are reserved for SNMP predefined trap tvpes Otherwise generic traps are sent Number of MIB tree indices in the following list mav be zero This must be less than or equal SNOMP MAX BINDINGS Array of MIB tree indices Each element in this array is the MIB tree index of an object to send with the trap message Tree indices may be obtained us ing snmp_last_index and other MIB functions TCP IP Manual Vol 2 rabbit com 423 snmp monitor continued RETURN VALUE 1 Insufficient room in monitor table 2 Inappropriate object specified for monitoring i e it is not an integer type This will only be returned if SNMP_ DEBUG is defined otherwise the check is not performed 0 SNMP_MAX MONITOR 1 The monitor table index used for this object LIBRARY SNMP LIB SEE ALSO snmp unmonitor snmp trap 424 rabbit com SNMP snmp print tree void snmp print tree void DESCRIPTION Debugging function only Prints entire MIB tree Leaf nodes are printed
117. BUFSIZE define COUTBUFSIZE SEROUTBUFSIZE define DINBUFSIZE SERINBUFSIZE define DOUTBUFSIZE SEROUTBUFSIZE define EINBUFSIZE SERINBUFSIZE define EOUTBUFSIZE SEROUTBUFSIZE define FINBUFSIZE SERINBUFSIZE define FOUTBUFSIZE SEROUTBUFSIZE These set the receive and transmit buffer sizes for the serial ports In this example only serial ports E and F are being used but here as well as in the function e2s_ init code is included for all possible serial ports In this way it is relatively easy to change the serial ports being used simply by changing the character array ports config enum E2S INIT E2S LISTEN E2S PROCESS Ie These are symbols representing different states in the Ethernet to serial state machine TCP IP Manual Vol 2 rabbit com 277 struct int state Current state of the state machine tcp_Socket sock Socket associated with this serial port The following members are function pointers for accessing this serial port int open int close int read akae oyeee O A int setdatabits int setparity e2s state sizeof ports config The e2s state array of structures holds critical information for each socket serial port pair namely the socket structures that are used when calling TCP IP functions and the various serial port functions that access the serial ports or set serial port parameters The first member of the structure State is th
118. C printf specifier except that it is limited to a single variable varname function gt varname variable print opt function gt print opt variable number print opt variable loop variable print select function gt print select variable count expression gt count variable number count variable Note that in the first option variable is an array in the second option it is a selection type variable numeric expression gt loop variable integral variable count expression numeric literal integral variable refers to a registered web variable of integral int or long signed or unsigned type if statement gt if if expression html code if expression gt numeric expression operator numeric expression error variable auth variable group rights updating operator gt gt lt gt lt group rights gt ro rw for loop gt for loop variable numeric expression loop variable operator numeric expression loop variable for inc html code for inc gt numeric expression numeric expression ro stands for read only rw stands for write only TCP IP Manual Vol 2 rabbit com 291 5 5 5 RabbitWeb Functions This section lists all of the functions that can be called within ZHTML tags auth This function is used to check if a user has authorization for accessing a specific variable lt
119. CII mode a blank line is waiting to be read or for UDP an empty datagram is waiting to be read gt 0 number of bytes waiting to be read LIBRARY HTTP LIB TCP IP Manual Vol 2 rabbit com 231 http sock fastread int http _ sock fastread HttpState state byte dp int len DESCRIPTION HTTP wrapper function for sock fastread that is for non blocking reads root This function can be used to read data from a socket associated with a particular HTTP server This function is intended for use in CGI applications PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function dp Pointer to return buffer len Maximum size of return buffer RETURN VALUE 50 the number of bytes read 1 error LIBRARY HTTP LIB 232 rabbit com HTTP Server http sock fastwrite int http sock fastwrite HttpState state byte dp int len DESCRIPTION HTTP wrapper function for sock fastwrite that is for non blocking writes This func tion can be used to write data from a root buffer to a socket associated with a particular HTTP server This function is intended for use in CGI applications PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function dp Pointer to buffer containing data to be written len Maximum number of bytes to write to the socket RETURN VALUE 50 the number of bytes written 1 error LIBRARY HTTP LIB TCP IP Manual Vol 2 rab
120. CTION this defines the CGI as new stvle SSPEC RESOURCE XMEMFILE specifies a file that has been imported in the server s flash memory using the ximport directive For example ximport samples tcpip http pages upload html index html index html is a placeholder a long int for the start of the file This is mentioned in the resource table entry so that the server knows where to get it The second entry above specifies a new style CGI function which has been the subject of the preceding sections You must use the SSPEC RESOURCE CGI macro to specify this type of CGI The URL string parameter is whatever is mentioned in the lt form action gt parameter of the initial web page The other parameter is the function pointer to the CGI that will process the upload If you do not wish to write a CGI just for handling file uploads you could specify http defaultCGI as the CGI function Step 8 Create List of Content Type Mappings The HTTP server needs to recognize different file formats This is done using file extensions and MIME types The server shares this information with the browser in its header In this way the browser knows how to handle the file The following code creates a table that maps file extensions to the appropriate MIME type SSPEC MIMETABLE START SSPEC MIME htm text html SSPEC MIME html text html SSPEC MIME gif image gif SSPEC MIME cgi SSPEC MIMETABLE END This method
121. ECTTO http REDIRECTHOST index shtml1 memmap xmem tuse dertcp lib use http lib ximport samples tcpip http pages ssi shtml index html ximport samples tcpip http pages rabbit1 gif rabbit1_gif ximport samples tcpip http pages ledon gif ledon gif ximport samples tcpip http pages ledoff gif ledoff gif ximport samples tcpip http pages button gif button gif ximport samples tcpip http pages showsrce shtml showsrc_shtml ximport samples tcpip http ssi c ssi c SSPEC MIMETABLE START SSPEC MIME FUNC shtml text html shtml handler SSPEC MIME html text htmi SSPEC MIME gif image gif SSPEC MIME cgi GW SSPEC MIMETABLE END TCP IP Manual Vol 2 rabbit com 149 char led1 15 char led2 15 char led3 15 char led4 15 LA int ledltoggle HttpState state if strcmp led1 ledon gif 0 strcpy led1 ledoff gif else strcpy led1 ledon gif CGil_iKeacllwecicieo SteaQicS REDIRECHE OE i eculia O int led2toggle HttpState state Entirely analogous to ledltoggle int led3toggle HttpState state Entirely analogous to led Itoggle int led4toggle HttpState state Entirely analogous to ledltoggle SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE SSPEC RESOURCE XMEMFILE SSPEC RESOURCE XMEMFILE SSPEC RESOURCE XMEMFILE SSPEC RESOURCE XMEMFILE SSPEC RESOURCE XMEMFILE SSPEC RESOURCE XMEMFILE SSPEC RESOURCE XMEMFILE i
122. ED lt z gt gt lt z print_opt select_var A gt This syntax allows for maximum flexibility In this case the count function returns the number of options in a selection variable The selected function takes a selection variable and an index as parameters It returns TRUE if that option matches the current value and FALSE if it doesn t The print opt function outputs the A th possible value The following is a convenience function that automatically generates the option list for a given selection variable lt zZ print select Sselect var gt 270 rabbit com RabbitWeb 5 3 4 Checkboxes and RadioButtons This section describes how to add checkboxes and radiobuttons to your web page Checkboxes are a bit tricky because if a checkbox is not selected then no information on that variable is sent to the server Only if it is selected will the variable value on by default or whatever you have in the VALUE this_is_the_value attribute be passed in In particular this means that if a variable was checked but then you uncheck it the server will not be able to tell the difference between that variable being unchecked and that variable value simply not being sent The server would need a notion of the full list of variables that should be in a specific form information which RabbitWeb does not have However there is a workaround If a variable is included in a form multiple times its value will be s
123. EE ALSO sspec setfventrvtvpe TCP IP Manual Vol 2 rabbit com 91 sspec getfvlen int sspec getfvlen int form int var DESCRIPTION Gets the length of a form variable the maximum length of the string representation of the vari able PARAMETERS form spec index of the form var Index into the FormVar array of the variable RETURN VALUE 1 Failure 20 Success length of the variable SEE ALSO sspec setfvlen sspec getfvname char sspec getfvname int form int var DESCRIPTION Gets the name of a variable that is displaved in the HTML form table PARAMETERS form spec index of the form var Index into the array of FormVar structures of the variable RETURN VALUE NULL Failure NULL name of the form variable SEE ALSO sspec setfvname 92 rabbit com Server Utilitv Librarv sspec getfvnum int sspec getfvnum int form DESCRIPTION Gets the number of variables in a form PARAMETERS form spec index of the form RETURN VALUE 1 Failure 20 Success number of form variables sspec getfvopt char sspec getfvopt int form int var int option DESCRIPTION Gets the numbered option starting from 0 of the form variable This function is only valid if the form variable has the option list set PARAMETERS form spec index of the form var Index into the array of FormVar structures of the variable option Index of the form variable option RETURN VALUE NULL Fail
124. EFAULT WRITEMASK respectively The current index is set to NULL PARAMETERS p Pointer to parameter structure to initialize If NULL does nothing but return NULL RETURN VALUE Alwavs returns p LIBRARV MIB LIB TCP IP Manual Vol 2 rabbit com 411 snmp last index word snmp last index snmp parms p DESCRIPTION Return the MIB tree index for the last object added or retrieved Indices are the most efficient way to access objects in the MIB tree however the efficiency comes at a price it is possible for indices to become invalid if the snmp delete function is ever used Once an object is created using snmp_add__ its index is guaranteed to remain valid until the same object is deleted using snmp_ delete After such time the index may refer to an unused tree entry and thus be garbage or another object may be created which will re use the same index It is safe to store indices of objects which are never deleted Otherwise the programmer must ex ercise caution An index value of SNMP_ NULL which is not the same as zero indicates a null index e g not found or unknown PARAMETERS p Parameter structure that was previously set by a call to snmp _add_ or snmp get or snmp get next RETURN VALUE SNMP NULL if p was NULL otherwise returns the index The returned index mav be garbage if no object was added or retrieved by previous calls LIBRARY MIB LIB SEE ALSO snmp ini
125. ERROR Can t resolve hostname SEE ALSO httpc post httpc post ext url encodestr 306 rabbit com HTTP Client httpc read body int httpc read body httpc Socket far s char buffer int buflen DESCRIPTION Read some of the body returned by the HTTP server PARAMETERS s Pointer to socket structure to use for connection buffer Buffer to store the data in buflen Length of buffer for storing data RETURN VALUE gt 0 length of data read 0 waiting on data from socket ENOTCONN connection closed can t read from socket NETERR REMOTE RESET connection closed before end of headers EIO error in chunked encoding EXAMPLE read bytes from the body of the response retval of bytes written do retval httpc read bodv amp hsock buffer sizeof buffer 1 while hsock status HTTPC STATE BODY TCP IP Manual Vol 2 rabbit com 307 httpc read header int httpc read header httpc Socket far s char buffer int buflen DESCRIPTION Read the next header from the socket PARAMETERS s Pointer to socket structure to use for connection buffer Buffer to store the header in recommend at least 128 bytes Header will be up to buflen 1 bytes followed by a null terminator Pass NULL if the call ing function does not need a copy of the header buflen Length of buffer for storing header Ignored if parameter 2 is NULL RETURN VALUE gt 0 length of header read excluding null terminator byte 0 no
126. HTML page by using the WEB ERROR function web foo 0 lt foo 71 WEB ERROR too low web foo foo lt 16 1 WEB ERROR too high Note that the checks for the variable foo have been split into two parts both checks are done during the error checking phase If the check such as 0 lt foo succeeds then the expression evaluates to 1 If the check fails then the special WEB ERROR function is triggered which will associate the given error string with the variable and will return 0 RWEB WEB ERROR MAXBUFFER which is 512 by default defines the size of the buffer for the error strings The buffer must be large enough to hold all error strings for a single form submission To change it define this macro before the use http lib statement in the application code Go to Section 5 3 5 to see how the error string passed to WEB ERROR is displayed in an HTML page 5 2 3 Security Features Various HTTP authentication methods basic digest and SSL are supported to protect web pages and variables Each method requires a username and password for access to the resource More information on the HTTP authentication methods is found in Section 4 3 In addition to the security offered by authen tication the concept of permissions allow specific protection for selected resources Permissions are granted based on user groups rather than on individual user ids User groups are defined at compile time however use
127. IC BACKUP echo state baud rate port number CONSOLE TCPIP BACKUP CONSOLE TCP MULTI BACKUP CONSOLE HTTP BACKUP CONSOLE SMTP BACKUP CONSOLE BACKUP LOGIN mv data mv data len mv preload mv presave CONSOLE BASIC BACKUP Causes backup of the echo state on or off baud rate and port number information CONSOLE TCPIP BACKUP Causes backup of the IP addresses of the controller board and the IP address of its netmask gate way and name server Note that only one of the CONSOLE TCP X structures should be used CONSOLE TCP MULTI BACKUP Using this structure causes if config to save and restore network configuration In addition to the information saved by CONSOLE TCP BACKUP multiple name servers DHCP configu ration ICMP Ping configuration and multiple interface configuration are all saved by CONSOLE TCP MULTI BACKUP Some built in console functions are for use with CONSOLE TCP MULTI BACKUP In general except for backwards compatibility issues CONSOLE TCP MULTI BACKUP should be used instead of CONSOLE TCP BACKUP Note that only one of the CONSOLE TCP x structures should be used CONSOLE HTTP BACKUP Causes backup of the files and variables visible to the HTTP server CONSOLE SMTP BACKUP Causes backup of the mail configuration CONSOLE BACKUP LOGIN Causes backup of the ConsoleLogin structure which stores the login name and password strings TCP IP Manual Vol 2 rabbit com 485 14 8 Zconsole Ma
128. ION HTTP wrapper function for blocking writes This function can be used to write data from a root buffer to a socket associated with a particular HTTP server This function is intended for use in CGI applications PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function dp pointer to buffer containing data to be written len maximum number of bytes to write to the socket RETURN VALUE Number of bytes of written or 1 if there was an error LIBRARY HTTP LIB 238 rabbit com HTTP Server http sock xfastread int http sock xfastread HttpState state long dp long len DESCRIPTION HTTP wrapper function for sock_fastxread that is for non blocking reads xmem This function can be used to read data from a socket associated with a particular HTTP server This function is intended for use in CGI applications PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function dp Pointer to return xmem buffer len Maximum length of the return xmem buffer RETURN VALUE Number of bytes of read or 1 if there was an error LIBRARY HTTP LIB http sock xfastwrite int http sock xfastwrite HttpState state long dp long len DESCRIPTION HTTP wrapper function for sock xfastwrite that is for non blocking writes It can be used to write the contents of an xmem buffer to a socket associated with a particular HTTP server PARAMETERS state HTTP state pointe
129. ION Returns the number of bvtes necessarv for each backup configuration file Note that enough space for two of these files needs to be reserved This function is most useful when ZCONSOLE LIB is being used with FS2 LIB RETURN VALUE Number of bytes needed for a backup configuration file LIBRARY zconsole lib SEE ALSO con backup reserve 476 rabbit com General Purpose Console con backup reserve void con backup reserve void DESCRIPTION Reserves space for the configuration information in the file system For more information on the file system see the Dynamic C User s Manual LIBRARY zconsole lib SEE ALSO con backup con load backup con backup bvtes con chk timeout int con chk timeout unsigned long timeout DESCRIPTION Checks whether the given timeout value has passed RETURN VALUE 0 Timeout has not passed 10 Timeout has passed LIBRARY zconsole lib SEE ALSO con set timeout TCP IP Manual Vol 2 rabbit com 477 con load backup int con load backup void DESCRIPTION Loads the configuration from the file system RETURN VALUE 0 Success 1 No configuration information found lt 0 Failure 1 error reading 1st set of information 2 error reading 2nd set of information and so on LIBRARY zconsole lib SEE ALSO con backup con backup reserve con reset io void con reset io void DESCRIPTION Resets all I O methods by calling close and
130. IST HOK 2 messages 320 octets 1 120 2 200 RETR 1 OK 120 octets lt the POP3 server sends message 1 gt DELE 1 OK message 1 deleted RETR 2 OK 200 octets lt the POP3 server sends message 2 gt DELE 2 OK message 2 deleted QUIT OK dewey POP3 server signing off maildrop empty lt close connection gt lt wait for next connection gt DANANDANNNA NA NNN ANNNNANHANANMNHNANUR For debugging purposes you can observe this conversation by defining POP DEBUG at the top of your program TCP IP User s Manual rabbit com 371 372 rabbit com POP3 Client RABE Tete 12 SNMP Simple Network Management Protocol SNMP is a popular network management tool Traditionally SNMP was designed and used to gather statistics for network management and capacity planning For example the number of packets sent and received on each network interface could be obtained But because of its simplicity SNMP use has expanded into areas of interest to embedded systems It is now used for many vendor specific management functions e g showing a thermostat temperature machine tool RPM or whether the front door was left open After reading this document and studying and running the provided demo program you will be able to e define a MIB e code and run an SNMP agent The SNMP library SNMP LIB implements version 1 of the SNMP protocol But before we get into the implementation details let s discuss SNMP from a con
131. L files one to display the current humidity to all users and another page that contains the form that allows some parameters to be changed 5 1 2 1 The Monitor Page The first HTML file is humiditv monitor zhtmi The zhtm1 suffix indicates that it contains special server parsed HTML tags That is the server must inspect the contents of the HTML file for spe cial tags rather than just sending the file verbatim 254 rabbit com RabbitWeb File name Samples tcpip rabbitweb pages humidity monitor zhtml lt HTML gt lt HEAD gt lt TITLE gt Current humidity reading lt TITLE gt lt HEAD gt lt BODY gt lt H1l gt Current humidity reading lt H1 gt The current humidity reading is in percent 222 jOrime Sawm PS lt P gt lt A HREF admin index zhtml gt Change the device settings lt A gt lt BODY gt lt HTML gt The above code displays the current humidity reading The new server parsed tags begin with lt z and end with gt print hum displays the given variable that must have been registered with web This code sets up a hyperlink that the user can click on to change the device settings Note that since it is in the admin directory the user will need to enter a username and password harpo and swordfish to access the file The username and password requirement was determined by the call to sspec addrule inhumidity c Also note that the reference
132. L if p was NULL or if there is no object with the given OID or if the object was not stored with short integer internal tvpe Otherwise returns p LIBRARV MIB LIB SEE ALSO snmp init parms snmp set stem snmp append stem snmp get indexed snmp get snmp add snmp xadd snmp set long snmp set str snmp set oct snmp set foct snmp set objectID TCP IP Manual Vol 2 rabbit com 431 snmp set long snmp parms snmp set long snmp parms p long L DESCRIPTION Set the value of a long integer object The OID of the object must be set in p If the object is not in fact a long integer then NULL will be returned and there will be no alteration of the value See snmp set int for other general considerations PARAMETERS p Parameter structure that was previously initialized by calls to snmp init parms snmp set stem etc L New value for the object RETURN VALUE NULL if p was NULL or if there is no object with the given OID or if the object was not stored with long integer internal tvpe Otherwise returns p LIBRARV MIB LIB SEE ALSO snmp init parms snmp set stem snmp append stem snmp get indexed snmp get snmp add snmp xadd snmp set int snmp set str snmp set oct snmp set foct snmp set objectID 432 rabbit com SNMP snmp set objectID snmp parms snmp set objectID snmp parms p snmp oid oid DESCRIPTION Set the value of an object ID object The OID of the object must be set in p I
133. LL LIBRARV MIB LIB SEE ALSO snmp init parms snmp set stem TCP IP Manual Vol 2 rabbit com 445 snmp used long snmp used void DESCRIPTION Obtain information about the amount of memory used by the MIB tree The value returned may be used as the setting for SNMP MIB SIZE if the application does not dynamically add objects during normal execution RETURN VALUE Number of bytes of xmem currently used by the MIB tree LIBRARY MIB LIB 446 rabbit com SNMP snmp xadd snmp parms snmp xadd snmp parms p char n word type long xs word maxlen DESCRIPTION This function is identical to snmp_add except that the object resides in xmem storage In stead of avoid address an xmem 20 bit linear address is stored In common with snmp add there is also a set of macros the use of which may result in cleaner code The macro names are identical to those for snmp add except that the names all start with snmp_xadd PARAMETERS p Pointer to parameter structure to set If NULL does nothing but return NULL n Optional extra OID level to temporarily append to the OID in p If 1 this is not done Otherwise the level is appended the value added then the extra level removed It is not possible to specify OID levels greater than JALI tvpe Type of value to add See description in snmp add xs xmem address of the actual object in xmem data storage The same consid erations apply to this ad
134. LM SSPEC DEFAULT METHOD This group of macros establishes global default permissions for resources that do not have a rule associated SSPEC DEFAULT READGROUPS is OxFFFF which means all users For writegroups this is O meaning no users The servermask defaults to SERVER ANY all serv ers can access realm defaults to 7 that is an empty string or no realm SSPEC DEFAULT METHOD defaults to no authentication method required 6699 SSPEC MAX FATDRIVES Determine the maximum number of independent FAT filesystem drives Defaults to 1 Each drive takes 8 bytes of root storage plus whatever is required by the filesystem itself Each drive can have up to 4 partitions This macro is only relevant if you use the FAT library SSPEC MAXNAME Define the maximum name length of each dynamic or static resource Defaults to 20 You can minimize memory usage by choosing short names for all resources and reducing the value of this macro SSPEC MAXRULES Define the maximum number of dynamically added rules Defaults to 10 but you can explicitly define it to zero if all the rule table entries are static see SSPEC RULETABLE macros Each rule takes up 13 bytes of root storage plus whatever storage is required for the realm and prefix strings which must be null terminated and in static storage since pointers to these are stored in the rule table 40 rabbit com Server Utility Library SSPEC MAXSPEC Define to the
135. MP 12 1 3 MIBs A MIB is a structured arrangement of managed objects a database that maps OIDs to actual variable instances The MIB may be used as a stand alone hierarchical database without SNMP if desired Instances of managed objects are always leaf nodes And only leaf nodes may be accessed using SNMP Figure 12 13 MIB Tree Diagram from Root Node Down to MIB II and Enterprise Subtrees ccitt 0 iso 1 iso ccitt 2 standard 0 registration member identified authority 1 body 2 organization 3 dod 6 PA internet 1 directory 1 mgmt 2 experimental 3 private 4 security 5 snmpV2 6 mib 2 1 enterprise 1 system 1 if 2 ip 4 icmp 5 tcp 6 udp 7 Rabbit Z World Inc Semiconductor 12817 12807 12 1 3 1 MIB II Subtree MIB II has nine groups six of which are usually of interest system if ip icmp udp and tcp Access to lots of useful information has been standardized by MIB II For example in the system group are managed objects named sysContact sysName and sysLocation If set they give the name and phone number of the person responsible for the device the device name and its physical location The interfaces group if holds information about each interface on a device The rest of the group names should be familiar For those interested in the descriptions of managed objects in MIB II read chapter 3 in a A Practical Guide to SNMPv3 and Network Management by David Zeltserman Not
136. N ERR SAVINGFILE Error saving file CON ERR READINGFILE Error reading file CON_ERR_FILENOTFOUND File not found JA CON_ERR_MSGTOOLONG Mail message too long rey CON ERR SMTPERROR SMTP server error X CON ERR BADPASSPHRASE Passphrases do not match bii CON ERR CANCELRESET Reset cancelled CON_ERR_BADVARTYPE Bad variable type CON_ERR_BADVARVALUE Bad variable value CON ERR NOVARSPACE Out of variable space CON_ERR_VARNOTFOUND Variable not found CON ERR STRINGTOOLONG String too long CON_ERR_NOTAFILE Not a file CON_ERR_NOTAVAR Not a variable CON ERR COMMANDTOOLONG Command too long CON ERR BADIPADDRESS Bad IP address CON ERR INVALIDPASSWORD Invalid Password CON ERR BADIFACE Bad interface name bey CON ERR BADNETWORKPARAM Error setting network parameter 14 4 2 2 Custom Error Messages Developers can create their own error messages bv following the format of the default error messages The error code numbers should be greater than 1 000 to save room for expansion of built in error messages define NEW ERROR 1001 const ConsoleError console errors CON STANDARD ERRORS includes all default error messages NEW ERROR Any error message I want The default error messages should be included in console errors along with any custom error messages that are used since the commands that com
137. NOTAUTH Unauthorized user FTP ERR BADMODE Requested option 2nd parameter is not supported FTP ERR UNAVAIL Resource temporarilv unavailable 334 rabbit com FTP Server 8 3 API Functions The API functions described here initialize and run the FTP server ftp dflt is auth int ftp dflt is auth int spec int options int uid DESCRIPTION Determine amount of access to a file If the FTP anonymous user has been set then also checks that options is how to access the file Currently this value is ignored If the anonymous user ID has been set then files it owns are globally accessible Returns whether the user can access it owner permission or if access is because there is an anonymous user world permission NOTE This routine only determines accessibility of a name not whether the user can read and or write the contents PARAMETERS spec Handle to SSPEC file item options How to access O RDONLXV O WRONLV or O_RDWR Currently this value is ignored uid The userID to access as RETURN VALUE 0 No access 1 uid only access 2 anonymous access user anonymous has been set SEE ALSO sspec checkaccess TCP IP Manual Vol 2 rabbit com 335 ftp init void ftp init FTPhandlers handlers DESCRIPTION Initializes the FTP server You can optionally specify a set of handlers for controlling what the server presents to the client This is done with function pointers in the FTPhandlers st
138. NY PARAMETERS s Pointer to an httpc Socket structure t Pointer to the tcp_ Socket that the HTTP client will use for its connec tions RETURN VALUE 0 OK EINVAL NULL passed for one of the first two parameters EXAMPLE httpc_init amp hsock amp tsock TCP IP Manual Vol 2 rabbit com 301 httpc init if int httpc init if httpc Socket far s tcp Socket tt int iface DESCRIPTION This function initializes the httpc Socket structure binds itto tcp_ Socket t and forces it to use interface iface PARAMETERS s Pointer to an httpc Socket structure t Pointer to thetcp Socket that the HTTP client will use for its connec tions Caller should memset this structure to 0 before first use iface Interface to use for connection if on a multi interface device RETURN VALUE 0 OK EINVAL NULL passed for one of first two parameters or invalid interface passed for iface EXAMPLE httpc init if amp hsock amp tsock IF PPPO 302 rabbit com HTTP Client httpc open int httpc open httpc Socket far s const char host word port DESCRIPTION Attempts to open a connection to a web server NOTE If a proxy server has been configured by calling httpc use proxy the host and port parameters are ignored and the proxy server settings are used for establishing the connection PARAMETERS s Pointer to httpc Socket structure to use for connection host Hostname or dotted IP to connect to
139. Name of the variable variable Pointer to the variable type Type of variable The following types are supported INT8 INT16 INT32 PTR16 FLOAT3 2 format Standard printf format string e g d RETURN VALUE 0 Success 1 Failure no room LIBRARY HTTP LIB SEE ALSO shtml delvariable 246 rabbit com HTTP Server shtml delfunction int shtml delfunction char name DESCRIPTION Deletes a function from the RAM resource table PARAMETERS name Name of the function as given to shtml addfunction RETURN VALUE 0 Success 1 Failure not found LIBRARY HTTP LIB SEE ALSO shtml_addfunction shtml delvariable int shtml delvariable char name DESCRIPTION Deletes a variable from the RAM resource table PARAMETERS name Name of the variable as given to shtml_addvariable RETURN VALUE 0 Success 1 Failure not found LIBRARY HTTP LIB SEE ALSO shtml addvariable TCP IP Manual Vol 2 rabbit com 247 248 rabbit com HTTP Server RABE Tete 5 RABBITWEB The Dynamic C RabbitWeb software allows developers to web enable embedded applications This chap ter explains the ease with which a web interface to a Rabbit based device can now be created In most cases this enhanced HTTP server eliminates the need for complicated CGI programming while giving the developer complete freedom in web page design The enhanced HTTP server is called RabbitWeb and uses
140. OF action code Using CGI_ SEND return code has some limitations In particular only a limited size of string may be sent to the client on any one call Also a null character cannot be sent to the client because the null is inter preted as the end of the string The null character problem is not usually important since nulls are rarely if ever sent in an HTML document The length limitation is more important since some HTML constructs can be very verbose The http write function is designed to overcome these limitations http write writes data from an arbitrary buffer with a higher length limit on any one call and returns either zero meaning that all data was successfully queued or it may return CGI_MORE if it could not write the data Either all or none of the data will be written respectively In the case that none was written the CGI returns the CGI_MORE return code to the HTTP server The CGI will then be called back with an action code of CGI CONTINUE where it should retry the failed http write call TCP IP Manual Vol 2 rabbit com 179 Ifhttp write returns zero it can be called again immediately with more data or the CGI can return zero to the HTTP server Otherwise the CGI function will generally need to remember what it was up to and retry the http write on the next call The following code illustrates use of http write static const char a very long html fragment 512 bytes case CGI END r
141. P CLIENT LIB SEE ALSO ftp client setup ftp client filesize ftp client xfer ftp last code 316 rabbit com FTP Client ftp client filesize int ftp client filesize void DESCRIPTION Returns the byte count of data transferred This function is deprecated in favor of ftp client xfer which returns a long value If the number of bytes transferred was over 32767 then this function returns 32767 which may be misleading RETURN VALUE Size in bytes LIBRARY FTP CLIENT LIB SEE ALSO ftp client setup ftp data handler ftp client xfer ftp client xfer longword ftp client xfer void DESCRIPTION Returns the byte count of data transferred Transfers of over 22 ed correctly bytes about 4GB are not report RETURN VALUE Size in bytes LIBRARY FTP_CLIENT LIB SEE ALSO ftp client setup ftp data _ handler ftp client filesize TCP IP Manual Vol 2 rabbit com 317 ftp data handler void ftp data handler int dhnd void dhnd data word opts DESCRIPTION Sets a data handler for further FTP data transfer s This handler is only used if the buffer pa rameter to ftp client setup is passed as NULL The handler is a function which must be coded according to the following prototype int my_handler char data int len longword offset int flags void dhnd_ data This function is called with data pointing to a data buffer and 1en containing the length of that buffer of
142. PTION Test whether a FAT partition has been registered with Zserver PARAMETER partno Partition number to test This starts at 0 corresponding to the A mount point 1 for B etc RETURN VALUE NULL Not registered Otherwise Registered and this is the fat part pointer SEE ALSO fat EnumDrive fat EnumPartition fat MountPartition sspec automount sspec fatregister TCP IP Manual Vol 2 rabbit com 83 sspec findfv int sspec findfv int form char varname DESCRIPTION Finds the index of a form variable in a given form PARAMETERS form spec index of the form in which to search varname Name of the variable to find RETURN VALUE 1 Failure 20 Success the index of the form variable in the array of type FormVar SEE ALSO sspec addfv 84 rabbit com Server Utilitv Librarv sspec findname int sspec findname char name word server DESCRIPTION Find the spec entry with a name field that matches the given name and is allowed with the spec ified server s Note that a leading slash in the given name and or in the resource name is ignored for backwards compatibility PARAMETERS name Name to search for in the resource list server The server making the request e g SERVER HTTP RETURN VALUE 1 Failure 20 Success spec index The special value SSPEC VIRTUAL is returned if the name refers to part of the virtual filesystem hierarchy In this case the server mask
143. P_MAX MONITOR When an object is monitored it is periodically examined at intervals of SNMP MIN TRAP INTVL milliseconds If at the time of examination the object is outside the specified bounds then trap message are initiated After the first message is sent another mes sage will be sent minintv1 seconds later Subsequent messages are sent at doubling time inter vals up to a maximum of maxintvl A maximum of nmesg messages will be sent for any event The time intervals and message counters are reset as soon as the object goes back inside the specified range 422 rabbit com SNMP PARAMETERS index minval maxval minintvl maxintvl nmesg ipaddr c index trap num noids indices snmp monitor continued MIB tree index of the object to monitor This value may be obtained when the object is created by calling snmp last index Minimum allowed value of object Maximum allowed value of object If the object is stored with an SNMP type of SNMP_P_ INTEGER then the comparisons are done using signed arith metic All other SNMP types are assumed to be unsigned so unsigned arith metic is performed Minimum interval in seconds between successive trap messages if the ob ject goes outside the specified bounds Maximum interval in seconds between messages Maximum number of messages to send while an object is outside bounds The message count is reset when the variable goes back inside bounds
144. Query to see if any HTTP servers are active RETURN VALUE 0 at least one HTTP server is active 1 all HTTP servers are idle LIBRARY HTTP LIB SEE ALSO http_handler 218 rabbit com HTTP Server http init int http init void DESCRIPTION Initializes the HTTP daemon This must be called after sock init and before calling http handler ina loop This sets the root directory to and sets the default file name to index html1 You can change these defaults by calling http set path after this function You can override these defaults at compile time by defining the macros define HTTP HOMEDIR define HTTP DFLTFILE index html to be something other than these defaults If you do this then there is no need to invoke the http set path function RETURN VALUE 0 Success LIBRARV HTTP LIB SEE ALSO http handler http shutdown http status http set path http is secure int http is secure HttpState state DESCRIPTION Test if this HTTP server state represents a secure SSL TLS connection PARAMETER state HTTP state structure RETURN VALUE None LIBRARV HTTP LIB TCP IP Manual Vol 2 rabbit com 219 http nextfverr void http nextfverr char start char name char value int error char next DESCRIPTION Gets the information for the next variable in the HTML form error buffer If any of the last four parameters in the function call are NULL then those par
145. RAPS to use this function PARAMETERS index MIB tree index of the object to unmonitor RETURN VALUE 1 the object is not currently being monitored Otherwise returns the monitor table index LIBRARY SNMP LIB SEE ALSO snmp monitor snmp trap TCP IP Manual Vol 2 rabbit com 443 snmp up oid snmp oid snmp up oid snmp oid oid word levels DESCRIPTION This function is identical to snmp_up_stem except that it uses an snmp oid structure See doc umentation for snmp up stem PARAMETERS oid Pointer to snmp oid structure to set If NULL does nothing but return NULL levels Number of levels to truncate on right of current OID If this is greater than the current number of levels the OID is set to emptv RETURN VALUE Returns oid unless NULL on entrv then nothing is done except to return NULL LIBRARV MIB LIB SEE ALSO snmp init parms snmp set stem snmp up stem 444 rabbit com SNMP snmp up stem snmp parms snmp up stem snmp parms p word levels DESCRIPTION Truncate the last n levels in the OID currently set in p This move up towards the first level in the OID PARAMETERS p Pointer to parameter structure to set If NULL does nothing but return NULL levels Number of levels to truncate on right of current OID If this is greater than the current number of levels the OID is set to emptv RETURN VALUE Returns p unless p is NULL on entrv then nothing is done except to return NU
146. RCE CGI upload cgi http defaultCGI SSPEC RESOURCETABLE END int io state web io state auth basic groups monitor group ro admin group void mv io polling void void main int rc sspec addrule index html Pet admin groupjmonitor group 0 SERVER HTTP SERVER AUTH BASIC NULL sauth setusermask sauth adduser admin dog SERVER ANX admin group NULL sauth setusermask sauth adduser monitor cat SERVER ANY monitor group NULL re sspec automount SSPEC MOUNT ANY NULL NULL NULL if rc printf Failed to initialize rce d n Proceeding anyway n rc sock init http init for 4337 4 mv io polling http handler TCP IP Manual Vol 2 rabbit com 23 The first change is the addition of FAT USE FORWARDSLASH and FAT BLOCK These are needed by Zserver to work with the FAT filesystem The definition of USE_HTTP_UPLOAD is needed for Zserver to use the file upload feature Next the libraries for the FAT fat lib and for the serial flash driver sflash fat libjare brought in with use statements The MIME tvpe mapping for CGIs is added to the MIME table with SSPEC RESOURCE CGI An empty string is the registered type for CGIs This makes sense since CGIs are not displayed by the browser Next we want to give the server access to the CGI function by creating an entry for it in the static resource table with SSPEC RESOURCE CGI The first parameter is a string that m
147. RIPTION Removes the user group s that userid belongs to from the read and write access masks for the specified resource This will deny access to other users who have the same group s as the current user This function is deprecated as of Dynamic C 8 50 Use the more general sspec setpermissions function instead PARAMETERS sspec spec index userid user index RETURN VALUE 0 Success user was removed 1 Failure no such userid found SEE ALSO sspec setuser sspec adduser sspec getusername sspec getuserid sspec setpermissions TCP IP Manual Vol 2 rabbit com 115 sspec resizerootfile int sspec resizerootfile int spec index int new size DESCRIPTION Change the byte size of a SSPEC item stored in root memory Item must be a ROOTFILE thus the item must have been created with sspec_addrootfile PARAMETERS spec index spec index of the item new size New size to assign to item RETURN VALUE 20 Successfully adjust size of item 1 Failed to adjust size SEE ALSO sspec addrootfile sspec restore int sspec restore void DESCRIPTION Restores the TCP IP servers object list and the TCP IP users list and some user specified data if set up with sspec setsavedata from the file system This does not restore the actual files and variables but onlv the structures that reference them If the files are stored in flash then the references will still be valid Files in volatile RAM and variables
148. RN VALUE 0 Success 1 Failure LIBRARY VSERIAL LIB ID of the gateway to change as specified in the spec table The parameter to send to the open serial port command it s usually the baud rate The local TCP port to listen on The remote host from whom to accept connections or 0 to accept a connec tion from anybody Option flags for this gateway Currently the only valid bit flags are VSERIAL COOKED to strip out telnet control codes or 0 to leave it a raw data link 452 rabbit com Telnet vserial open int vserial open int id long baud int port long remote host int flags long retry DESCRIPTION Opens a connection to a remote host and maintains it starting the gateway process PARAMETERS id ID of the gateway to change as specified in the spec table baud The parameter to send to the open serial port command it s usually the baud rate port The TCP port on the remote host to connect to remote host The remote host to connect to flags Option flags for this gateway Currently the only valid bit flags are VSERIAL COOKED to strip out telnet control codes or 0 to leave it a raw data link retry The retry time out in seconds When a connection fails or if the connection was refused we will wait this number of seconds before retrying RETURN VALUE 0 Success 1 Failure LIBRARY VSERIAL LIB TCP IP Manual Vol 2 rabbit com 453 vserial tick int vserial tick void
149. ROLOG CGI EPILOG CGI HEADER or CGI_ EOF NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Length of available data This will range from 0 to HTTP MAXBUFFER 0 will only be returned for PROLOG and EPILOG when a blank line is read LIBRARY HTTP LIB SEE ALSO http_getAction 206 rabbit com HTTP Server http getField char http getField HttpState state DESCRIPTION Return the current form field name This function should only be called when the action code is CGI START CGI_DATAor CGI_END NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Null terminated string containing the current field name The field name is the name of a form element specified using for example lt INPUT TYPE TEXT NAME srv file in the HTML where srv_ file is the field name If there was no name parameter in the returned form data this will be an empty string zero length not NULL LIBRARY HTTP LIB SEE ALSO http_getAction TCP IP Manual Vol 2 rabbit com 207 http getHTTPMethod char http getHTTPMethod HttpState state DESCRIPTION Return the HTTP request method of the current request protocol The CGI might need to look at this to generate the correct response headers NOTE This is implemented as a macro
150. RS sspec spec index index index of userid for this sspec resource to return 0 1 2 RETURN VALUE 1 Error or no such userid 0 Success userid is returned SEE ALSO sspec getusername sauth getusername TCP IP Manual Vol 2 rabbit com 101 sspec getusername char sspec getusername int sspec DESCRIPTION Gets the username field of the first user in the user table that has read access to the resource indexed by sspec If multiple users are associated with this resource the first user s username will be returned See sspec_getuserid to get all userids for a resource and sauth_getusername to convert the userids to usernames Starting with Dynamic C 8 50 access control is done by groups rather than individual users there fore sspec getusername may not work as expected This only works for RAM and flash table entries PARAMETERS sspec spec index RETURN VALUE NULL Failure or no user has read access to this resource NULL Success pointer to username SEE ALSO sauth adduser sspec setuser sauth getuserid sauth getusername sspec getvaraddr void sspec getvaraddr int sspec DESCRIPTION Returns a pointer to the requested variable in the resource list PARAMETERS sspec spec index RETURN VALUE NULL Failure NULL Success pointer to variable SEE ALSO sspec readvariable 102 rabbit com Server Utility Library sspec getvarkind word sspec getvarkind
151. RTANT NOTE the buffers for username and password must NOT change until pop3 tick returns something besides POP PENDING These values are not saved inter nally and depend on the buffers not changing PARAMETERS username The username of the account to access password The password of the account to access server The IP address of the server to connect to as returned from resolve RETURN VALUE 0 Success 1 Failure LIBRARY POP3 LIB 368 rabbit com POP3 Client pop3 tick int pop3 tick void DESCRIPTION A standard tick function to run the daemon Continue to call it as long as it returns POP PENDING RETURN VALUE POP PENDING Transfer is not done call pop3 tick again POP SUCCESS All e mails were received successfully POP ERROR Unknown error occurred POP TIME Session timed out Try again or use POP TIMEOUT to increase the time out length LIBRARY POP3 LIB TCP IP User s Manual rabbit com 369 11 5 Sample Receiving of E mail This program connects to a POP3 server and downloads e mail from it Program Name Samples tcpip pop3 parse_extra c define define define define define memmap INEPEON FT AL POP HOST mail domain com Name of your POP3 server POP USER myname Username for POP3 account POP PASS secret Password for POP3 account POP _ PARSE EXTRA xmem tuse Teertcj Iipr use pop3 lib int n int storemsg int num char to char from char
152. RV SNMP LIB SEE ALSO snmp add communitv snmp set dflt communities snmp set communitv snmp communitv name TCP IP Manual Vol 2 rabbit com 403 snmp community name char snmp community name word c_ index int length DESCRIPTION Return the name and optionally the length of the specified community PARAMETERS c index The community table index is the value returned by snmp_add_community ormay be SNMP PUBLIC SNMP_ PRIVATE or SNMP_TRAPDEST for the predefined default com munities length If not NULL then the addressed location will be set with the community name string length RETURN VALUE NULL the index was outside the table bounds Otherwise a pointer to the community name is returned The data at this location should not be modified LIBRARY SNMP LIB SEE ALSO snmp add communitv snmp set dflt communities snmp set communitv snmp communitv mask 404 rabbit com SNMP snmp copy oid snmp oid snmp copy oid snmp parms p snmp oid tn DESCRIPTION Copy the current object ID stem from p into n PARAMETERS p Parameter structure that was previously initialized by calls to snmp init parms snmp set stem etc n Object ID structure to be filled in with current stem from p Must not be NULL RETURN VALUE If p was NULL returns NULL otherwise returns n LIBRARY MIB LIB SEE ALSO snmp init parms snmp set stem snmp append stem TCP IP Manual Vol 2 rabbit com 4
153. RY HTTP LIB SEE ALSO http_getAction TCP IP Manual Vol 2 rabbit com 229 http shutdown int http shutdown int graceful DESCRIPTION Shut down the http daemon Use http init to restart PARAMETER If non zero current connections are allowed to terminate normally Otherwise any open connec tions are reset RETURN VALUE 0 LIBRARY HTTP LIB SEE ALSO http_handler http_init http_status http skipCGI int http skipCGI HttpState state DESCRIPTION Indicate to the HTTP server that the CGI has finished processing this part of a multi part data stream The server reads and discards data from the stream until the next part is found or the epilog When the next part is found the server continues calling the CGI function as before PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE 0 LIBRARY HTTP LIB SEE ALSO http_getAction http_abortCGI http_switchCGI http_finishCGI http_write 230 rabbit com HTTP Server http sock bytesready int http sock bytesready HttpState state DESCRIPTION HTTP wrapper function for sock bvtesreadv This function may be used by CGI appli cations to determine if there is data waiting on the socket associated with a particular HTTP server PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE 1 no bytes waiting to be read 0 in AS
154. RabbitWeb software 5 5 1 Language Enhancements Grammar so Terminals are in bold f indicate optional parts and I indicates an OR in the statement web extension gt web statement web groups statement web update statement web statement gt web variable expression authorization End of line escaping must be used for the web statement to span lines variable gt case insensitive C variable expression gt modified C expression select select list select list gt string numeric literal select list variable isa C variable in the global scope Due to details of how variables are transferred over HTTP the variable name must be treated as case insensitive We can catch variables that conflict because of case insensitivity at run time modified C expression isa regular C expression with an optional symbol preceding C vari ables which is used to reference the newest value of the variable authorization gt authorization auth method valid groups auth method gt auth auth type list auth type list gt ssl basic digest auth type list valid groups gt groups valid groups list valid groups list gt group group rights valid groups list group rights gt ro rw web groups statement gt web groups groups list groups list gt group name groups list group name follows the same rules of a C variable name it will in fact be in the
155. SMI specifies the allowable data types information organization and the encoding rules used BER 376 rabbit com SNMP Object Data Types Managed objects must be reducible to the data types defined for SNMP The following table shows the mappings from the SMI defined types to the internal types used by the MIB LIB implementation to store an object in the MIB tree SMI Defined Data Type Internal Data Type SNMP SHORT INTEGER SNMP_LONG SNMP_OCT OCTECT STRING SNMP_FOCT SNMP_STR OBJECT IDENTIFIER SNMP_OID NULL SNMP_NULL IpAddress SNMP_ LONG Counter SNMP LONG Gauge SNMP LONG TimeTicks SNMP_LONG The internal data types are specified in the following table Internal Type Representation SNMP SHORT 2 byte integer in Rabbit order little endian SNMP_LONG 4 byte integer in Rabbit order Null terminated string with specified maximum length The null SNMP STR terminator is not counted in computing the string length The null is only appended if the string is less than its maximum length 2 byte unsigned length field followed by data The length field SNMP OCT contains the actual data length not including the 2 bvtes for the length field itself SNMP FOCT Fixed length binary data The length is always equal to the maximum length specified SNMP_OID Object identifier as defined by the snmp_ oid structure The easiest way to understand
156. SOURCE ROOTVAR led1 led1 PTR16 MILEGI W IEGD PTRIG Ted led PIRIC U Wales lTed4 PITRE IU AO AO AO ol nan an SSPEC RESOURCETABLE END shtml handler which is the built in script processor for SSI looks up 1ed1 and replaces it with the text output from printf s char led1 The ledi variable is either ledon gif or ledoff gif When the browser loads the page it replaces lt img SRC Tal iecho ver Tleci il stis with lt img SRC ledon gif gt or lt img SIRCS LeClosese efi S This causes the browser to load the appropriate image file SSI string variables are only appropriate for relatively short strings In the above example the SSI string variables are ledon gif and ledoff gif The size that can be output is limited to the size HTTP MAXBUFFER If you need larger strings you should either increase HTTP MAXBUFFER which will use more root RAM or switch to using a CGI function 152 rabbit com HTTP Server 4 5 2 2 CGI Feature Ssi c also demonstrates the Common Gateway Interface CGI is a standard for interfacing external applications with HTTP servers Each time a client requests an URL corresponding to a CGI program the server will execute the CGI program in real time For increased flexibility a CGI function is responsible for outputting its own HTTP headers Information about HTTP headers can be found at http deesse univ lemans fr 8003 Connected RFC 1945
157. START call The CGI has no choice than to return to the HTTP server after doing whatever it can in the CGI_ START state The solution to this problem is that the CGI opens the file on the CGI_ START call and stores the open file handle somewhere where it can be retrieved on the next CGI DATA or CGI END call The recom mended method for accomplishing this is to save the handle back with the server You can use the http setCond andhttp getCond functions to do this The HTTP server maintains a set of so called cond variables for each CGI instance Your application decides how many cond variables there are by defining the HTTP MAX COND macro which defaults to 4 Each cond variable is a 16 bit integer There is also a single integer variable accessed using http getState andhttp setState TCP IP Manual Vol 2 rabbit com 171 Expanding on the above let s add opening of the file define COND HANDLE 0 cond variable for storing the handle case CGI START if http getField s 0 printf Found a file to upload n http setCond s COND HANDLE sspec open http getField s http getContext s O WRITEJO CREAT O TRUNC 0 if http getCond s COND HANDLE lt 0 http skipCGI else http skipCGI s break The sspec_open function opens the file whose name is in the field name with write access The http getcontext function returns a server context structure which is required for the ss
158. ServerPermissions to use for this entry 3 1 6 ServerContext Structure Starting with Dynamic C 8 50 context information must be maintained by each server that wants Zserver functionality Therefore servers must provide a ServerContext struct when required The fields of ServerContext are userid This field identifies the current user server This field identifies the server for example SERVER HTTP This is one of the few cases where only a single server bit should be set rootdir This field is a pointer to the root directory This is usually if the whole namespace is to be accessible Otherwise it may be for example A to restrict access to just the first DOS FAT partition The first and last character must be cwd This field is an array containing the current working directory This would normally contain the root directory as a prefix The first and last character must be dfltname This field points to a file name to be used as a resource name suffix when the first parameter refers to a directory name The ServerContext structure helps support more powerful resource access control It is needed by several of the new API functions that deal with resource retrieval and control as well as functions that per form directory navigation There are two functions that return a ServerContext struct http getcontext and http getContext The latter is for use in CGI functions These functions can be u
159. Set the callback function for the next object to be added This remains in effect for all further ad ditions until cancelled by passing NULL for the callback function Use of the callback function is described in the printed documentation It is only applicable if SNMP is being used The functions in MIB LIB do not invoke the callback PARAMETERS p Pointer to parameter structure to set If NULL does nothing but return NULL cb Pointer to callback function or NULL to cancel RETURN VALUE Returns p unless p is NULL on entrv then nothing is done except to return NULL LIBRARV MIB LIB SEE ALSO snmp init parms TCP IP Manual Vol 2 rabbit com 427 snmp set community int snmp set community word c index char cname byte mask DESCRIPTION Changes the name password string and access mask for the community indexed by c_ index PARAMETERS c index Community table index This is the value returned by snmp add communitv ormav be SNMP PUBLIC SNMP PRIVATE or SNMP TRAPDEST for the predefined default com munities cname Communitv name as a null terminated string with maximum length of SNMP MAX COMMUNITV NAME mask Access mask This specifies the access groups one or more of 8 groups to which this community belongs Three groups are predefined SNMP PUBLIC MASK public group with read only access SNMP PRIVATE MASK private group with read write access SNMP TRAPDEST MASK trap group with no access RETURN VALUE
160. System Initialization Prior to Dynamic C 7 30 Zconsole depended on the flash file system included with Dynamic C There are actually two file systems FS1 was the first Dynamic C file system The second one FS2 introduced with Dynamic C 7 05 is an improved file system Besides defining the macro that directs the file system to EEPROM memory and including the appropriate library i e define FS FLASH use filesvstem lib If using the improved file system available with Dynamic C 7 05 substitute fs2 lib for filesvstem lib the application program must initialize the file system with a call to fs init Starting with Dynamic C 7 30 none of this is necessary because Zconsole saves configuration information to the User block See the designer s handbook for your Rabbit processor e g the Rabbit 4000 Designer s Hand book for more information about the User block 14 6 2 Serial Buffers If the pre defined serial I O methods are used the circular buffers used for I O data can be resized from their default values of 31 bytes by using macros For example if CONSOLE IO SERIALC is included in console _io then lines similar to the following can be in the application program define CINBUFSIZE 1023 define COUTBUFSIZE 255 In general these buffers can be smaller for slower baud rates but must be larger for faster baud rates 14 6 3 Using TCP IP To use the TCP IP functionality of Zconsole you must have the foll
161. T TYPE checkbox lt z if checkboxBoolean 1 gt CHECKED 78 gt NAME checkboxBoolean VALUE 1 gt lt br gt lt br gt TCP IP Manual Vol 2 rabbit com 271 lt z for SA 0 A lt count S radiobutton A gt lt INPUT TYPE radio NAME radiobutton VALUE lt z print opt radiobutton SA gt OPTION lt z if selected radiobutton SA gt CHECKED lt z gt gt 228 Ps lt br gt lt br gt lt INPUT TYPE Submit VALUE Submit gt lt form gt lt BODY gt lt HTML gt To take advantage of the above zhtml script the server code would need something like the following int checkboxBoolean radiobutton web checkboxBoolean web radiobutton select 0 0 1 2n 3n wan 5 6 u7 checkboxBoolean 0 radiobutton 0 5 3 5 Error Handling One of the biggest benefits to the new server parsed HTML tags is the ability to perform actions based on whether a user submitted variable was in error A natural way of creating an HTML user interface is to create the form on an HTML page When the user enters or changes values and submits the result the server should check the input for errors If there are errors then the same form can be redisplayed This form can mark the values that are in error and allow the user to update them With the use of conditionals it is possible to create both the original form and the form that shows the errors in the same page
162. TART is received all of the part headers have been read so the server knows everything relevant about the data that follows The CGI can access this information using several of the HTTP API functions The most important information is the field name on the form from the lt INPUT NAME fieldname gt element in the HTML form case CGI START if http _getField s 0 printf Found a file to upload n break http getField looks at the first character of the field name to see if it is a slash character We are using the convention that if the field starts with a slash it is the name of a local file to be overwritten with the following data Note that the field names are controlled by the server via the NAME parameters in the INPUT fields We can choose any naming convention desired in this case using an initial slash seems to make sense for file destinations Now let s fill in what happens when there is a file to save In most cases when writing or reading a file it is necessary to open the file When a file is open it can be read and or written Finally it is closed All this implies that some sort of state needs to be maintained so that we can refer to the correct open file It would be very easy if all the data was presented at once to the CGI so that it could open write and close the file in one fell swoop Unfortunately that cannot happen since the data is not yet available on the CGI_
163. TCP IP Manual Vol 2 rabbit com 25 That way the only people who see the Upload button are those authorized to use it Design decisions such as these are guided by the needs of the application The point here is that these design decisions are not limited by the underlying tools you are using to accomplish your goal 2 8 Living Without RabbitWeb and FAT Without the use of RabbitWeb we are back to SSI tags in the HTML page and writing a CGI to process them With the new style CGIs introduced in Dynamic C 8 50 this is easier than it used to be If there is no serial flash the FAT filesystem isn t available but if there is a second flash or some battery backed RAM FS2 is The following diagram shows the components that are used in this case Note that even though both the second flash and the battery backed RAM are highlighted an application can use either or both Figure 2 7 Components of a full featured web enabled application Application Compile Time Run Time Main Application CGI Initialization Initialization Loop Specifics I Q_ _ Functions es es ee wm Gr Metadata i Requests MIME Resources Contexi Table Zserver Resource Manager Dynamic Resource Table Static Resource Table ETS lt TD COED RAPA Storage Program Second Backed Serial 1 Flash Flash Flash 26 rabbit com Web Enabling Your Application The sample program is now modified to use the FS2 filesystem I
164. TURN VALUE If parameter is a TCP or SSL server 0 socket is not writable It was closed by the application or it may have been aborted by the peer Non zero the socket is writable The amount of data that the socket would accept is this value minus 1 which may turn out to be zero if the socket s buffer is temporarily full On a freshly established socket and at any other time when all data has been acknowledged by the peer the return value minus one indicates the maximum socket transmit buffer size If parameter is a UDP server 0 socket is not open Non zero socket is open This value minus 1 equals the maximum size datagram payload that would be sent without fragmentation at the IP level Note the maximum payload depends on the interface which is selected Since this is not known a priori the interface with the largest MTU is arbitrarily selected LIBRARY HTTP LIB TCP IP Manual Vol 2 rabbit com 237 http sock tbleft long http sock tbleft HttpState state DESCRIPTION HTTP wrapper function for sock tbleft This function may be used by CGI applications to determine how much space is left in the HTTP socket s transmit buffer PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Number of bytes of free space remaining in the transmit buffer LIBRARY HTTP LIB http sock write int http sock write HttpState state byte dp int len DESCRIPT
165. TURN VALUE 0 Success 1 Failure LIBRARY VSERIAL LIB TCP IP Manual Vol 2 rabbit com 455 telnet tick int telnet tick void DESCRIPTION Must be called periodically to run the daemon RETURN VALUE 0 Success call it again 1 Failure TELNET CONNECT died or a fatal error occurred LIBRARY VSERIAL LIB telnet close void telnet close void DESCRIPTION Terminates any connections currently open and shuts down the daemon LIBRARY VSERIAL LIB 456 rabbit com Telnet 13 2 3 An Example Telnet Server The following code implements a telnet server It listens on well known port 23 for a connection request Data is passed transparently via serial port C define MV IP ADDRESS 10 10 6 105 define MV NETMASK 255 255 255 0 define MV GATEWAV 10 10 6 19 define MV NAMESERVER 10 10 6 19 define SERIAL PORT SPEED 115200 Set serial port speed undef TELNET COOKED This is a raw data port memmap xmem kuse dortop lip use vserial lib define SERVER_PORT 0 Defaults to port 23 main SOCK ilmiib 5 Mnitialize stack telnet init TELNET LISTEN 0 SERVER_ PORT Mnitialize server while telnet tiek Run server this is non blocking continue telnet close Error close telnet connection TCP IP Manual Vol 2 rabbit com 457 13 2 4 An Example Telnet Client This sample code implements a client that can connect to the above telnet server define
166. The user can create a structure like the following to indicate to the web server that it should save the speci fied tags const HttpHeader http headers Host Content Length User Agent END HTTP HEADERS i END HTTP HEADERS is simplv a macro NULL that indicates the end of the structure These headers will be saved in an internal buffer of a user specified size define HTTP CUSTOM HEADERS SIZE 1024 By default HTTP CUSTOM HEADERS SIZE is undefined which disables the custom header function alitv since in most cases it will not need to be used This buffer will be located in xmem and there will be one per HTTP server A define will also be provided to limit the maximum size of a single header to keep one verv long header from monopolizing all of the buffer space define HTTP CUSTOM HEADER MAX SIZE 128 By default this is undefined and there is no limit The user will also need functions that look up the data int http getheader HttpState state char header char dest int destlen int http xgetheader HttpState state char header long destptr The first function requires the user to provide a root buffer to place the header The Ht tpState state structure must be passed so that the server knows which set of headers to access The header parameter is of course the name of the header the user wants to retrieve dest is a pointer to the destination buffer destien is the length of the destination buffer
167. TransferEncoding http_getField http_getContentLength http_getContentType http_getContentDisposition http_getTransferEncoding http_getData http_getDataLength CGI_DATA http_getField http_getContentLength CGI END http_getContentType http_getContentDisposition http_getTransferEncoding CGI_HEADER CGI_ PROLOG CGI EPILOG CGI EOF http_getData http_getDataLength Depends on previous action code at time of returning CGI_ CONTINUE CGI_MORE however http_getData will NOT be valid 198 rabbit com HTTP Server Table D 8 Valid Functions per Action Code CGI Action Code Valid Functions Macros Should only do resource cleanup http_getContext http_getURL http_getState CGI ABORT http_getCond http_getUserState http_getHTTP Version http_getHTTPVersion_str http_getHTTPMethod http_getHTTPMethod_str PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Action code One of the following values e CGI START start of a part in a multi part transfer e CGI DATA binary data for this part e CGI END end ofa part e CGI HEADER header line of a part e CGI PROLOG binary data before the first part e CGI EPILOG line of data after the last part e CGI EOF normal end of all parts and epilog e CGI ABORT abnormal termination CGI should recover and or close any open resources e CGI CONTINUE being called from the HTTP se
168. UE if that variable did not pass its error check and FALSE otherwise It can be used to print out the WEB ERROR message print error foo printf This is a display function to make web variables visible on an HTML page With printf you can dis play a variable of type int or long lt z printf sld Slong foo gt print opt This is a display function to make selection type web variables visible on an HTML page It takes two parameters The first parameter is a selection type variable and the second parameter is the index into the list of possible values for the selection type variable lt zZ print opt Sselect var SA gt 292 rabbit com RabbitWeb print select This is a display function to make selection type web variables visible on an HTML page It automati cally generates the option list for a given selection variable lt zZ print select Sselect var gt selected The selected function takes two parameters The first parameter is a selection variable and the sec ond parameter is an integer index into the array of options for the specified selection variable The function returns TRUE if the option indicated by the index parameter matches the currently selected option and FALSE if it doesn t For example to iterate through all possible values of a selection type variable and output the appropriate lt OPTION gt or lt OPTION SELECTED gt tags something like the following
169. UG Base64 encoded Username client responds with its Base64 encoded username server re sponds with 334 UGFzc3dvemQ6 client responds with its Base64 encoded password At this point the server should respond with a message indicating whether authentication was successful This method is only slightly more complex than AUTH PLAIN AUTH CRAM MD5 Client sends AUTH CRAM MDS server responds with 334 lt challenge gt where lt challenge gt is a unique Base64 encoded challenge string for example lt 4994 1088035610 rabbit com gt The client generates a digest using the following MDS hashing algorithm where password is null padded to a length of 64 bytes ipad is 0x36 repeated 64 times and opad is Ox5C repeated 64 times digest MD5 password XOR opad MD5 password XOR ipad challenge The client responds with the string lt username gt lt response gt Base64 encoded lt username gt is in plaintext and lt response gt is the 16 byte digest in hex form This method is the most secure since someone sniffing the connection would be unable to determine the cleartext password used to au thenticate 354 rabbit com SMTP Mail Client 10 3 Sample Sending of an E mail This program smtp c sends an e mail To have the client query the server for authentication define the macro USE SMTP AUTH and call smtp setauth before calling smtp_sendmail or smtp sendmailxmem If the mail server does not support authentica
170. Utilitv Librarv sspec addfsfile int sspec addfsfile char name byte filenum word servermask DESCRIPTION Adds a file located in the FS2 filesystem to the RAM resource list Make sure that SSPEC MAXSPEC is large enough to hold this new entry This function associates a name with the file This creates an alias entry for fs2 file lt n gt Note that all FS2 files are automatically accessible There is no need to call this function unless it is desired to assign a name to an FS2 file other than the default whichis filel file2 etc For more information regarding the FS2 filesystem please see the Dynamic C User s Manual PARAMETERS name Name of the new file filenum Number of the file in the file system 1 255 This is the number passed in as the second parameter to fcreate or the return value from fcreate unused servermask Bitmask representing servers for which this entry will be valid e g SERVER HTTP SERVER FTP RETURN VALUE 1 Failure 20 Success location of file in TCP IP servers object list SEE ALSO sspec addrootfile sspec addfunction sspec addvariable sspec addxmemfile sspec addform sspec aliasspec TCP IP Manual Vol 2 rabbit com 61 sspec addfunction int sspec addfunction char name void fptr word servermask DESCRIPTION Adds a function to the RAM resource list Make sure that SSPEC_MAXSPEC is large enough to hold this new entry This function is currently only us
171. Vol 2 rabbit com 325 ftp dflt getfilesize long ftp dflt getfilesize int fd DESCRIPTION Return the length of the specified file This is called immediately after open for a read file If the file is of a known constant length the correct length should be returned If the resource length is not known perhaps it is generated on the fly then return 1 For write operations the maximum permissible length should be returned or 1 if not known PARAMETERS fd The file descriptor returned when the file was opened RETURN VALUE 20 The size of the file in bytes 1 The length of the file is not known 326 rabbit com FTP Server ftp dflt read int ftp dflt read int fd char buf long offset int len DESCRIPTION Read file identified by d The file contents at the specified offset should be stored into buf up to a maximum length of len The return value should be the actual number of bytes transferred which may be less than 1 en If the return value is zero this indicates normal end of file If the return value is negative then the transfer is aborted Each successive call to this handler will have an increasing offset If the getfilesize handler returns a non negative length then the read handler will only be called for data up to that length there is no need for such read handlers to check for EOF since the server will assume that only the specified amount of data is available The return value can also be gre
172. ZE Maximum length of mail server name and NULL terminator Defaults to 51 CON MAX NAME Default is 10 maximum number of characters for a login name This value must be equal to or less than CON CMD DATA SIZE CON MAX PASSWORD Default is 10 maximum number of characters for a login password CON NO FS SUPPORT This macro is defined by default only if no filesystem libraries have been used Even if a filesvs tem library has been used this can still be explicitly defined by the user When this is defined then the console will not save configuration information to the filesystem and no filesystem function calls will be included CON SP RDBUF SIZE Size of the slave port read buffer Defaults to 255 CON SP WRBUF SIZE Size of the slave port write buffer Defaults to 255 CON TIMEOUT Adjusts the number of seconds that the console will wait before cancelling the current command The timeout can be adjusted in user code in the following manner state gt timeout con set timeout CON TIMEOUT This is useful for custom user commands so that they can indicate when something meaningful has happened on the console such as some data being successfully transferred CON VAR BUF SIZE Adjusts the size of the variable buffer in which values of variables can be stored for use with the HTTP server It is allocated in xmem space Defaults to 1024 bytes CON VERSION MESSAGE This defines the version message to display when the HELP comma
173. _multi Like the con show function this function shows the current console configuration This command will however show more network configuration than is available via con show Interface specific configuration information is separated out A command that uses this function takes an optional parameter ETHO ETH1 PPPO PPP1 PPP2 etc to display the interface specific configuration for the specified interface If the optional parameter is missing the current console configuration for all valid interfaces is displayed TCP IP Manual Vol 2 rabbit com 467 14 4 1 2 Custom Zconsole Commands Developers are not limited to the default commands A custom command is easy to add to Zconsole sim ply create an entry for itin console commands The three fields of this entry were described in Section 14 3 1 The first field is the name of the command The second field is the function that imple ments the command This function must follow this prototype int function name ConsoleState state The parameter passed to the function is a structure of type ConsoleState Some of the fields in this structure must be manipulated by your custom command function other fields are used by Zconsole 1ib and must not be changed by the your program typedef struct int console number ConsoleIO conio int state int laststate char command CON CMD SIZE char cmdptr char buffer CON BUF SIZE Use for reading in data char buf
174. access mask is the user has no write access to any server To assign this permission call the function sauth setwriteaccess with the user table index returned by sauth adduser PARAMETERS username Name of the user a character string up to SAUTH MAXNAME characters password Password for the user another character string up to SAUTH MAXNAME characters servermask Bitmask representing valid servers e g SERVER HTTP SERVER FTP RETURN VALUE 1 Failure 20 Success index into user table id passed to sauth_getusername SEE ALSO sauth authenticate sauth getwriteaccess sauth setusermask sauth setwriteaccess sauth removeuser 46 rabbit com Server Utilitv Librarv sauth authenticate int sauth authenticate char username char password word server DESCRIPTION Authenticate user and return the user index representing the authenticated user that is the user table index This performs only a plaintext comparison of the userid and password Servers prob ably will have their own more sophisticated checks If username is NULL or empty string then password only matching is attempted for servers who allow this type of authentication as defined by the SERVER PASSWORD ONLY macro PARAMETERS username Name of user password Password for the user server The server for which this function is authenticating e g SERVER_HTTP SERVER_FTP RETURN VALUE 1 Failure or user not authorized 20 Succes
175. access this resource NB for backwards compatibility if this is set to zero then all servers are allowed method Authentication method s allowed combination of SERVER_AUTH_ bits Note that Zserver lib does not directly support anything other than ba sic authentication that is SERVER AUTH BASIC however the required information is stored here so that servers can access it as needed in a consis tent manner mimetype MIME type for this resource or NULL If NULL the MIME type will be derived from the file name using the MIMETypeMap table called http_types If not found in that table the first entry in that table will be used for backward compatibility Historical note Prior to Dynamic C 8 50 Ht tpRealm was used in place of ServerPermissions If you have used HttpRealm for password protection in existing code and are upgrading to Dynamic C TCP IP Manual Vol 2 rabbit com 35 8 50 or later you must rewrite any code that used this old structure For an example of the new way to password protect an entity see the sample program samples tcpip http authentication c 3 1 5 RuleEntry Structure This structure associates a resource name prefix with a ServerPermissions structure The rule table is an array of these structures prefix Prefix of resource name s which are associated with this rule table entry If there are multiple entries which match a resource name then the rule with the longest matching prefix is used perm
176. acter represents a wild card for the index value It is replaced with the index being checked in the expression int temps 20 web temps 50 lt Stemps amp amp Stemps lt 100 For example if temps 0 is being checked for errors the error checking expression becomes 50 lt Stemps 0 amp amp Stemps 0 lt 100 Alternatively it is possible to give each array element its own error checking expression int temps 3 web temps 50 lt S temps 0 amp amp Stemps 0 lt 100 amp amp 60 lt Stemps 1 amp amp S temps 1 lt 90 amp amp 70 lt Stemps 2 amp amp Stemps 2 lt 80 Note that the above statement spans lines The statement is continued on the next line by escaping the end of the line It is also possible to register and check array variables individually int temps 3 web temps 0 50 lt Stemps 0 amp amp Stemps 0 lt 100 web temps 1 60 lt Stemps 1 amp amp Stemps 1 lt 90 web temps 2 70 lt Stemps 2 amp amp Stemps 2 lt 80 Structures are also supported with error checking struct foo int a int b ha struct foo bar web bar 0 lt Sbar a amp amp Sbar a lt 10 amp amp 5 lt Sbar b amp amp Sbar b lt 5 TCP IP Manual Vol 2 rabbit com 261 Alternatively each structure element can be specified separately using the same structure definition as above and given
177. admin web alarm email groups all ro admin void main void int userid hum 50 hum_alarm 75 alarm_interval 60 strepv alarm email somebody nowhere org sock init initialize TCP IP stack hteep inich initialize web server Inet See _joetein M M Watjavskere salateinl tcp reserveport 80 sspec addrule admin Admin admin admin SERVER _ ANY SERVER AUTH BASIC NULL userid sauth_adduser harpo swordfish SERVER_ANY sauth setusermask userid admin NULL while 1 http handier 250 rabbit com RabbitWeb The source code walk through consists of blocks of code followed by line by line descriptions Particular attention is given to the RabbitWeb web and web groups statements which are new compiler direc tives define TCPCONFIG 1 define USE RABBITWEB 1 memmap xmem tause cleweejo lala use http lib The macro TCPCONFIG is used to set network configuration parameters Defining this macro to 1 sets 10 10 6 100 255 255 255 0 and 10 10 6 1 for the board s IP address netmask and gateway nameserver respectively If you need to change any of these values read the comments at the top of lib tcpip tcp config lib for instructions The USE RABBITWEB macro must be defined to 1 to use the HTTP server enhancements The define of USE RABBITWEB is followed by a request to map functions not flagged as root into xmem The two use statements allow t
178. al Ports There are predefined I O methods for all four of the serial ports on a Rabbit board The baud rate is set by passing it to the macro See above 472 rabbit com General Purpose Console 14 5 2 2 Telnet Zconsole runs a telnet server The port number is passed to the macro CONSOLE _IO_ TELNET The user telnets to the controller that is running the console 14 5 2 3 Slave Port The Rabbit slave port is an 8 bit bidirectional data port Zconsole runs on the slave processor Two drivers are needed Slave Port Driver The slave port driver is implemented by SLAVE PORT LIB For an application to use the slave port e The driver must be installed by including the library in the program e Acallto SPinit mode must be made to initialize the driver e A function to process Zconsole commands sent to the slave port must be provided The slave port has 256 channels separate port addresses that are independent of one another A handler function for each channel that is used must be provided For details on how to do this please see the Dynamic C User s Manual A stream based handler SPShandler to process Zconsole commands for the slave is provided in SP STREAM LIB The handler is set up automatically by the console when the slave port I O method is included The macro CONSOLE IO SP expands to the I O functions defined in SP_STREAM LIB Master Connected to Rabbit Slave Port The master controller board can be another Rabbit p
179. al timezone offset will be ignored For many reasons including the fact that daylight savings transitions are more manageable it is better to set the RTC to UTC however some users prefer the clock to run in local time See the documentation for rtc timezone for more details To do this use the function lookup fea ture in Dynamic C or refer to the Dynamic C Function Reference Manual 4 5 Sample Programs Sample programs demonstrating HTTP are in the Samples Tcpip Http directory There is a config uration block at the beginning of each sample program The macros in this block need to be changed to reflect your network settings Starting with Dynamic C 7 30 setting up the network addresses is both more complex and more simple The complexity lies in the added support for multiple interfaces Luckily for us the simplicity is in the interface to this more intricate implementation In the file tcp config lib are predefined configura tions that may be accessed by a define of the macro TCPCONFIG For instructions on how to set the con figuration please see volume 1 of the manual or LIB TCPIP TCP_CONFIG LIB 4 5 1 Serving Static Web Pages The sample program Static c initializes HTTP LIB and then sets up a basic static web page It is assumed you are on the same subnet as the controller The code for Static c is explained in the follow ing pages From Dynamic C compile and run the program You will see the LNK light on the board come
180. ameters will not have a value returned This is useful if you are only interested in certain variable information PARAMETERS start Pointer to the variable in the buffer for which we want to get information name Return location for the name of the variable value Return location for the value of the variable error Return location for whether or not the variable is in error 0 if it is not 1 if it is next Return location for a pointer to the variable after this one RETURN VALUE None although information is returned in the last four parameters LIBRARY HTTP LIB 220 rabbit com HTTP Server http parseform int http parseform int form HttpState state DESCRIPTION Parses the returned form information It expects a POST submission This function is useful for a developer who only wants the parsing functionality and wishes to generate forms herself Note that the developer must still build the array of FormVars and use the server_spec table This function will not however automatically display the form when used by itself If all vari ables satisfy all integrity checks then the variables values are updated If any variables fail then none of the values are updated and error information is written into the error buffer If this function is used directly the developer must process errors PARAMETERS form server spec index of the form i e location in TCP IP servers object list state The HTTP server with which t
181. amic resource tables The default setting is index html The value must not start or end with a character SOCK BUF SIZE This macro is not defined by default If you define it then it specifies the amount of extended memory to allocate xalloc for each HTTP server instance If you do not define it then socket buffers are allocated from the usual pool See tcp extopen for more details HTTP DIGEST NONCE TIMEOUT This macro is used whenUSE HTTP DIGEST AUTHENTICATION is set to one Nonces that are generated by the server are valid for this many seconds 900 by default If set to 0 nonces are good forever Setting this to a smaller value can possibly result in higher security although inter nal use of the nonce count facility offsets this Setting it to a larger value reduces the negotiation TCP IP Manual Vol 2 rabbit com 141 between the browser and the server since when a nonce times out the browser must be told that it is using a stale nonce value and provided with a new one Since Mozilla and Netscape ignore the stale parameter the user must reenter the username and password when a nonce times out In ternet Explorer and Opera respect the stale parameter so they automatically try the username and password with the new nonce without asking the user HTTP MAXBUFFER This is the size of the buffer accessible through the Ht tpSpec structure It defaults to 256 bytes The size of this buffer affects the speed
182. andard errors used by the built in commands in zconsole lib Users can define their own errors here as well const Consolcerror comsole errors 14 CON STANDARD ERRORS Da This array defines the information such as configuration that will be saved to the file system Note that if for example the HTTP or SMTP related commands are included in the console_commands array above then the backup information must be included in this array The entries below are macros that expand to the appropriate entry for each set of functionality Users can also add their own information to be backed up here by adding more ConsoleBackup structures const ConsoleBackup console backup CONSOLE BASIC BACKUP CONSOLE TCP BACKUP CONSOLE HTTP BACKUP CONSOLE SMTP BACKUP 490 rabbit com General Purpose Console The following code defines the MIME types that the web server will handle const HttpType http tvpesll shen text html chemli handler ssi U Ioemil Meesse lemilt NULL html gif image gif NULL u jpg Timege jpeg NULE 1 jpeg image jpeg NULL Weoce ee esc pl arm SNUEE E The function for the custom command is defined here and the main program finishes up the program To see the complete sample look in Samples zconsole tcpipconsole c This is a custom command Custom commands always take a ConsoleState as an argument a pointer to the state str
183. archy That is it should not start with s2 A B etc fileloc Pointer to the beginning of the file len Length of the file in bvtes servermask Bitmask representing servers for which this entrv will be valid e g SERVER HTTP SERVER FTP RETURN VALUE 1 Failure 20 Success file index into the resource list SEE ALSO sspec addfsfile sspec addxmemfile sspec addxmemvar sspec addvariable sspec addfunction sspec addform sspec aliasspec sspec resizerootfile 64 rabbit com Server Utilitv Librarv sspec addrule int sspec addrule char pfx char realm word readgroups word writegroups word servermask word method MIMETypeMap mimetype DESCRIPTION Add a rule to the dynamic resource rule table Resource rules are used to associate access infor mation with resource names matching the specified prefix string The most specific that is the longest matching string is used Normally the rule table is consulted only for resource names that belong in a file system FS2 or FAT You can also cause the rule table to be consulted for flash or RAM table entries if you leave the realm field as NULL in the entry If the realm field is not NULL then the rule table is not consulted for that entry If the realm field was NULL and there was no applicable entry in the rule table then the resource table permissions are used with NULL realm Do not attempt to use a very large number of rule table entries since the
184. as write permission This does NOT necessarily mean that the resource can actually be written only that the permission bits allow it lt 0 Error For example no permissions can be located or the sspec handle is invalid SEE ALSO sspec setpermissions sspec getpermissions sspec access 76 rabbit com Server Utilitv Librarv sspec close int sspec close int sspec DESCRIPTION Close a file resource This function must be called by servers when they have completed opera tions on the file otherwise there will be a resource leak and future open calls will fail PARAMETER sspec Open file handle This must be a handle that was returned by sspec open RETURN VALUE 20 Success The following return values are negatives of the values defined in errno lib e EBADF The specified handle was not open or invalid e Other negative values indicate an error in closing the file resource SEE ALSO sspec read sspec write sspec seek sspec tell sspec open TCP IP Manual Vol 2 rabbit com 77 sspec delete int sspec delete char name ServerContext context DESCRIPTION Delete a resource by name See sspec open for a detailed description of parameters PARAMETERS name Name of resource context Current server context RETURN VALUE 0 OK The following return value is a negative of the values defined in errno lib Any other nega tive values indicate an error e ENOENT The specified resource did
185. ate E2S PROCESS else if sock alive sock 4 The socket was established but then aborted by the peer e28 statelil state E2S INIT else socket was opened but is now closing Go to PROCESS state to read any data e2s statelil state H2S PROCESS break The function e2s tick drives the Ethernet to serial state machine Each time this tick function is called it loops through all of the serial ports first grabbing the socket structure that associates a particular serial port with a TCP port then determining which state is active for that TCP port There are three states in the Ethernet to serial state machine identified by e F2S INIT e F2S LISTEN e E2S PROCESS The first state E2S INIT opens the socket with a call to tcp listen and then sets the state vari able to be in the listen state The next time the tick function is called the E2S LISTEN state will execute TCP IP Manual Vol 2 rabbit com 283 The state machine will stay in this listen state until a connection to the socket is attempted a condition determined by a call to sock waiting As noted in the code comments above once a connection is attempted there are several stages it can be in which one will determine the next state of the Ethernet to serial state machine case E2S PROCESS Check if the socket is dead if sock_alive sock 628 _Sicaice i state 828 _ WNL Read from TCP socket and write to serial po
186. ated to HITP_MAXURL bytes the truncated information is also NULL terminated Use http getURL for new code version This should be treated as read oniv This holds the version of the HTTP re quest that was made It can be HTTP VER 09 HTTP VER 10 0r HTTP VER 11 for 0 9 1 0 or 1 1 requests respectively Use http getHTTPVersion for new code TCP IP Manual Vol 2 rabbit com 139 content tvpell This should be treated as read only This buffer holds the value from the Content Type header sent by the client Use http getContentTvpe for new code content length This should be treated as read only This variable holds the length of the content sent bv the client It matches the value of the Content Length head er sent by the client Use http getContentLength for new code has form This should be treated as read only If the value is 1 there is a GET style form after the XO byte inurl abort notify Set to 10 in user defined formprolog function to indicate that the formepilog function needs to be called on an abort condition If the epilog function is reached normallv this field must be set to zero This pre vents the formepilog function from being called one more time on a con nection abort cancel This should be treated as read only It is intended for when the user defined functions which may be called before and after an HTML form is submit ted are used for locking resources If the formprolog fun
187. ater than len This is interpreted as I have not put anything in buf Call me back when you the server can accept at least 1 en bytes of data This is useful for read handlers that find it inconvenient to retrieve data from arbitrary offsets for example a log reader that can only access whole log records If the returned value is greater than the server can ever offer then the server aborts the data transfer The handler should never ask for more than FTP MAXLINE bytes PARAMETERS fd The file descriptor returned when the file was opened buf Pointer to the buffer to place the file contents offset Offset in the file at which copying should begin len The number of bytes to read RETURN VALUE 0 EOF gt 0 The number of bytes read into buf 1 Error transfer aborted TCP IP Manual Vol 2 rabbit com 327 ftp dflt write int ftp dflt write int fd char buf long offset int len DESCRIPTION The default write handler does nothing but return zero The specification states that the handler may write the file identified by d buf contains data of length len which is to be written to the file at the given offset within the file The return value must be equal to Len or a negative number if an error occurs such as out of space The FTP server does not handle partial writes the given data must be completely written or not at all If the return code is less than 1 en an error is assumed to have occurred Note that it is u
188. ave their authentication method set to SERVER AUTH DEFAULT or none specified PARAMETERS auth Type of authentication Choices are e HTTP NO AUTH e HTTP BASIC AUTH e HTTP DIGEST AUTH RETURN VALUE Actual resulting type of authentication LIBRARY HTTP LIB TCP IP Manual Vol 2 rabbit com 225 http setCond int http setCond HttpState state int idx int val DESCRIPTION Set the value of an HTTP condition state variable aka cond variable There are HTTP MAX COND of these integer state variables thus idx must be between 0 and HTTP MAX COND I inclusive NOTE This is implemented as a macro PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function idx Index of cond variable 0 HTTP_ MAX COND 1 Validity is not checked val New value RETURN VALUE Returns the new value of the cond variable i e val LIBRARY HTTP LIB SEE ALSO http_getAction http_getCond 226 rabbit com HTTP Server http setcookie void http setcookie char buf char value DESCRIPTION This utility generates a cookie on the client This will store the text in value into a cookie generation header that will be written to buf The header placed in buf is not automatically sent to the web client It is the caller s responsibility to send the header in buf along with any other HTTP headers to the client When a page is requested from the client and the cookie is already set the
189. ay we ILO p else Read by the agent Convert internal to external xv 10 printf v out ld n v return 0 The callback function has the opportunity to manipulate the value including its length as well as say whether the write operation is allowed or not TCP IP Manual Vol 2 rabbit com 381 12 2 3 Creating Communities Before the MIB is created variables are defined and some initialization takes place int main auto snmp parms p auto snmp parms p auto word tt auto word trapindices 2 auto word monindex Set the community passwords snmp set dflt communities public private trap Set p to bea pointer to p for calling convenience p amp Dp Set parameter structure to default initial state required snmp init parms p There are three communities defined in this SNMP agent The public and private communities are defined by default and the trap community is defined with the inclusion of define SNMP_ TRAPS at the beginning of the program The configuration macro SNMP MAX COMMUNITIES limits the number of distinct community names It will be set to 3 in this SNMP agent It must be at least 1 To add another community call the API function snmp_add_community The return value of this function is used to set the password for the new community by passing it as a parameter to snmp set communitv Each new community requires SNMP_MAX COMMUNITIES to be increased by 1
190. b used prior to Dynamic C 8 50 is now syn onymous with this structure ServerSpec typedef struct word type char name SSPEC_MAXNAME long data void addr word vartype char format ServerPermissions perm ifdef FORM ERROR BUF endif ServerSpec The structure fields are described below The ifdef expression adds some fields to the ServerSpec structure if the HTML form functionality provided by Zserver is included by the web server application These fields are not described below For more details Section 4 5 4 HTML Forms Using Zserver lib Starting with Dynamic C 8 50 enhanced support is provided for HTML forms with the Dynamic C Rab bitWeb software RabbitWeb provides an easy to develop web interface for your embedded device and allows for complete flexibility in form layout See Chapter 5 for more information on this enhanced HTTP server In older versions of Dynamic C it was necessary to explicitly create the static resource table by doing something like this const HttpSpec http flashspec by in your main application code filling in the entries of course Starting with Dynamic C 8 50 there is new recommended syntax for creating these resources using the SSPEC_RESOURCETABLE series of mac ros This new method is recommended for maintaining future compatibility For more information see Section 3 2 5 3 Static Resource Table TCP IP Manual Vol 2 rabbit com 33 3 1 2 1 ServerSpec Fields T
191. being provided in the current connection Using redirect is less efficient however PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function newURL The resource name to present to the client This may be another CGI or any other type of resource that could be presented to the client in response to an HTTP GET or POST request The resource must exist in the flash or ram spec table or in a filesystem RETURN VALUE 0 LIBRARY HTTP LIB SEE ALSO http getAction http_skipCGI http_abortCGI http_finishCGI http write 242 rabbit com HTTP Server http urldecode char http urldecode char dest const char src int len DESCRIPTION Converts a string with URL escaped tokens such as 20 hex for space into actual values Changes into a space String can be NULL terminated it is also bounded by a specified string length This function is reentrant PARAMETERS dest Buffer where decoded string is stored sre Buffer holding original string not changed len Maximum size of string NULL terminated strings can be shorter RETURN VALUE dest if all conversion was good NULL if some conversion had trouble LIBRARY HTTP LIB SEE ALSO http_contentencode TCP IP Manual Vol 2 rabbit com 243 http write int http write HttpState state char data word length DESCRIPTION Write data back to the client This function either sends all of the given data or none of
192. big bold text This is specified by the second line The first line adds a title to the page which most browsers display in the window bar To see this web page on screen the user needs to tell their browser what to get If doing it manually they would need to enter something like http 10 10 6 100 hellowww htm in the browser s URL entry field The browser strips off the http 10 10 6 100 part of it and sends the rest to the specified host address 10 10 6 100 using a TCP connection to port 80 interpreted from the http part The server gets the hel lowww html part which it knows about since it has a page of that name and returns the contents of that file as a response The browser interprets the HTML it receives and generates a nice visual rendition of the contents TCP IP Manual Vol 2 rabbit com 5 2 3 Web Server Architecture Before describing a real application it is useful to know how such an application is organized The follow ing diagram shows all of the relevant components of a web enabled application There may seem to be a large number of components however keep in mind that not all components need to be used by your appli cation Figure 2 1 Components in a web enabled application Application Compile Time Run Time Main Application CGI Initialization Initialization Loop Specifics I O Functions web Variables Metadata SS ae ore l Requests i Resources Pan Table Zserver TCP IP
193. bit com 233 http sock gets int http sock gets HttpState state byte dp int len DESCRIPTION HTTP wrapper function for sock gets This function can be used by CGI applications to retrieve a string waiting on an ASCII mode socket associated with a particular HTTP server PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function dp Pointer to return buffer len Maximum size of return buffer RETURN VALUE 0 if buffer is empty or if no r or n is read but buffer had room and the connection can get more data gt 0 is the length of the string 1 error LIBRARY HTTP LIB SEE ALSO http_sock_mode 234 rabbit com HTTP Server http sock mode void http sock mode HttpState state http sock mode t mode DESCRIPTION HTTP socket wrapper function for socket mode This function can be used by CGI applications to set the mode of a socket associated with a particular HTTP server PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function mode HTTP mode to use for the socket Valid values for mode are e HTTP MODE ASCII Sets the associated socket to ASCII mode e HTTP MODE BINARY Sets the associated socket to BINARY RETURN VALUE None LIBRARY HTTP LIB TCP IP Manual Vol 2 rabbit com 235 http sock readable int http sock readable HttpState state DESCRIPTION HTTP wrapper function for socket readable funct
194. ble int sspec readvariable int sspec char buffer DESCRIPTION Formats the variable associated with the specified ServerSpec structure and puts a NULL ter minated string representation of it in buffer The macro SSPEC XMEMVARLEN default is 20 defines the size of the stack allocated buffer when reading a variable in xmem PARAMETERS sspec spec index buffer The buffer in which to put the variable RETURN VALUE 0 Success 1 Failure SEE ALSO sspec getvaraddr sspec remove int sspec remove int sspec DESCRIPTION Removes a spec entrv bv marking it unused In the case of files note that this function does not actually remove the file only the reference to the file in the spec structure This only works for RAM table entries PARAMETERS sspec spec index RETURN VALUE 0 Success 1 Failure i e the index is already unused TCP IP Manual Vol 2 rabbit com 113 sspec removerule int sspec removerule char pfx DESCRIPTION Remove a rule from the dynamic resource rule table PARAMETER pfx Prefix of resource name This must be an exact match to one of the rules pre viously added using sspec addrule RETURN VALUE 20 OK 1 Error For example the rule was not found or maybe the rule was in the flash table f rule table SEE ALSO sspec addrule 114 rabbit com Server Utilitv Librarv sspec removeuser int sspec removeuser int sspec int userid DESC
195. ble is a list of all resources that the server can access In this case the server has knowledge of two resources named and index zhtm1 When either of these is requested the config zhtml file is served The file extension zhtm1 identifies the file as containing server parsed tags vord restart Ockert ime 3 p void update _tcp void voL restart erial dme 3 p void update_serial void void serial opena ime il weacl e26 imit VOLE WOLC e26 tiek wouLel These are the function declarations They will be defined later in the program TCP IP Manual Vol 2 rabbit com 275 Struct SerialPort 4 word tcp port struct ePar riport long baud int databits int parity int stopbits ser hg ptruct Serialrore serial ports sizeor ports Cont Le p struct SerialPort serial ports copy sizeof ports config The SerialPort structure has fields for the configuration information for each serial port and TCP port pair The serial ports array and its copy stores configuration information about the serial ports serial ports copv L is used to determine which port information changed when the update func tion is called web serial _ports tcp port Sserial_ports tcp port gt 0 web serial ports ser port The first web statement is registration for the TCP port Note that the only rule in the guard is that the new value must be greater than zero The next web statement registers the
196. bove The other change on this page is the NAME attribute in the first INPUT tag of the second form When uploading to an FS2 partition the mount point fs2 must be prepended to the filename The ext1 part is also prepended to the filename and refers to the second flash The default CGI function can now store an uploaded file in a valid FS2 partition TCP IP Manual Vol 2 rabbit com 29 30 rabbit com Web Enabling Your Application RABE Tete 3 SERVER UTILITY LIBRARY This chapter is intended to be a detailed description of the resource manager Zserver and how it interfaces to other libraries such as servers HTTP FTP etc and filesystems FS2 FAT For an overview please see Chapter 2 Web Enabling Your Application The resource manager Zserver lib contains the structures functions and constants to allow HTTP Hypertext Transfer Protocol and FTP File Transfer Protocol servers to share data and user authentica tion information while running concurrently In general you do not need to know some of the details of Zserver described in this chapter if you are using the server libraries provided with Dynamic C Such sections are marked as advanced and you may skip them unless you are writing a server or filesystem Some sections are marked historical They are included to describe how previous versions of the library worked These may be skipped for new code The basic facility provid
197. cal file name but this is just a con vention Content Type text plain Content Type indicates the type of information The default is plain i e ascii text however it could also be set to image gif for a GIF file text html for HTML etc The following blank line indicates the end of headers for this part test file contents first line This is the actual file or form field content 3vAL1QsFOUg2GSY3p6n3 YQ The boundary string terminates the data for the previous part Headers for the next part immediately follow Content Disposition form data name submit This is form field data in this case the submit button itself upload 3vAL1Q0s FOUg2GSY3p6n3 YQ The boundary terminates the previous form field Since this is the last boundary it also has a trailing When writing the CGI you do not have to worry about parsing the headers and boundary separators This is already done by the HTTP server However you do need to be aware of the stream oriented nature of the incoming data The HTTP server separates out the parts and parses the headers As it does this it calls the defined CGI with the data for each section TCP IP Manual Vol 2 rabbit com 169 Action Codes Received by a CGI Function The CGI is called in a number of different contexts It determines the context by calling the http getAction function The return value of http getAction indicates the reason that the CGI is being called by the HTTP server For
198. can support Each server requires a significant amount of RAM 4096 bytes by default though this can change through SOCK BUF SIZEortcp MaxBufSize deprecated FTP NODEFAULTHANDLERS This macro is undefined Define it to eliminate the code for the default file handlers You must then provide your own file handlers This macro is no longer needed starting with Dynamic C ver sion 7 20 322 rabbit com FTP Server FIP TIMEOUT The default is 16 the number of seconds to wait for FTP commands from the remote host before terminating the connection In a high latencv network this value may need to be increased to avoid premature closures FTP USE FS2 HANDLERS Define this to enable the full use of FS2 in the default FTP handler functions Defining this macro will automatically define FTP_WRITABLE FILES to 1 as well FTP USERBLOCK OFFSET This macro should be defined to a number that specifies the offset into the User block at which the list of filenames will be saved This list correlates the filenames with the locations of the files in the filesystem FS2 This macro defaults to 0 If the user is putting other information in the User block this offset may need to be adjusted to prevent clobbering the other data FTP WRITABLE FILES The defaults is 0 Define to 1 to provide support in ftp dflt open for authenticating a user for write access before a file is opened This also provides support in the file listing function ftp _df1t_list to
199. ceptual level 12 1 SNMP Overview The SNMP model is client server based The SNMP agent is the server part passively listening for com munication from an SNMP manager the client side of things The SNMP manager which runs on a Net work Management Station NMS may make one of three possible requests Get GetNext or Set These requests are made via SNMP messages SNMP allows managers and agents to exchange SNMP messages for the purpose of sharing information about managed objects The messages are embedded in UDP datagrams for transmission Their format is shown in Figure 12 12 Figure 12 12 SNMPv1 Message Format version community PDU s version version of SNMP being used 1 2 or 3 community used for trivial authentication PDU stands for Protocol Data Unit another name for a packet These are generated and parsed internally A PDU contains the type of message get getnext set response or trap and a list of affected objects called the variable binding The variable binding is a list of name and value pairs either to get or to set TCP IP Manual Vol 2 rabbit com 373 12 1 1 Managed Objects A managed object can be a device or a device characteristic e g the value of a temperature gauge the setting of a switch or any other logical or physical component of an embedded system Instances of managed objects are kept in a Management Information Base MIB Each managed object has a unique name which is
200. char dest int maxlen DESCRIPTION This function allows you to scan a buffer with a POST response for the key value pairs This func tion is reentrant PARAMETERS tag Buffer holding the tag name buffer Buffer to read data from dest Buffer to store value to maxlen Size of destination buffer RETURN VALUE 0 Successful 0 Not successful LIBRARY HTTP LIB TCP IP Manual Vol 2 rabbit com 223 http set anonymous int http set anonvmous int uid DESCRIPTION Set the anonymous user ID This is the assumed user ID when no credentials are provided by the client browser A tvpical use of this function would be int anon anon sauth_adduser anonymous SERVER FTPISERVER HTTP sauth setusermask uid WORLD GROUP NULL http set anonvmous uid ftp set anonvmous uid if using FTP too which defines an anonymous login for the HTTP and optionally the FTP servers Since FTP also requires an anon user you can use the same user ID for both FTP and HTTP When a web browser initially requests a resource it may not pass any user credentials i e user name and password The HTTP server will assume that the user is anonymous and apply the ac cess permissions tests on that basis If access is denied then the browser will prompt the user for a real user name and password and the request will be re tried You do not always need to define an anonymous user to HTTP But it is required if yo
201. character representing the serial port in this case E or F web serial ports ser baud serial_ports ser baud gt 300 1 WEB ERROR too low web serial ports ser baud serial_ports ser baud lt 115200 ili WEB ERROR too high These two web statements correspond to the baud rate The guards are split into two so that the WEB_ERROR feature can be used The string passed to WEB_ERROR can later be used in the ZHTML scripting to indicate why the guard statement failed irwol Seielell joes l ser ceicaloilics selece 7 7 Vs B PUED serial porre lel ser parity eelect WNoneY 0 Vayent cleliuy mielo serial pores lel ser stogoite selecte 1 1 TAY 2 These are selection variables They limit the available options for serial port configuration parameters 276 rabbit com RabbitWeb web update serial portslel tcp port update tcp web_ update serial ports ser baud serial_ports ser databits serial ports ser stopbits update serial The web_ update feature will initiate a function call when the corresponding variables are updated Note that update tcp will be called when the TCP port changes and update_serial will be called when any of the other serial port configuration parameters are updated define AINBUFSIZE SERINBUFSIZE define AOUTBUFSIZE SEROUTBUFSIZE define BINBUFSIZE SERINBUFSIZE define BOUTBUFSIZE SEROUTBUFSIZE define CINBUFSIZE SERIN
202. ck EXAMPLE The program Samples tcpip smtp smtp dh c makes use of this function 358 rabbit com SMTP Mail Client smtp mailtick int smtp mailtick void DESCRIPTION Repetitively call this function until e mail is completely sent RETURN VALUE SMTP SUCCESS e mail sent SMTP_PENDING e mail not sent yet call smtp_mailtick again SMTP TIME e mail not sent within SMTP_ TIMEOUT seconds SMTP_UNEXPECTED received an invalid response from SMTP server SMTP_DNSERROR cannot resolve server name SMTP ABORTED transaction aborted by data handler If using SMTP AUTH the following values are also possible SMTP AUTH UNAVAILABLE unable to attempt authenticationi SMTP AUTH FAILED attempts to authenticate failed LIBRARY SMTP LIB SEE ALSO smtp sendmail smtp status TCP IP Manual Vol 2 rabbit com 359 smtp sendmail void smtp sendmail char to char from char subject char message DESCRIPTION Start an e mail being sent This function is intended to be used for short messages that are entirely constructed prior to being sent If you have previously installed a data handler via smtp_data_handler then you must call smtp data handier witha NULL data handler otherwise this message will not get sent NOTE The strings pointed to by the parameters must not be changed until the entire process is completed Also if the first character of any line of the message is a period then this c
203. com 409 snmp get next snmp parms snmp get next snmp parms p DESCRIPTION Retrieves the next object in lexicographically ascending sequence The object information is stored in p and can be examined using the snmp last series of functions The object ID of the retrieved object may be obtained by calling snmp_copy_oid The object ID is au tomatically set in p so this function can be called repeatedly to retrieve all objects in ascending sequence of object ID PARAMETERS p Parameter structure that was previously initialized by calls to snmp init parms snmp set stem etc RETURN VALUE NULL if p was NULL or if there is no next object Otherwise returns p LIBRARV MIB LIB SEE ALSO snmp init parms snmp set stem snmp append stem snmp copv oid snmp get snmp get indexed snmp last int snmp last long snmp last mem snmp last xmem snmp last tvpe snmp last len 410 rabbit com SNMP snmp init parms snmp parms snmp init parms snmp parms p DESCRIPTION Initialize the parameter structure p This is used to set p to a known state prior to calling other functions in the MIB group If p is not NULL it is set to all binary zeros The initial OID stem is then set to 43 6 1 4 1 or if SNMP ENTERPRISE is defined it is set to 43 6 1 4 1 SNMP ENTERPRISE Note that the leading 43 is the standard compression of 1 3 The current read and write masks are set to SNMP DEFAULT READMASK and SNMP D
204. controls web vari ables are not strictly resources they are included as parts of other resources however they can be assigned some access controls of their own In this example access to the variable is being set to require basic authentication and the allowable user groups are both of the defined groups with the proviso that the monitor group is to be allowed read only access The last major change is in the main function where some runtime initialization needs to be per formed Since the user ID table cannot be statically initialized i e at compile time this is a necessary step The rule table can be statically initialized but in this example we choose to do it at runtime First the rule table entry sspec addrule index html Pet admin grouplmonitor group 0 SERVER HTTP SERVER AUTH BASIC NULL The first parameter specifies the name of the resource to which this rule applies or rather the first charac ters in the resource name For clarity the sample shows the full name In practice since there is only one resource it would be acceptable to use just instead of index htm1 The second parameter Pet is an arbitrary string called the realm This is presented to the browser s user when prompted for the password as shown in Figure 2 5 Figure 2 5 Enter Network Password 121X gt Please type your user name and password Site 10 10 4 22 Realm Pet User Name Pa
205. cros Many macros are available to change the behavior of Zconsole They are all listed here Starting with Dynamic C 7 30 additional macros are available to support saving configuration information to the User block DHCP ping configuration and multiple interfaces CON BACKUP FILE1 The file number used for the first backup file For FS1 this number must be in the range 128 143 sothatfs reserve blocks can be used to guarantee free space for the backup files De faults to 128 for FS1 Defaults to 254 for FS2 CON BACKUP FILE2 Same as above except this is for the second backup file Two files are used so that configuration information is preserved even if the power cvcles while configuration data is being saved For FS1 this number must be in the range 128 143 Defaults to 129 for FS1 Defaults to 255 for FS2 CON BACKUP USER BLOCK Defaults to not defined If this is defined then configuration information for the console will be saved to the User block instead of to the flash file system Note that the configuration is only safe in the case of power failures with a version 3 or higher System ID block CON BUF SIZE Changes the size of the data buffer that is allocated for each I O method If the baud rate or transfer speed is too great for the console to keep up then increasing this value may help avoid dropped characters It is allocated in root data space It defaults to 1024 bytes CON CMD SIZE Changes the size of the command buffer
206. ction was called and then the connection is aborted before the formepilog function can be called cance is set to 1 and the formepilog function is called exactly once If the epilog function was al ready called but returned zero not finished yet then it is called again if the connection is aborted except if cgi redirectto has been called from the epilog function In that case the epilog function is not called after an abort username Read only buffer has username of the user making the request if authenti cation took place Note New code should use the http getContext macro then use the results to look up the user details using the sauth functions See the documentation for the ServerContext Structure in the previous chapter password Read only buffer has password of the user making the request if authenti cation took place See the above note cookie Read only buffer contains the value of the cookie DCRABBIT see http setcookie for more information 140 rabbit com HTTP Server headerlen headeroff These variables can be used together to cause the web server to flush data from the buffer array in the HttpState structure headerlen should be set to the amount of data in buffer and headeroff should be set to 0 to indicate the offset into the array The next time the CGI function is called the data in buffer will be flushed to the socket For new code consider writing a new style CGI function
207. ctory must already exist If not the upload will fail TCP IP Manual Vol 2 rabbit com 193 http defaultCGI cont 3 To add user authentication and other facilities there are three possible things to pro tect e The web page containing the form Give read access only to those users who could conceivably upload the files specified therein e The CGI itself this function Protect as for a e The uploaded resource You should set up a rule allowing write access only to the intended user s When defining user IDs which can use the upload do not forget to give those users overall write access using for example sauth_setwriteaccess uid SERVER_HTTP Be aware that rogue clients could easily change the resource name to something other than the one that was intended in the original form This is why resource protection is important Having done these three things the HTTP server is now set up to automatically place uploaded files in the filesystem Note that this CGI is limited to placing files into fixed resource locations as specified by the field name of the INPUT element If you need more sophisticated control you may wish to write your own CGI function using the code of this one as a starting point This CGI also presents a default status web page back to the client This page indicates whether the upload was successful the number of bytes uploaded and a link to test out the new file as suming it is som
208. cture is set up by the caller s Returned data This is a pointer to the following structure which will be filled in on return typedef struct word flags See below long mdtm Date time SEC_TIMER format long length Current file size long maxlength Max allowable file size ServerPermissions perm See below SSpecStat The flags field can be one of the following e SSPEC_ATTR_MDTM Modification date time e SSPEC_ATTR_LENGTH Current length e SSPEC_ATTR_WRITE File is writable e SSPEC ATTR EXEC File is executable e SSPEC ATTR HIDDEN Hidden attribute bit e SSPEC ATTR SYSTEM System attribute bit e SSPEC ATTR ARCHIVE Archive attribute bit e SSPEC ATTR DIR This is directorv name e SSPEC ATTR COMPRESSED Compressed format e SPEC ATTR MAXLENGTH Have maximum length e SSPEC ATTR SEEKABLE Randomly accessible e SSPEC ATTR EXTENSIBLE File may be expanded at end TCP IP Manual Vol 2 rabbit com 133 sspec stat cont The ServerPermissions structure is defined as follows typedef struct word readgroups word writegroups word servermask char realm char method ServerPermissions Read or write permission is granted for readgroups or writegroups if current ServerAuth mask i e userid entrv group mask matches in at least one bit position Bit is set in servermask field for each server that can access the resource Realm string of the resource only us
209. cution Choices 483 14 7 Backup Svstem seen 484 We ine Os oscars scenctiacatacenseedestietideeeains 44 p gt y 3 Telne i 9 14 7 1 Data Structure for Backup Svstem 13 1 Telnet Dynamic C 7 05 and Later 449 484 13 1 1 Setup 449 14 7 2 Array Definition for Backup System 13 1 2 API Functions Dynamic C 7 05 and 485 Later om 14 8 Zconsole Macros ena 486 vserial close eeeenenennnnnnn 450 vSerial_init c ccccccccsesseeseesessessesesseeee 451 14 9 Sample Program ssssreriisvasensesresoesss 488 vserial_keepalive mn 451 be a TO 452 TG OX E E EE 493 vserial OPEN eee nn enn 453 vserial tik enesnenennennnn 454 13 2 Telnet pre Dynamic C 7 05 455 13 2 1 Configuration Macros 455 TCP IP User s Manual Vol 2 rabbit com vi rabbit com Table of Contents RABE Tete 1 INTRODUCTION The Dynamic C TCP IP User s Manual Vol 2 is intended for embedded system designers and support professionals who are using a Rabbit based controller board Most of the information contained here is meant for use with Ethernet or WiFi enabled boards but using only serial communication is also an option Knowledge of networks and TCP IP Transmission Control Protocol Internet Protocol is assumed For an overview of these two topics a separate manual is provided An Introduction to TCP IP A basic understanding of HTML HyperText Markup Language is also assumed For information on this subject there are numerous
210. d The FORM and INPUT tags are used to create forms in HTML The FORM tag specifies which elements constitute a single form and what CGI program to call when the form is submitted The FORM tag has an option called ACTION This option defines what CGI program is called when the form is submitted when the Submit button is pressed The FORM tag also has an option called METHOD that defines the method used to return the form information to the web server In Section 4 5 3 1 the POST method is used which will be described later All of the HTML between the lt FORM gt and lt FORM gt tags define what is contained within a form Starting with Dynamic C 8 50 you can also use the enctype option inside the FORM tag This specifies a return encoding type for the form s information If you did not specify this option then you can use old style CGIs as described in this section If you specify enctype multipart form data then you should specify a new style CGI instead See Section 4 6 describing the HTTP upload feature for more details on writing a new style CGI TCP IP Manual Vol 2 rabbit com 153 The INPUT tag defines a specific form element the individual input fields in a form For example a text box in which the user may type in a value or a pull down menu from which the user may choose an item The TYPE parameter defines what type of input field is being used In the following example in the first two cases it is the text inpu
211. d IP to connect to port Port to connect to typically 80 file Filename to request should start with auth Optional username and password separated with to authenticate with or NULL for no authentication postdata Data to post already URL encoded postlen Length of data to post typically strlen postdata contenttype String to send as Content Type Use NULL for default of application x www form urlencoded RETURN VALUE 0 Success EIO couldn t write to socket NETERR_DNSERROR Can t resolve hostname E2BIG Buffer full trying to create HTTP request SEE ALSO http post url httpe post TCP IP Manual Vol 2 rabbit com 305 httpc post url int httpc post uri httpc Socket far s const char far url const char far postdata word plen const char contenttype DESCRIPTION Connect to resource at url and POST plen bytes of postdata PARAMETERS s Pointer to socket structure to use for connection url URL in the following format items in are optional http user pass hostname port filename postdata Data to post already url encoded plen Length of data to post typically strlen postdata contenttype String to send as Content Type Use NULL for default of application x www form urlencoded RETURN VALUE 0 Success EINVAL Error parsing URL E2BIG URL is too big to parse Increase URL MAX BUFFER SIZE to handle larger URLs NETERR_DNS
212. d and processed separately Could they be processed as one form Yes but from a modular design perspective it makes sense to keep the form submissions separate when the purpose of each form is entirely separate You may have noticed that no security was added to protect the filesystem anyone can upload a file that passed the initial user and password protection that limits access to the web page This is probably not the ideal situation Typically there needs to be some limit placed on who is able to write to the filesys tem When considering security there are three possible things to protect e The web page that contains the form Give read access only to those users who could conceivably upload the files specified therein e The CGI itself Protect the same as the web page e The uploaded resource You should set up a rule allowing write access only to the intended user s When defining user IDs that can use the upload don t forget to give those users overall write access using e g sauth_setwriteaccess uid SERVER HTTP Another way to design this application is to have a separate HTML file that contains the form for the file upload then instead of having the form for the file upload on the current HTML page you put a link to the new page and then apply a permission to allow the new page to be displayed such as sspec_addrule newpage html Pet admin group admin group SERVER HTTP SERVER AUTH BASIC NULL
213. define define define define MY IP ADDRESS 10 10 6 106 MY NETMASK 255 255 255 0 MY GATEWAY 10 10 6 19 MY NAMESERVER 10 10 6 19 SERIAL PORT SPEED 115200 Must match server undef TELNET COOKED memmap xmem tuse dertep lib use vserial lib define SERVER_PORT 0 Defaults to port 23 must match server define REM_HOST 10 10 6 19 Remote IP to connect to main sewele dmit Mnitialize the stack Tell the server to connect and reconnect if the connection is lost telnet_init TELNET RECONNECT resolve REM HOST SERVER_PORT while ltelnet tick Run client this is non blocking continue telnet close Error close telnet connection 458 rabbit com Telnet RABE Tete 14 GENERAL PURPOSE CONSOLE The library zconsole lib implements a serial based console that we call Zconsole It can be used to e Configure a board e Upload and download web pages e Change web page variables without re uploading the page e Send e mail e Calls subsystem initialization for ARP TCP UDP and DNS if applicable 14 1 Zconsole Features Recognizing that embedded control systems are wide ranging in their requirements zconsole lib was designed with flexibility and extensibility in mind Designers can choose the available functionality they want and leave the rest alone Zconsole includes e Login name and password protection e Default and custom Zconsole commands e Defau
214. denied a protected resource On receipt of user credentials name and pass word the HTTP server consults the resource manager which in turn looks up the rule table to see if the user s credentials are OK If they are then the resource manager also determines the group s of which this user is a member Thereafter all access and permission checking is based on the group not the individual user 3 Return the resource Having verified the group access rights if necessary the resource is transmitted back to the user The resource may be an HTML or image file obtained from program memory or a file system or it may be a script file that is processed on the fly to generate markup language It may even represent a CGI function that will be called to generate all the necessary response Note that a complete response requires a small amount of header information to be prefixed to the actual resource The HTTP server usually takes care of this however CGIs sometimes need to generate the header themselves Referring to the diagram in Figure 2 1 you can see that there are several arrows leading in and out of the HTTP server block These represent lines of communication and the arrow heads indicate the usual direc tion of data flow or for function calls who calls whom 1 This is a necessary optimization There may be hundreds of individual users however the majority of these would be considered to be in a single class
215. dicate an error SEE ALSO sspec close sspec read sspec seek sspec tell sspec open TCP IP Manual Vol 2 rabbit com 111 sspec readfile int sspec readfile int sspec char buffer long offset int len DESCRIPTION Read a file represented by the sspec index into buf fer starting at of f set and only copy ing len bytes For xmem files this function automatically skips the first 4 bytes Hence an offset of 0 marks the beginning of the file contents not the file length This function is intended for file types that do not require explicit open or close calls that is root or xmem files It can also be called for FS2 files but this is not recommended since each call re quires the file to be opened seeked read then closed Instead use sspec_open sspec read and sspec close calls which are the most efficient sspec readfile has the advantage of being stateless but the price to pav is great loss of efficiency especially when sequential access is all that is required This function will NOT work for compressed xmem files or DOS FAT files PARAMETERS sspec spec index buffer The buffer to put the file contents into offset The offset from the start of the file in bvtes at which copving should begin len The number of bytes to copy RETURN VALUE 1 Failure 20 Success number of bytes copied SEE ALSO sspec getlength sspec getfileloc 112 rabbit com Server Utilitv Librarv sspec readvaria
216. dress as they do for the near pointers used by snmp add maxlen Maximum permissible length of the object RETURN VALUE Returns p unless p is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp _ init parms snmp set stem snmp set parse stem snmp append stem snmp_append parse stem snmp set access snmp set callback snmp up stem snmp add snmp delete snmp get snmp last index TCP IP Manual Vol 2 rabbit com 447 448 rabbit com SNMP RABE Tete 13 TELNET The library Vserial lib implements the telecommunications network interface known as telnet The implementation is a telnet to serial and serial to telnet gateway This chapter is divided into two parts The first part describes the library from Dynamic C version 7 05 and later The second part describes the library prior to 7 05 13 1 Telnet Dynamic C 7 05 and Later This implementation is more general than the previous one Any of the four serial ports can be used and other I O streams can be added Multiple connections are supported by the use of unique gateway identifi ers 13 1 1 Setup To use a serial port the circular buffers must be initialized For instance if serial port A is used by an application then the following macros must be defined in the program define AINBUFSIZE 31 define AOUTBUFSIZE 31 It might be necessary to have bigger buffers for some applications 13 1 1 1 Low Level Serial Ro
217. ds For instance if the data must be secret you can require that it only be updated via SSL You can also make cer tain variables be read only for certain user groups Valid user groups and authentication methods can be specified as follows web foo foo gt 0 auth basic digest ssl groups admin users ro By default all authentication methods and user groups are allowed to update the variable That is to limit access to the variable you must include the applicable auth or groups parameters when registering the variable none is a valid authentication method 264 rabbit com RabbitWeb If foo is a structure or array the protection modes are inherited by all members of the structure or array unless specifically overridden with another web statement If a received variable fails a security check then the client browser will be given a Forbidden access page 5 2 4 Handling Variable Changes Receiving checking and applying the variable changes works well when the program does not immedi ately need to know the new values For instance if we are updating a value that represents the amount of idle time needed on a serial port before sending the queued data over the Ethernet the program does not need to know the new interval value immediatelv it can just use the new value the next time it needs to do the calculation But sometimes the program must perform some action when values have been updated For example if a ba
218. e A simple scripting language consisting of server parsed tags added to the HTML page that contains the form e Dynamic C language enhancements which includes new compiler directives that can be added to the application calling the HTTP server Section 5 1 presents a simple example to show the power and ease of developing a RabbitWeb server that presents a web interface to your device This example gives step by step descriptions of the HTML page and the Dynamic C code New features will be briefly explained then linked to their comprehensive descriptions in Section 5 2 and Section 5 3 These sections are followed by a more complex example in Section 5 4 which in turn is followed by quick reference guides for both the Dynamic C language exten sions and the new scripting language which is called ZHTML Section 5 5 5 1 Getting Started A Simple Example In this example we pretend that a humidity detector is connected to your Rabbit based controller Your controller runs a web server that displays a page showing the current reading from the humidity detector From this monitoring page there is a link to another page that contains an HTML form that allows you to remotely change some configuration parameters This example introduces web variables and user groups It also illustrates some new security features and the use of error checking This example assumes you have already installed Dynamic C version 8 5 or later and hooked up a Rab bit bas
219. e FS2 file number 99 has a complete resource name of fs2 file99 If fat 1ib is included then all DOS FAT files are mounted under a drive letter The first par tition of the first DOS FAT filesystem is called A and the second partition if any is called B etc For example if the FAT filesystem has a file called system admin htm then the complete resource name will be A system admin htm NOTE Forward slashes are required Do not use backslashes as is customary with DOS file systems If the resource name does not begin with fs2 or A etc then the resource is located in the static resource table flashspec that is the http flashspec global table or in the dynamic RAM table To access the file resource the return value from this function must be passed to other functions suchas sspec_read A few functions do not work with resources opened with this function These cases are documented with the function NOTE When the application has finished accessing the resource it must be closed using sspec_close This must be done because there is a limited amount of storage for main taining the necessary file handles PARAMETERS name Resource name as a NULL terminated string This name is assumed to be relative to context gt cwd if it does not begin with a character Oth erwise the name is assumed to be relative to context gt rootdir Note that the name string can contain
220. e Filename to get put dir Directory file is in NULL for default directory buffer Buffer to get put the file from to Must be NULL if a data handler function will be used See ftp data handler for more details length On upload length of file on download size of buffer This parameter limits the transfer size to a maximum of 32767 bytes For larger transfers it will be necessary to use a data handler function RETURN VALUE 0 Success 1 Failure LIBRARY FTP CLIENT LIB SEE ALSO ftp client setup_url ftp client tick ftp data_handler 314 rabbit com FTP Client ftp client setup url int ftp client setup uri const char far url int mode char buffer int length DESCRIPTION Sets up a FTP transfer It is called first then ftp client tick is called until it returns non zero PARAMETERS url URL to download mode Mode of transfer e FTP MODE UPLOAD e FTP MODE DOWNLOAD You may also OR in the value FTP_MODE_PASSIVE to use passive mode transfer important if you are behind a firewall Use FTP MODE GETLIST if you just want to retrieve the file information given by LIST filename If FTP MODE GETLIST is used with a NULL filename the the results of LIST are given These results may just be a list of file names or they may contain more information with each file this is server dependent buffer Buffer to get put the file to from Must be NULL if a data handler function will be used See ftp data handler for m
221. e MAX FORMSIZE 64 typedef struct char name char value MAX FORMSIZE FORMType FORMType FORMSpec 2 void init_forms void HORMS OSS LOJ mame Use meme 5 DORMS OSE LLI mame VUSET EimesIL Reading amp Storing URL encoded Data parse post is called from the CGI function submit to read URL encoded data off the net work It calls http scanpost to store the data in FORMSpec These code snippets are from Samples tcpip http post c int parse post HttpState state auto int retval auto int i retval sock _aread amp state gt s state 9p X state gt content_length lt HTTP MAXBUFFER 1 int state content length HITP MAXBUFFER 1 LE erval lt return 1 state gt subsubstate retval if state gt subsubstate gt state gt content_length state gt buffer int state gt content_length 0 for i 0 i lt sizeof FORMSpec sizeof FORMType i http_scanpost FORMSpec i name state gt buffer FORMSpec i value MAX FORMSIZE return 1 return 0 156 rabbit com HTTP Server 4 5 3 4 Sample of a CGI Handler This next function is the CGI handler that calls parse post It is a state machine based handler that generates the page It calls parse post and references the structure that is now filled with the parsed data we wanted This function is from Samples tcpip http post c int submit HttpState state auto int i if sta
222. e conditionally included if HTTP forms are in use These are not gener ally relevant See the library source for details 34 rabbit com Server Utility Library 3 1 3 ServerAuth Structure This structure defines a global array that is a list of user name password pairs ServerAuth server auth SAUTH MAXUSERS Throughout this manual this array is called the user table The fields in the ServerAuth struct are manipulated using the sauth_ functions The description below is for reference only username Name of user or password Password or mask Group mask writeaccess Which servers this user has write access to servermask Which servers this user is visible to data Arbitrarv data application dependent 3 1 4 ServerPermissions Structure This data structure holds access permissions for a resource or a group of resources An instance of ServerPermissions is contained in each ServerSpec structure as well as within each rule table entry The fields for the ServerPermissions struct are realm Pointer to realm string of the resource It is only used by HTTP servers but can be used for other purposes readgroups Read permission is granted if the current ServerAuth mask value matches in at least one bit position writegroups Write permissions is granted if the current ServerAuth mask value matches in at least one bit position and ServerAuth writeaccess is set servermask A 16 bit mask with a bit set for each server that can
223. e form has been successfully submitted This function can for example execute a cgi_redirectto to redirect to a specific page It should accept HttpState state as an argument return 0 when it is not finished and 1 when it is finished i e behave like a normal CGI function PARAMETERS form spec index of the form function spec index of the function to call when the specified form has been success fully submitted This is the return value of the function sspec addfunction RETURN VALUE 0 Success 1 Failure SEE ALSO sspec setformprolog TCP IP Manual Vol 2 rabbit com 119 sspec setformfunction int sspec setformfunction int form void fptr DESCRIPTION Sets the function that will generate the form PARAMETERS form spec index of the form fptr Form generation function NULL for the default function RETURN VALUE 0 Success 1 Failure sspec_setformprolog int sspec_setformprolog int form int function DESCRIPTION Allows a user specified function to be called just before form variables are updated This is useful for implementing locking on the form variables which can then be unlocked in the epilog func tion so that other code will not update the variables during form processing The user specified function should accept HttpState state as an argument return 0 when it is not finished and 1 when it is finished i e behave like a normal CGI function PARAMETERS form spec index
224. e function prototype for a custom command must be declared before the console_command array x inte Mello worlcl Consolebtate sea ee 488 rabbit com General Purpose Console The following code is for Zconsole configuration The number of console I O streams that this program supports Since we are supporting serial port C and telnet there are two I O streams define NUM_CONSOLES 2 fi If this macro is defined then the version message will be shown with the help command when the help command has no parameters define CON HELP VERSION Defines the version message that will be displayed in the help command if CON HELP VERSION is defined e define CON VERSION MESSAGE TCP IP Console Version 1 0 r n Defines the message that is displayed on all I O channels when the console starts x define CON INIT MESSAGE CON VERSION MESSAGE The ximport directives include the help texts for the console commands Having the help text in xmem helps save root code space ss ximport samples zconsole tcpipconsole help help txt help txt The rest of the ximport statements may be seen in tcpipconsole c TCP IP Manual Vol 2 rabbit com 489 The following code sets up all the data structures needed by the console The console will be available to the I O streams given in the following array The I O streams are defined through macros as documented in Section 14 5 2 The parameter for t
225. e may be chosen from SNMP ERR definitions in which case the val ue is used as the error type for the response Otherwise SNMP ERR genErr is used Read callbacks are used for SNMP get get next requests as well as immediately after SNMP set requests where the updated value of the variable is read back for generating the response The return code for read callbacks is currently ignored but should be set to zero for OK or non zero for invalid if applicable to allow upward compatibility 12 2 2 1 Callback Function Example A callback function may be used for special actions that must be taken when a variable is written by the SNMP agent such as creating entire table rows Another use is to transform between internal and external representations For example the callback function shown below demonstrates how to scale a variable from internal units into the units expected by the SNMP manager In this case the variable appears as 1 10th of its internal value Note that the transformation needs to work both ways if the variable is writable by the SNMP manager int scale snmp_parms p int wr int commit long v word len word maxlen prime VCallloacke wrescl commit Sel wlim slcl wir Commit aay p if wr l On write by agent we ensure that the variable is within bounds if v gt 200000000 return SNMP_ERR_badValue HE Kev lt 200000000 return SNMP_ERR_badValue OK scale it up to internal representation w
226. e other lines are the body The body is ter minated with a D or Z 0x04 or Ox1A TCP IP Manual Vol 2 rabbit com 465 con_put This function creates a new file in the file system for use with the HTTP server It works in the following fashion if the command is called PUT e ASCII mode usage put lt filename gt The file is then sent terminating with a D or Z 0x04 or Ox1A e BINARY mode usage put lt filename gt lt size in bytes gt The file is then sent and must be exactly the specified number of bytes in length Note that ASCII mode is only useful for text files since the console will ignore non displayable charac ters In binary mode the put command will time out after CON_ TIMEOUT seconds of inactivity 60 by default con_putv This function updates the value of a variable A command that uses this function takes two parameters the name of the variable and the new value for the variable con_reset_files This function removes all web files con_reset_variables This function removes all web variables con_set_dhcp This function turns DHCP configuration for an interface on or off Currently this command only works with the default interface After DHCP has been turned on ZConsole will undertake reacquiring the lease should it be dropped For example a lease might be dropped if the DHCP server is unavailable for an extended period of time con_set_gateway This function changes the
227. e table form sspec_addform myform html myform 5 SERVER HTTP This line sets the title of the form The first parameter is the form index the return value of sspec addform and the second parameter is the form title This title will be displayed as the title of the HTML page and as a large heading in the HTML page sspec setformtitle form ACME Thermostat Settings The following line adds a variable to the resource table It must be added to this table before being added to the form The first parameter is the name to be given to the variable the second is the address of the variable the third is the type of variable this can be INT8 INT16 INT32 FLOAT32 or PTR16 the fourth is a printf style format specifier that indicates how the variable should be printed and the fifth is the server for which this variable is accessible The return value is the handle of the variable in the resource table 160 rabbit com HTTP Server var Sspec_ackhyacialole cemplaL Gcemplal INTL sel SERVER_HTTP The following line adds a variable to a form The first parameter is the index of the form to add the vari able to the return value of sspec_addform and the second parameter is the index of the variable the return value of sspec addvariable The return value is the index of the variable within the developer declared FormVar array myform var sspec addfv form var This function sets the name of a form var
228. e telling the user that redirection has taken place and to click here to go to the new URL This is for browsers that do not rec ognize the redirection 302 command in the header This may cause a problem for browsers which do recognize the 302 redirection command Some browsers immediately issue a GET request to the new location while still reading in the human readable page If MAX TCP SOCKET BUFFERS and HTTP MAXSERVERS are set to one the server will not receive the GET request because it is busy sending out the human readable page The symptom is that the browser appears to time out This timing problem may be masked when a proxy server is used Set MAX TCP SOCKET BUFFERS and HTTP MAXSERVERS to a value more than one to prevent this problem TCP IP Manual Vol 2 rabbit com 187 cgi redirectto PARAMETERS state Current server struct as received by the CGI function url Fully qualified URL to redirect to RETURN VALUE None sets the state so the CGI must immediately return with a value of 0 LIBRARY HTTP LIB SEE ALSO cgi_sendstring cgi sendstring void cgi sendstring HttpState state char str DESCRIPTION Sends a string to the user You should immediately issue a return 0 after calling this func tion The CGI is considered finished when you call this and will be in an undefined state This function greatly simplifies a CGI handler because it allows you to generate your page in a buffer and then
229. e that Dynamic C does not currently implement any of the MIB II objects since it does not support network router functionality TCP IP Manual Vol 2 rabbit com 375 12 1 3 2 Enterprise Subtree The enterprise subtree is of special interest because it is where you can stake out a personal piece of the brave new MIB world In Figure 12 13 notice that both Rabbit Semiconductor and Z World have nodes on the enterprise subtree Enterprise numbers are assigned by the Internet Assigned Numbers Authority IANA Our assigned enterprise numbers are e 12807 Rabbit Semiconductor e 12817 Z World Inc In Section 12 2 5 1 we will examine the Rabbit Semiconductor subtree To obtain an assigned enterprise number go to www iana org cgi bin enterprise pl 12 1 4 SMI Structure of Management Information SMI gives the rules for naming and defining the managed objects that are stored in a MIB The actual storage of instances of managed objects is done programmatically by the SNMP agent with the values being stored on the managed device The definitions of managed objects required by SMI are compiled by SNMP managers This is a standard that the manager uses in order to know what managed objects the agent can access and where they are logically located Object Name OID SMI specifies a hierarchical naming scheme The OID of an object is a series of non negative integers tra versing the tree to the node of the object Object Definition
230. e value of the variable that determines which state of the Ethernet to serial state machine will execute the next time e2s_tick is called char e2s buffer E2S BUFFER_SIZE This is a temporary buffer for copying data between the serial port buffers and the socket buffers Now we will look at the functions that were declared earlier in the program void resteart Soclzet ilmie il printf Restarting socket d n i Abort the socket SOC abore 6 le25_ stace li SOE z Set up the state machine to reopen the socket e25 Bede lll state HAS NILI The function restart socket displays a screen message and then aborts the socket The state vari able for the Ethernet to serial state machine is set to the initialization state which will cause the socket to be opened for listening the next time the state machine tick function is called 278 rabbit com RabbitWeb void update_tcp void auto int i Check which TCP port s changed for i 0 i c sizeof ports config i iit seriell portsial cap pore l Serial ports copy LLI tE Pore This port has changed restart the socket on the new port restart socket i Save the new port so we can check which one changed on the next update serial ports copy Lil CCD pore serial ports lil ccb port The function update_tcp is called when a TCP port is updated via the HTML interface It deter mines which TCP port s changed and then restarts
231. e with Zconsole lib each expect their own par ticular error message TCP IP Manual Vol 2 rabbit com 471 14 5 Zconsole I O Interface Multiple I O methods are supported as well as the ability to add custom I O methods An array of Console10 structures must be defined in the application program and named console io l This structure holds handlers for common I O functions for the I O method typedef struct long param Baud for serial port for telnet etc int open void close int tick int puts int rdUsed int wrUsed int wrFree int read int write Consolel0 14 5 1 How to Include an I O Method Each supported I O method is determined at compile time i e each supported I O method must have an entry in console io 14 5 2 Predefined I O Methods Several predefined I O methods are in Zconsole lib They will be included by entering their respec tive macros in console io const ConsoleIO console io CONSOLE IO SERA baud rate CONSOLE IO SERB baud rate CONSOLE IO SERC baud rate CONSOLE IO SERD baud rate CONSOLE IO SP channel number CONSOLE IO TELNET port number Dp H hm E The macros expand to the appropriate set of pre defined handler functions e g define CONSOLE IO SERA param param serAopen serAclose NULL conio serAputs serArdUsed serAwrUsed serAwrFree serAread serAwrite 14 5 2 1 Seri
232. e with the filename as the first parameter and a symbol that references it in Dynamic C as the second parameter ximport samples tcpip http pages static html index html ximport samples tcpip http pages newfile html newfile html Next find these lines in Static c SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE index html index html SSPEC RESOURCE XMEMFILE rabbiti gif rabbitl gif SSPEC RESOURCETABLE END Insert the name of your new file preceded by into this structure using the same format as the other lines SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE index html index html SSPEC RESOURCE XMEMFILE newfile html newfile html SSPEC RESOURCE XMEMFILE rabbiti gif Taloi wil Eji SSPEC RESOURCETABLE END Compile and run the program Open up your browser to the new page for example http 10 10 6 100 newfile html and your new page will be displayed by the browser 4 5 1 2 Adding Files with Different Extensions If you are adding a file with an extension that is not html or gif you need to use the appropriate macros to make an entry in the MIMETypeMap structure for the new extension The first field is the extension and the second field describes the MIME type for that extension You can find a list of MIME types at ftp ftp isi edu in notes iana assignments media types media types In the media types document located there the text in the type column would precede the
233. earch 1 starts searching the RAM entries servermask The server making the request e g SERVER HTTP RETURN VALUE 1 Failure 20 Success index of requested ServerSpec structure SEE ALSO sspec findname sspec gettvpe TCP IP Manual Vol 2 rabbit com 87 sspec getfileloc long sspec getfileloc int sspec DESCRIPTION Gets the location in memory or in the file system of a file represented by a ServerSpec struc ture The location of the file is returned as a long even if the file location should be represented by a char for a root file or a Fi leNum for the filesystem The return value should be cast to the appropriate type by the user sspec getfiletvpe can be used to find the file type PARAMETERS sspec spec index of the file in the resource list RETURN VALUE 20 Success location of the file 1 Failure SEE ALSO sspec getfiletvpe sspec getlength 88 rabbit com Server Utilitv Librarv sspec getfiletype word sspec getfiletype int sspec DESCRIPTION Get the type of a file represented by the given spec index PARAMETERS sspec spec index of the file in the resource list that is the index into the array of ServerSpec structures RETURN VALUE SSPEC ROOTFILE root memory data SSPEC XMEMFILE xmem data SSPEC ZMEMFILE compressed xmem data SSPEC FSFILE FS2 file SSPEC ERROR failure not a file or invalid handle SEE ALSO sspec getfileloc sspec gettvpe sspec
234. ecifier for outputting the variable such as d lt value gt is the value to assign the variable strlen is only used if the variable is of type STRING It is used to give the maximum length of the string con_delete This function deletes a file from the file system A command that uses this function takes one parameter the name of the file to delete con_echo This function turns on or off the echoing of characters on a particular I O stream That is it does not affect echoing globally but only for the I O stream on which it is issued A command that uses this function takes one parameter ON OFF TCP IP Manual Vol 2 rabbit com 463 con_get This function displays a file from the file system It works in the following fashion if the command is called GET e ASCII mode usage get lt filename gt The file is then sent followed by the usual OK message e BINARY mode usage get lt filename gt lt size in bytes gt The message LENGTH lt len gt will be sent indicating length of the file to be sent and then the file will be sent but not more than lt size in bytes gt bytes con_getv This function displays the value of the given variable The variable is displayed using the printf style for mat specifier given in the createv command A command that uses this function takes one parameter the name of the variable con_help This function implements the help system for Zconsole A command t
235. ed access is set to read only for the remainder of the managed objects Addition of each object requires the addi tional levels below the root OID specified in the call to snmp append parse stem By con vention objects with a single instance i e not tabular always have a zero at their lowest level enterprise 1 Rabbit Z World Inc Semiconductor 12817 12807 xi 1 rw int 1 0 rw_long 2 0 7 tt 8 r int 1 0 r long 2 0 r oid 6 0 But we still don t know where the oemExperiments demos rabbitsemiDemoSNMPI1 part comes in unless you cheated and already looked in the text files that were named in the instructions at the beginning of SNMP1 C These files e RABBITSEMI SMI txt top level Rabbit Semiconductor e RABBITSEMI PRODUCTS MIB txt listing of products boards e RABBITSEMI DEMO SNMP1 txt describes this demo contain the SMI definitions that are used by the SNMP manager 384 rabbit com SNMP 12 2 5 Defining Managed Objects with SMI The SNMP manager must compile the relevant txt files that define a MIB that is compatible with the structure of the MIB defined by the SNMP agent 12 2 5 1 Defining the Rabbit Subtree The text file RABBITSEMI SMI txt defines the top level of the Rabbit Semiconductor subtree RABBITSEMI SMI DEFINITIONS BEGIN IMPORTS MODULE IDENTITY OBJECT IDENTITY enterprises FROM SNMPv2 SMI rabbitsemi MODULE IDENTITY 2 dashes are the comment mark
236. ed by HTTP server but can be used for other purposes Authentication method s allowed combination of SERVER_AUTH_ bits RETURN VALUE 20 Success The following return values are negatives of the values defined in errno lib e ENOENT The resource was not found e EINVAL The resource name was malformed for example too long or context was NULL or the resource was not a file type SEE ALSO sspec open sspec delete sspec close 134 rabbit com Server Utilitv Librarv sspec tell long sspec tell int sspec DESCRIPTION Return the current read write offset in the file resource This will be a non negative value unless there was an error PARAMETER sspec Open file handle This must be a handle that was returned bv sspec open RETURN VALUE 20 Offset in the file resource The following return value is a negative of the value defined in errno lib Any other negative values indicate an error EBADF The specified handle was not open or invalid SEE ALSO sspec close sspec write sspec read sspec tell sspec open TCP IP Manual Vol 2 rabbit com 135 sspec write int sspec write int sspec char buf int len DESCRIPTION Write byte s to the given file resource The data is written to the current position then the current position is advanced by the number of bytes written PARAMETERS sspec Open file handle This must be a handle that was returned by sspec open buf Buffer
237. ed by Zserver is the ability to translate resource names URLs in the case of HTTP into references to filesystem and memory objects The term resource refers to the objects files functions and variables that are manipulated by the Zserver library on behalf of the server A file resource refers specifically to a resource of type file as opposed to the actual file that is manipulated by an underly ing filesystem which may not be a resource as such Support for HTML forms is also included in Zserver 1ib Starting with Dynamic C 8 50 an enhanced HTTP server RabbitWeb is available that has an easy to use interface for form generation and no limita tions on the form layout See Chapter 5 for more information on this enhanced HTTP server Zserver supports the concept of a virtual file system This is modeled on the Unix directory structure 3 1 Data Structures for Zserver lib There are several data structures in this library that servers with Zserver functionality must use and may need to be manipulated or initialized by the application program e MIMETypeMap e ServerSpec e ServerAuth e ServerPermissions e RuleEntry Use of the following structures is considered advanced e ServerContext e SSpecStat e sspec fatinfo TCP IP Manual Vol 2 rabbit com 31 The following structures are documented for historical reasons e FormVar e SSpecFileHandle 3 1 1 MIMETvpeMap Structure This structure organized into a table assoc
238. ed core module that has an Ethernet jack Hardware hook up instructions are in the user s manual for the device The hardware user s manual describes network connections for your device as well as set ting IP addresses for running sample programs 5 1 1 Dynamic C Application Code for Humidity Detector This section describes the application for our example The program is shown in its entirety for conve nience It is broken down into manageable pieces on the following pages TCP IP Manual Vol 2 rabbit com 249 File Name Samples tcpip rabbitweb humidity c define TCPCONFIG 1 define USE RABBITWEB 1 memmap xmem tausenden ep Ialo rusen izzjoni ximport samples tcpip rabbitweb pages humidity_monitor zhtml monitor zhtml ximport samples tcpip rabbitweb pages humidity admin zhtml admin_zhtml SSPEC MIMETABLE START SSPEC MIME FUNC zhtml text html zhtml handler SSPEC MIME html text html SSPEC MIMETABLE END SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE index zhtml monitor zhtml SSPEC RESOURCE XMEMFILE admin index zhtml admin zhtml SSPEC RESOURCETABLE END web groups admin int hum web hum groups all ro int hum alarm web hum alarm 0 lt hum alarm amp amp hum alarm lt 100 X groups all ro admin ime alarm interval char alarm_email 50 web alarm interval 0 lt S alarm_interval amp amp Salarm interval lt 30000 groups all ro
239. eees 321 11 3 2 POP PARSE EXTRA call back 366 8 1 Configuration Macros ssssssssesnenzavenzz 322 11 4 API Functions sccccscssscssevsvssvsssesssee 367 8 2 File Handlers sen 324 pop3 A A 367 8 2 1 Replacing the Default Handlers 324 pop3 getmail eee 368 8 2 2 File Handlers Specification 324 pop3 tiek eee 369 ftp dflt OPEN s sense ennannenenne nn 325 11 5 Sample Receiving of E mail 370 ftp_dflt_getfilesize 326 11 5 1 Sample Conversation 371 ftp dflt read srira 327 ftp dflt write ARA IDA EA JAP 328 1 2 SNMP prrrerenesenenanzzznanananananznnnann nn 37 3 ftp_dflt_elose wisensscrssarsvenesvestvasesive 329 12 1 SNMP OVerview semen 373 ftp dfit list ria paige GA E EA 330 12 1 1 Managed Objects 374 ftp dfit cd 331 1212 SNMP A 374 ftp dflt pwd cccccsssecssseessssescsseeesses 332 SIA gent TU GN MACAU ki i ken 333 12 1 3 MIBs 375 ftp dfit delete 0 334 12 1 4 SMI 376 8 3 API Functions oo ennennnnnzenn 335 12 2 Demo Program ET 378 ftp_dflt_is_auth PA 335 12 2 1 Creating Managed Objects 379 ftp_init etbesi eltsinentotrozzi bet ti ogit O 336 12 2 2 Callback Functions 380 ftp load filenames 0 337 1223C ing C MR 382 ftp_save_filenames cece 338 ne reating ommunities ftp_set_ANONYMOUS cceeeeeeees 339 12 2 4 Creating the MIB 383 ftp shutdown nn 340 12 2 5 Defining Managed Objects with SMI ftp TICK irrien cneseedesnts 340 385 8 4 Sample FTP S
240. eful for HTTP servers NOTE If using HTTP upload facility and or the new CGI interface use sspec_addCGI instead PARAMETERS name Name of the function tpr Pointer to the function servermask Bitmask representing servers for which this function will be valid currently only useful with SERVER_HTTP RETURN VALUE 1 Failure 20 Success location of the function in the TCP IP servers object list SEE ALSO sspec addform sspec addfsfile sspec addrootfile sspec addvariable sspec addxmemvar sspec addxmemfile sspec aliasspec 62 rabbit com Server Utilitv Librarv sspec addfv int sspec addfv int form int var DESCRIPTION Adds a variable to a form PARAMETERS form spec index of the form previously returned by sspec addform var spec index of the variable to add which must have been previously created using sspec_addvariable RETURN VALUE 1 Failure 20 Success next available index into the FormVar array SEE ALSO sspec addform TCP IP Manual Vol 2 rabbit com 63 sspec addrootfile int sspec addrootfile char name char fileloc int len word servermask DESCRIPTION Adds a file that is located in root memory to the dynamic resource table Make sure that SSPEC MAXSPEC is large enough to hold this new entry PARAMETERS name Name of the new file This must be unique but this function does not check The name should not conflict with the virtual filesystem hier
241. either at the keyboard using a terminal emulator or a command is generated and sent from an attached machine Zconsole carries out the com mand and either the message OK r n is returned or an error is returned in the form of ERROR XXXX This is an error message r n Note that the carriage return and new line characters r n are always returned by Zconsole whether the command completed successfully or not 14 3 1 Zconsole Command Data Structure The command system is set up at compile time with an array of ConsoleCommand structures There is one array entry for each command recognized by Zconsole typedef struct char command int cmdfunc long helptext ConsoleCommand command This field is a string like the following SET MAIL FROM That is each word of the command is separated by a space The case of the command does not matter Entering this string is how the command is invoked emdfunc This field is a function pointer to the function that implements the command The functions that come with Zconsole are listed in Section 14 4 1 1 on page 463 460 rabbit com General Purpose Console helptext This field points to a text file The text file contains help information for the associated command When HELP COMMAND is entered this text file the help information for COMMAND will be printed to Zconsole The help text comes from ximported text files 14 3 1 1 Help Text for General Cases There are two
242. ements for the FAT library and the associated serial flash driver library As with the sample in the last section this code assumes that a valid filesystem partition exists on the target board in this case it s an FS2 partition In the simplest case which is one FS2 partition on the secondary flash bringing in s2 1ib and then mounting the filesystem with acall to sspec_ automount is all that is required For more informa tion on FS2 refer to the Dynamic C User s Manual The next change is the def ine of the user groups Each user group has to be explicitly given a value when RabbitWeb is not available to do it Note that they are word values each with a unique bit position set Next the first entry in the MIME table was changed Recall that the entry and requests without an extension are dealt with by the handler in the first entry of the MIME table In this example if a browser points to the Rabbit board s IP address the page is processed by shtml_handler a handler that will understand the SSI tags that we are about to add to the HTML file The ximport statement did not techni cally need to change The extension used for the file was changed from zhtmi to shtm1 These file extensions are only a convention The important thing is that the HTML file is touched by the correct han dler function As a matter of fact in this example our HTML page is not recognized by the server as end ing with either zhtml or s
243. ended to use them instead of static initial izers in order to maintain forward compatibility The macros with P_ inthe name are the same as the others except that they explicitly allow all 42 rabbit com Server Utility Library the server permissions information except for the MIME type mapping to be initialized See sspec addrule for more information on the parameters The name parameter to all these macros is the resource name This usually starts with a for files but not for variables The string length should be less than or equal to SSPEC_MAXNAME The other parameters depend on the resource type being created ROOTFILE addr root memory address of first byte of file 1en length of file 0 32767 XMEMF ILE addr longword physical address of the length word of the file The length word 4 bytes is followed by the first byte of data ZMEMF ILE as for XMEMF ILE except the file is compressed and imported using zimport instead of ximport FSFILE fnum FS2 file number of file 1 255 ROOTVAR addr root memory address of data type type of data as documented with sspec addvariable format char format as used by printf For example d for a decimal number XMEMVAR as for ROOTVAR except the address is a longword physical address FUNCTION or CGI addr address of C function Note that a maximum of 511 static resource table entries can be defined 3 3 File Compression Support
244. entered then the page will be displayed Otherwise the browser will print an error message saying that access was denied 20 rabbit com Web Enabling Your Application Unfortunately as written above the sample will not allow us to test the distinction between the two users regarding the ability to modify the web variable We have shown how to add access control but not how to actually specify a web form that allows the user to update the variable It turns out that adding a form is not difficult A modified script file is shown below There is quite a lot to HTML forms so most of the details are documented elsewhere There are many good HTML reference books available lt HTML gt lt HEAD gt lt TITLE gt Web Variables lt TITLE gt lt HEAD gt lt BODY gt lt H1 gt Web Variables lt H1 gt lt P gt The current value of io state is lt z echo io state 72 lt P gt lt z if error io state gt lt P gt Sorry you were not authorized to perform an update lt P gt lt z gt lt FORM ACTION index html METHOD POST gt lt P gt Enter a new value if you dare lt P gt lt INPUT TYPE text NAME io state SIZE 5 VALUE lt z echo io state gt gt lt INPUT TVPE submit VALUE Submit gt lt INPUT TYPE reset VALUE Reset gt s lt FORM gt lt BODY gt lt HTML gt If you run the above sample with this script then the user will be able to attempt an update to the web variable io state If the user was
245. entries marked in red below gZ Ps Without any parameters error returns TRUE if there were any errors in the last form submission When the submit button for the form is clicked the POST request goes back to the zhtmi page specified by the line lt FORM ACTION admin index zhtml METHOD POST gt Since this refers back to itself if there were any errors in the last form submission the page is redisplayed and along with it the error message inside the if statement Figure 5 9 Web Page with Error Message File Edit View Favorites Tools Help Ea e ala U g BAr a Back Forward Stop Refresh Home Search Favorites History Mail Address http nowhere org admin index zhtml Go Links Configure the humidity device ERROR Your submission contained errors Please correct the entries marked in red below Humidity alarm level percent fi 12 Send email alarm to somebody nowhere org Minimum time between alarms minutes feo Submit Return to the humidity monitor page There are five actions the user can take on this page The Submit button was discussed above and the link to the monitor page is a common HREF link The other three actions are the input fields of the form These are text fields created by the INPUT tags lt INPUT TVPE text NAME hum_alarm SMZ ESB VALUE lt zZ print Shum alarm gt gt TCP IP Manual Vol 2 rabbit com 257 Notice how
246. er the information that should be here may be seen in RABBITSEMI SMI txt enterprises 12807 assigned by IANA The MODULE IDENTITY macro names rabbitsemi as node 12807 under enterprises rabbitsemiProducts OBJECT IDENTITY STATUS current DESCRIPTION rabbitsemiProducts is the root OBJECT IDENTIFIER from which sysObjectID values are assigned Actual values are defined in RABBITSEMI PRODUCTS MIB rabbitsemi 1 The OBJECT IDENTITY macro names rabbitsemiProducts as node 1 under the rabbitsemi node Studying the rest of the definitions in this file you should be able to create the following tree diagram TCP IP Manual Vol 2 rabbit com 385 enterprise 1 rabbitsemi gt Z World Inc 12817 i oe jfa rabbitsemiProducts 1 rabbitsemiChipsets 9 rabbitsemiMgmt 2 rabbitsemiExperiments 8 oemExperiments 3 rabbitsemiConfig 7 oemAssigned 4 rabbitsemiAgentCapability 6 rabbitsemiModules 5 demos 1 processor 1 communication 2 12 2 5 2 Defining the Demo MIB The file RABBITSEMI DEMO SNMP1 txt defines another level in the MIB and then defines the leaf nodes that will hold the values of the managed objects for this demo The leaf nodes correspond to the variable definitions in the code shown in Section 12 2 1 RABBITSEMI DEMO SNMP1 DEFINITIONS BEGIN IMPORTS MODULE IDENTITY OBJECT TYPE NOTIFICATION TYPE IpAddress TimeTicks FROM SNMPv2 SMI DisplayS
247. er complete 1 Error from remote side transfer terminated In this case the ts_addr gt file field will be overwritten with a NULL terminated error message from the server 2 Error could not contact remote host or lost contact 3 Timed out transfer terminated 4 not used 5 Transfer complete but truncated buffer too small to receive the complete file LIBRARY TFTP LIB TCP IP Manual Vol 2 rabbit com 349 tftp tickx int tftp tickx long ts addr DESCRIPTION This function is a wrapper for calling tftp tick where the structure is possibly stored somewhere other than in the root data space See that function description for details PARAMETERS ts addr Physical address of TFTP state struct tftp state RETURN VALUE 1 OK transfer not yet complete 0 OK transfer complete 1 Error from remote side transfer terminated In this case the ts_addr gt file field will be overwritten with a NULL terminated error message from the server 2 Error could not contact remote host or lost contact 3 Timed out transfer terminated 4 not used 5 Transfer complete but truncated buffer too small to receive the complete file LIBRARY TFTP LIB 350 rabbit com TFTP Client tftp exec int tftp exec char put long buf addr word len int mode char host char hostfile udp Socket sock DESCRIPTION Prepare and execute a complete TFTP session blocking until complete This function
248. er of dertcp lib and fat lib may be interchanged since these libraries are independent However it is recommended you use the given ordering since future releases of the FAT may be able to use networking services Step 5 Create a Web Page When using HTTP upload there needs to be a way to prompt the user web browser to enter a file name to upload This is done by using an HTML form The form specifies input fields that may be filled out by the user and one or more submit buttons that the user presses to start the upload process If you have an existing web based application to which you want to add a file upload facility you probably already have a web page with a form on it in this case you can add an extra input field to an existing form on that page or create a new form on the same page You may already have a CGI function that processes the results of the form submission This will need to be rewritten to process data that is not URL encoded If you are creating a new application you need to construct an initial page to contain the necessary form elements As a starting point you can use the sample page in samples tcpip http pages upload html Click on upload html and the browser will displav something like this E HTTP Upload Form Microsoft Internet Explorer Oy x File Edit View Favorites Tools Help e ae RO li Cut Copy Paste Back Forgan Stop Refresh Home Search Favorites Address je E
249. ermask will be returned RETURN VALUE 0 Success 1 Failure sspec gettype word sspec gettype int sspec DESCRIPTION Returns the type SSPEC FILE SSPEC VARIABLE etc of the spec entry represented by sspec This is a generic type in that SSPEC FILE is returned for any type SSPEC ROOTFILE SSPEC FSFILE etc that has file properties and SSPEC_VARIABLE is returned for SSPEC ROOTVAR or SSPEC XMEMVAR Other tvpes are returned without translation PARAMETERS sspec spec index RETURN VALUE SSPEC ERROR Failure ISSPEC ERROR Success tvpe as described above SEE ALSO sspec getfiletvpe sspec getvartvpe 100 rabbit com Server Utilitv Librarv sspec getuserid int sspec getuserid int sspec int index DESCRIPTION Returns a userid for the given sspec resource Since a resource can have multiple userids asso ciated with it index indicates which userid should be returned Note that index should follow the relation 0 S index lt SSPEC USERSPERRESOURCE If there is no userid for a given index 1 will be returned If 1 is returned for an index then 1 will also be returned for all higher indices This function may be used to iterate through all users that have read access to a particular resource This only works for RAM and flash table entries Starting with Dynamic C 8 50 access control is done by user groups rather than individual users therefore sspec_getuserid may not work as expected PARAMETE
250. ers function if HTTP CUSTOM HEADERS is defined content If more_hdrs is non zero this parameter can include additional headers followed by two r n pairs and then content for the response If more_hdrs is zero this parameter is sent as page content only LIBRARY HTTP LIB TCP IP Manual Vol 2 rabbit com 197 http getAction char http getAction HttpState state DESCRIPTION Return the current CGI action This should be called only from a CGI function registered as a SSPEC_CGI resource in the zserver resource table NOTE This is implemented as a macro You must define the macro USE HTTP UPLOAD if using this macro otherwise you will get a compile time error http getAction should be called at the top of the CGI function Other http get functions macros may or may not be valid depending on the action code The following table shows which functions are applicable Table D 8 Valid Functions per Action Code CGI Action Code Valid Functions Macros http_getContext http_getURL http_getState http_setState http_getCond http_setCond http_getUserState http_getSocket http_write Any action code except CGI ABORT http_abortCGI http_skipCGI http_finishCGI http_switchCGI http_getHTTPVersion http_getHTTPVersion_str http_getHTTPMethod http_getHTTPMethod_str http_getRemainingLength http_getField http_getContentLength CGI START http_getContentType http_getContentDisposition http_get
251. ers is set to the number of server instances plus the number of serial ports The last two defines will be used later to allocate space for the receive and transmit buffers used by the serial port drivers This is the end of the configuration section 274 rabbit com RabbitWeb memmap xmem define USE RABBITWEB 1 kuse dertop lib use http lib ximport samples tcpip rabbitweb pages config zhtml config zhtml SSPEC MIMETABLE START SSPEC MIME FUNC zhtml text html zhtml handler SSPEC MIME html text htmi SSPEC_MIME gif image gif SSPEC MIMETABLE END SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE config zhtml SSPEC RESOURCE XMEMFILE index zhtml config zhtml SSPEC RESOURCETABLE END This block of code asks the compiler to map functions not declared as root to extended memory Setting the macro USE RABBITWEB to one enables the use of the scripting language and the HTTP enhance ments Other macros that affect these features are described in the reference section Next the TCP IP libraries are brought in as well as the HTTP library The HTML page that contains the configuration inter face to the serial ports is copied into memory with the ximport directive HTTP servers require MIME type mapping information This information is kept in the MIME table which is set up by the SSPEC MIME 4 macros The SSPEC_RESOURCE macros set up the static resource table for this server The resource ta
252. erver 341 12 2 6 Running the SNMP Agent 389 8 5 Getting Through a Firewall 342 12 3 Configuration Macros ssssssersesser 390 8 6 FTP Server Commands ssseennnn 342 12 4 API Functions sonciernanmieuie 392 8 7 Reply Codes to FTP Commands 344 simp add iisipin iinei 393 l snmp add communitv 396 9 TETP Ch nt siccis 345 snmp_append_binary_oid 397 iv rabbit com Table of Contents snmp append binarv stem 398 13 2 2 API Functions 455 snmp_append_oid n s 399 telnet imit sess eeesnenennznznnnznzenznnan 455 snmp_append_parse_oid 4 400 telnet tiek cscscsssesssssesseeeseereee 456 snmp_append_parse_stem 401 telnet ClOSE eee 456 snmp_append_steM eessseseeseeenenn 402 13 2 3 An Example Telnet Server 457 snmp_community_mask PA 403 13 2 4 An Example Telnet Client 458 snmp_community_name 404 a i KA E E EE i 14 General Purpose Console 459 ag e A 407 14 1 Zoonsole Features sssssssssssssseeseeeeee 459 Nip eee 408 14 1 1 File System Requirement 459 snmp_get_indexed mn 409 14 1 2 TCP IP and Zconsole 460 ane ae ae ee fel 14 2 Login Name and Password 460 snmp last index an 412 14 3 Zconsole Commands and Messages 460 snmp last Int 413 14 3 1 Zconsole Command Data Structure snmp last len nn 414 460 a TT 14 4 Zeonsole Command Array wr 461 snmp_last_me
253. erver This only applies to the FTP server The username anonymous is recommended since most FTP clients use this for hosts that have no account for the user PARAMETER uid The user ID to use as the anonymous user This should have been defined using sauth_adduser Pass 1 to set no anonymous user RETURN VALUE Same as the uid parameter except 1 if uid is invalid LIBRARY FTP SERVER LIB SEE ALSO sauth_adduser TCP IP Manual Vol 2 rabbit com 339 ftp shutdown void ftp shutdown int bGraceful DESCRIPTION Close and cancel all FTP connections If the server is connected to a client forces the QUIT state If the application has called tcp reserveport then it must call tcp clearreserve Fora graceful shutdown the application must call tcp tick a few more times After the FTP sockets close the application must call ftp init to again start the server run ning PARAMETER bGraceful boolean zero to immediately abort all open connections or non zero to simulate the QUIT command RETURN VALUE None LIBRARY FTP SERVER LIB SEE ALSO ftp init ftp_tick void ftp tick void DESCRIPTION Once ftp init has been called ftp tick must be called periodically to run the serv er This function is non blocking LIBRARY FTP SERVER LIB SEE ALSO ftp init 340 rabbit com FTP Server 8 4 Sample FTP Server This code demonstrates a simple FTP server using the ftp librar
254. es not affect your existing application except to slightly reduce memory usage This change does add flexibility because it gives any file handler the ability to call any other file handler In particular ftp dfilt list may now call ftp dflt getfilesize to get the file s size 8 2 2 File Handlers Specification Function descriptions for the default handlers are detailed in this section Additional information is pro vided in these descriptions when the default handler does not cover the entire function specification The default file handlers are in FTPSERVER LIB 324 rabbit com FTP Server ftp dflt open int ftp dflt open char name int options int uid int cwd DESCRIPTION Opens a file If a file is successfully opened the returned value is passed to subsequent handler routines to identify the particular file or resource as the fd parameter If necessary you can use this number to index an array of any other state information needed to communicate with the other handlers The number returned should be unique with respect to all other open resource instances so that your handler does not get confused if multiple FTP data transfers are active simultaneously Note that the specified file to open may be an absolute or relative path if the handler supports the concept of directories then it should handle the path name appropriately and not just assume that the file is in the current directory If the filename is relative
255. et str snmp parms p char DESCRIPTION Set the value of an ascii string object The OID of the object must be set in p If the object is not in fact a string then NULL will be returned and there will be no alteration of the value If the string is too long for the specified maximum storage length for this object then the string is truncated to fit This may result in the object having no null terminator See snmp set int for other general considerations PARAMETERS p Parameter structure that was previously initialized by calls to snmp init parms snmp set stem etc s New value for the object RETURN VALUE NULL if p was NULL or if there is no object with the given OID or if the object was not stored with string internal type Otherwise returns p LIBRARY MIB LIB SEE ALSO snmp init parms snmp set stem snmp append stem snmp get indexed snmp get snmp add snmp xadd snmp set int snmp set long snmp set oct snmp set foct snmp set objectID TCP IP Manual Vol 2 rabbit com 439 snmp start int snmp start void DESCRIPTION Restart the SNMP subsystem after calling snmp stop RETURN VALUE 0 LIBRARY SNMP LIB SEE ALSO snmp_stop snmp stop int snmp_stop void DESCRIPTION Temporarily suspends network access to the SNMP subsystem Incoming SNMP messages are re ceived but ignored while in the stopped state If the stopped state is maintained for less than about 1 second then e
256. ething the browser will understand such as an HTML document or GIF image You can use this function as a starting point for generating your own content PARAMETERS state HTTP state pointer provided by HTTP server to all CGIs newURL The resource name to present to the client This may be another CGI or any other type of resource that could be presented to the client in response to an HTTP GET or POST request The resource must exist in the flash or ram spec table or in a filesystem RETURN VALUE See documentation for writing a data handler CGI LIBRARY HTTP LIB SEE ALSO http_getAction http_skipCGI http_switchCGI http_finishCGI http_write 194 rabbit com HTTP Server http delfile int http delfile char name DESCRIPTION Deletes a file from the RAM spec table PARAMETERS name Name of the file as passed to http addfile RETURN VALUE 0 Success 1 Failure not found LIBRARV HTTP LIB SEE ALSO http addfile http finderrbuf char http finderrbuf char name DESCRIPTION Finds the occurrence of the given variable in the HTML form error buffer and returns its location PARAMETERS name Name of the variable RETURN VALUE NULL Failure NULL Success location of the variable in the error buffer LIBRARY HTTP LIB TCP IP Manual Vol 2 rabbit com 195 http findname int http findname char name DESCRIPTION Finds a spec entry searching first in RAM then in f
257. etparity PARAM_NOPARITY else iz serial porcs ri cser parity 1 Even parity e2s statelil setparity PARAM EPARITY else Odd parity 2 e2s state i setparity PARAM OPARITY else 2 stop bits e2s statelil setparity PARAM 2STOP The function serial open is called from the function that initializes the Ethernet to serial state machine e2s init It does all of the work necessary to open a serial port including setting the num ber of data bits stop bits and parity The first statement opens the serial port using the baud rate value that was initialized in main In the rest of the code the values for the other serial port parameters which are also initialized in main are used to determine the correct bitmask to send to the serial port functions serXdatabits and serXparity The bitmasks PARAM are defined in the serial port library RS232 lib TCP IP Manual Vol 2 rabbit com 281 void e2s init void auto int i for i 0 i lt sizeof ports config i e2s statelil state E2S INIT Initialize the state Initialize the serial function pointers Switch pores contigiil Gase VA e2s statelil open serAopen e2s statelil close serAclose e29 Biteiee lill read gserAreacl e2s state i write serAwrite e2s state i setdatabits serAdatabits e2s statelil setparitv serAparity break default Error not a valid se
258. eturn http write s a verv long html fragment strlen a very long html fragment case CGI CONTINUE if was writing that long fragment return http write s a verv long html fragment strlen a very long html fragment break The details of determining which write was in progress have been glossed over Basically you would have to use a cond variable to keep track of which http write was in progress if there is more than one possibility There is a limit to the amount of data that http write can possibly write on any given call This limit is set by the HTTP server socket transmit buffer size This buffer size is given by TCP BUF_SIZE 2 The transmit buffer is usually at least 1024 bytes which is considerably larger than the limitation when using the CGI_ SEND return code typically 255 bytes If you try exceeding that limit http write will never succeed Step 7 Creating the Resource Tables Web browsers use URLs which are specially formatted strings to refer to resources web pages on the server For example a user may enter http rabbit server admin upload html to retrieve the admin upload html resource from the HTTP server on rabbit_server When the server receives such a request it needs to look up the name open the resource that it refers to and send the contents back to the client CGI functions are no different from other resources as far as the client is concerned The server
259. ext time the tick function is called If no data was read from the serial port the process state will execute again the next time the tick function is called void main void auto int i Mnitialize the serial_ports data structure for i 0 i c sizeof ports config i serial porets il cep pore 1234 ip Serial portslil ser port ports configlil serial portslij ser baud 9600 serial ports i ser databits 8 serial ports i ser parity 0 serial portslil ser stopbits 1 Make a copy of the configuration options to be compared against when the update functions are called memcpy serial _ ports copy serial ports sizeof serial ports Initialize the TCP IP stack HTTP server and Ethernet to serial state machine soak inir hero init z e2s_init This is a performance improvement for the HTTP server port 80 especially when few HTTP server instances are used tcp reserveport 80 while 1 Drive the HTTP server http handler Drive the Ethernet to serial state machine e2s_ tick In the main function the configuration parameters for the serial ports are given initial values which are then copied for later comparison After initialization of the stack the web server and finally the state machine the while loop allows us to wait for a connection TCP IP Manual Vol 2 rabbit com 285 5 4 2 HTML Page for TCP to Serial Port Example The file con
260. f a CGI_ABORT action code This code means that the connection has been lost and there is no point in handling any more incoming data or generating any response Thus processing of CGI_ ABORT is neces sarily limited to cleaning up any open files or other resources case CGI ABORT handle http getCond s COND HANDLE sspec close handle break In this example we simply close the handle possibly leaving the file with partially written contents It is important to do this since if the handle is left open then that handle is lost forever or until the next reboot The CGI ABORT code can happen at any time so the CGI must handle it if it ever uses leak able resources If you are alert you noticed that CGI ABORT may be called when there is no open handle We must guard against the possibility of trying to close an invalid handle since it may happen to belong to another active CGI We can do this by ensuring the value in the cond variable is 1 if the handle is not open 174 rabbit com HTTP Server Minimum Required Functionality of CGI All the above code is pulled together with the proper tests and comments on the additional code cond variable for storing the handle define COND HANDLE 0 int my_CGI HttpState s int handle Following block ensures that the first time http getState is zero we set the handle to 1 if http getState s 0 http setState s 1 http setCond s COND HANDLE
261. f the object is not in fact an OID then NULL will be returned and there will be no alteration of the value See snmp set int for other general considerations PARAMETERS p Parameter structure that was previously initialized by calls to snmp init parms snmp set stem etc oid New value for the object RETURN VALUE NULL if p was NULL or if there is no object with the given OID or if the object was not stored with object ID internal tvpe Otherwise returns p LIBRARV MIB LIB SEE ALSO snmp init parms snmp set stem snmp append stem snmp get indexed snmp get snmp add snmp xadd snmp set int snmp set str snmp set oct snmp set foct snmp set long TCP IP Manual Vol 2 rabbit com 433 snmp set oct snmp parms snmp set oct snmp parms p word len char s DESCRIPTION Set the value of a variable length object The OID of the object must be set in p If the object is not in fact an octet string then NULL will be returned and there will be no alteration of the value If Len is too long for the specified maximum storage length for this object the data is truncated to fit See snmp set int for other general considerations PARAMETERS p Parameter structure that was previously initialized by calls to snmp init parms snmp set stem etc len New length for the object s New value for the object This points to the actual object data not the 2 byte length prefix RETURN VALUE NULL if p was NULL
262. fer Anonymous FTP is supported Most FTP servers on the Internet use the identifier anonymous So since FTP clients expect it this is the identifier that is recommended But any string with a maximum length of SAUTH_MAXNAME may be used Dynamic C 8 includes some enhancements that basically let the FTP server act as a full FTP server where you can create read and delete files at will To use these enhancements the configuration macro FTP USE FS2 HANDLERS must be defined to enable FS2 support in the default file handler functions The structure that holds the association of filenames and FS2 file locations is the server spec list the glo bal array defined in zserver 1ib It is stored in the User block and the API functions ftp save filenames and ftp load filenames are used for support of this NOTE For a demonstration of the enhanced FTP server see the sample pro gram SAMPLES TCPIP FTP FTP SERVER FULL lt C TCP IP Manual Vol 2 rabbit com 321 8 1 Configuration Macros The configuration macros control various conditions of the server s operation Read through them to understand the default conditions Any changes to these macros may be made in the server application with define statements before inclusion of FTPSERVER LIB FTP CMDPORT This macro defaults to 21 which is the well known FTP server port number You can override this to cause the server to listen on a non standard port number FTP CREATE MASK Th
263. ferend Use for reading in data ConsoleCommand cmdspec int sawcr int sawesc int echo Check if echo is enabled or change it int substate unsigned int error int numparams Number of parameters on command line int commandparams Number of commands issued on cmd line char cmddata CON CMD DATA SIZE ifndef CON NO FS SUPPORT File processing not needed with DC 7 30 FileNumber filenum Use for file processing File file Use for file processing tendif int spec Use for working with Zserver entities long timeout Use for extending the time out ConsoleState tendif To accomplish its tasks the function should use state gt substate for its state machine which is initialized to zero before dispatching the command handler and state gt command to read out the command buffer to get other parameters to the command for instance In case of error the function should set state gt error to the appropriate value 468 rabbit com General Purpose Console The buffer at stat e gt cmddata is available for the command to preserve data across invocations of the command s state machine The size of the buffer is adjustable via the CON CMD DATA SIZE macro set to 16 bytes by default Generally this buffer area will be cast into a data structure appropriate for the given command state machine Both state gt numparams and state gt commandparams are read only The latter was introduced in Dynamic
264. fficient const ConsoleError console errors CON STANDARD ERRORS includes all default error messages TCP IP Manual Vol 2 rabbit com 469 14 4 2 1 Default Error Messages These are the error codes for the default error messages and the text that will be displayed by the console if the error occurs define CON ERR TIMEOUT 1 define CON_ERR_BADCOMMAND 2 define CON_ERR_BADPARAMETER 3 define CON ERR NAMETOOLONG 4 define CON ERR DUPLICATE 5 tdefine CON ERR BADFILESIZE 6 define CON_ERR_SAVINGFILE 7 define CON ERR READINGFILE 8 tdefine CON ERR FILENOTFOUND 9 define CON ERR MSGTOOLONG 10 tdefine CON ERR SMTPERROR 11 tdefine CON ERR BADPASSPHRASE 12 tdefine CON ERR CANCELRESET 13 define CON ERR BADVARTVPE 14 tdefine CON ERR BADVARVALUE 15 define CON ERR NOVARSPACE 16 tdefine CON ERR VARNOTFOUND 17 tdefine CON ERR STRINGTOOLONG 18 define CON ERR NOTAFILE 19 define CON ERR NOTAVAR 20 tdefine CON ERR COMMANDTOOLONG 21 tdefine CON ERR BADIPADDRESS 22 tdefine CON ERR INVALIDPASSWORD 23 define CON ERR BADIFACE 24 tdefine CON ERR BADNETWORKPARAM 25 470 rabbit com General Purpose Console define CON STANDARD ERRORS CON ERR TIMEOUT Timed out CON ERR BADCOMMAND Unknown command CON ERR BADPARAMETER Bad or missing parameter Fi CON ERR NAMETOOLONG Filename too long CON ERR DUPLICATE Duplicate object found CON_ERR_BADFILESIZE Bad file size CO
265. fig zhtml that was copied into memory at the beginning of this program contains the HTML form that is presented when someone contacts the IP address of the Rabbit that is running the above application code config zhtml uses the ZHTML scripting language that interacts with the code above to create the web interface to a Rabbit based controller board File name Samples tcpip rabbitweb pages config zhtml lt HTML gt lt HEAD gt lt TITLE gt Ethernet to Serial Configuration lt TITLE gt lt HEAD gt lt BODY gt lt H1l gt Ethernet to Serial Configuration lt H1 gt lt A HREF index zhtml gt Reload the page with committed values lt A gt lt P gt Sir Give error 7 gt There is an error in your data The errors are both listed below and marked in lt FONT COLOR ff0000 gt red lt FONT gt lt UL gt 282 ien SA Op SA lt Goume Ssemial jemes T OSAA 73 42 die ester Serial porets SA ee port 22 lt LI gt Serial Port lt z echo Sserial ports A ser port gt TCP port is in error must be greater than 0 committed value is lt z echo eserial ports SA tcp port gt lt Z Re lt Z if error Sserial portsISAJ ser baud Ps lt LI gt Serial Port lt z echo Sserial ports A ser port gt baud rate is in error lt z echo error Sserial ports SA ser baud gt must be between 300 and 115200 baud committed value is lt z echo serial portsISAJ ser baud gt lt Z R SAZ
266. figure the humidity device lt H1 gt 207 if error gt ERROR Your submission contained errors Please correct the entries marked in red below lt Z 25 lt FORM ACTION admin index zhtml METHOD POST s3 lt P gt lt z if error hum_alarm 73 lt FONT COLOR f 0000 gt NDA 22 Humiditv alarm level percent lt z if etror Shum alarm 2 lt FONT gt 22 85 lt INPUT TYPE text NAME hum alarm SIZE 3 WALUE lt P joie Slob ellen PS gt lt P gt lt z if error Salarm email 73 lt FONT COLOR ff 0000 gt lt Z i Send email alarm to lt if error alarm_email gt lt FONT gt lt Z e lt INPUT TYPE text NAME alarm_email SIZE 50 VALUE lt z print alarm email gt gt lt P gt lt z if error Salarm interval 73 lt FONT COLOR f 0000 gt lt Z 2S Minimum time between alarms minutes 42 Wir error Sallesem_imieerweill 73 lt FONT gt lt Z 22 lt INPUT TYPE text NAME alarm_ interval Sl A 5 VALUB lt zZ print Salarm interval gt gt lt P gt lt INPUT TYPE Submit VALUE Submit gt lt FORM gt lt A HREF index zhtml gt Return to the humidity monitor page lt A gt lt BODY gt lt HTML gt 256 rabbit com RabbitWeb After the usual opening lines of an HTML page is our first server parsed tag Bez de error 2 gt ERROR Your submission contained errors Please correct the
267. foct 3 0 ro foct 3 0 rw str 4 0 ro str 4 0 rw oct 5 0 ro oct 5 0 rw oid 6 0 ro oid 6 0 rw ipaddr 7 0 rw timeticks 8 0 388 rabbit com SNMP 12 2 6 Running the SNMP Agent Now that we ve seen how the SNMP manager uses an SMI defined MIB to recognize the MIB controlled by the SNMP agent let s look at the rest of the sample program SNMP1 C our SNMP agent for this demo After the MIB is defined the managed objects are initialized the MIB tree is checked to make sure it was constructed without error and the network is started Mnitialize the variables iw ime 1001 rw long 1000002 memcpy rw fixed rw fixed abcdefghijk 20 SIEIEGJON 207 _ Siew Waw Sic p memepy xw oct x06 x00rw_oct 8 memcpy amp rw_oid amp p sizeof snmp oid trapdest ip aton MANAGER IP rw tt snmp timeticks Set base epoch r int 2001 r long 2000002 memcpy r fixed r fixed abedefghijkl 20 Serey Ce SEE e SeN y memepy le oct Y05000 oer 7 7 memcpy amp r_oid amp p sizeof snmp oid Finally we check that the MIB tree was constructed without error Wf there was any error p will be set to NULL alge Up 4 printf There was an error constructing the MIB n esgalit IL p Monitor the rw int variable whose MIB tree index was saved in monindex trapindices was set up with the indices for r int and r oct snmp monitor monindex 0 30
268. forhttpc init if using IF_ANY as the interface designator 6 2 2 Connect and Request Functions As is usual with client side software the HTTP client initiates the connection and makes a request of the server Common requests are GET POST and HEAD The Dynamic C HTTP client has seven functions to choose from that accomplish the connect request tasks There are two functions that allow you to connect and request separately They are httpc open and httpc request You must use httpc request to make a HEAD request You may also make GET and POST requests with this function as it allows you to specify the request method The other five functions couple the connect and request tasks and are method specific They differ in the form that the resource and its server are identified The connect request functions are e httpc_get connect and GET e httpc_get_url connect and GET e httpc_post connect and POST e httpc_post_ext connect and POST e httpc_post_url connect and POST 6 2 3 Read Server Response Functions A valid HTTP server response has a fixed structure The HTTP client may read any of the header lines and or the optional message body using the following functions e httpc read header read the next header from the response e httpc read bodv read bytes from the body of the response 6 2 4 Miscellaneous Functions e httpc close release resources for the specified socket e httpc headermatch find string in header
269. from which data is copied len Length of the above buffer RETURN VALUE 0 No data was written because 1 en was zero or because a local buffer is full e g when writing toan underlving filesvstem that streams data to a peer 1 len The specified number of characters has been copied from the supplied buffer and the current file position has been advanced by that many bytes Possibly less than 1en bytes may be written in which case the server should attempt to write the remaining data later The following return values are negatives of the values defined in errno lib e EINVAL len parameter was lt 0 e EBADF The specified handle was not open or invalid e ENOSPC There is insufficient space in the underlying filesystem or the file cannot be extended EPERM The file resource does not support writing e g xmem files or a read only filesystem Any other negative values indicate an error SEE ALSO sspec close sspec read sspec seek sspec tell sspec open 136 rabbit com Server Utilitv Librarv RABE Tete 4 HTTP SERVER This chapter is intended to be a detailed description of the HTTP server and how it interfaces to other libraries such as Zserver and TCP IP For an overview of how these libraries interface with one another and with your application please see Chapter 2 Web Enabling Your Application An HTTP Hypertext Transfer Protocol server makes HTML Hypertext Markup Language pages and other
270. get a chance to run except interrupts It is preferable to return to the HTTP server which in turn can return to the application before coming back into the CGI 176 rabbit com HTTP Server CGI Return Codes This is where the CGI return code becomes important Up to now the return code has always been zero which means continue as usual However some of the APIs such as http _abortCGI override this There are several other legitimate values for the return code e CGI_MORE Call back again when free space in transmit buffer e CGI DONE CGI has finished writing data to the client e CGI_SEND Send the data null term string in the main buffer e CGI SEND DONE combination of the above two Action Code CGI CONTINUE In the case we are discussing the CGI MORE return code is used This tells the server that the CGI func tion is busv trving to do something but it could not complete the task It wants to be called back again but without anv new incoming data Thus if the CGI function returns CGI MORE the HTTP server will eventuallv come back with a special action code which has not been mentioned yet called CGI CONTINUE The CGI needs to respond to this code so that it can continue doing what it was trving before This implies that the CGI will need to remember at least a bit of information like how many bytes of the total it successfully wrote For this it can use the state and cond variables The foll
271. getContext ServerContext http getContext HttpState state DESCRIPTION Return the current HTTP server context The context pointer is required by many zserver resource handler functions NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Pointer to the HTTP server s context structure See zserver documentation LIBRARY HTTP LIB SEE ALSO http_getAction 204 rabbit com HTTP Server http getData char http getData HttpState state DESCRIPTION Return a pointer to the data that is available It is only valid to call this if the action code is one of CGI DATA CGI PROLOG CGI_EPILOG CGI HEADER or CGI_ EOF When CGI_DATA this is the next chunk of data received as the content of the current part of a multi part transfer The data arrives in arbitrary amounts CRLF boundaries if any are not re spected and the data may contain NULLs and other binary values THE CGI MUST CONSUME ALL DATA PROVIDED since the data will not be presented again on the next call When CGI_ PROLOG this is data that occurs before the first boundary part but after the main HTTP headers This data like that for CGI DATA is not line oriented When CGI_EPILOG CGI_HEADER or CGI_ EOF the data will be a complete line of input with the terminating CRLF stripped off The returned string will also be null terminated When CGI_EOF the data if an
272. getformtitle char sspec getformtitle int form DESCRIPTION Gets the title for an automatically generated form PARAMETERS form server spec index of the form RETURN VALUE NULL Failure NULL Success title string SEE ALSO sspec setformtitle TCP IP Manual Vol 2 rabbit com 89 sspec getfunction void sspec getfunction int sspec DESCRIPTION Returns a pointer to the function represented by the sspec index The entry must have been created asa SSPEC FUNCTION orasaSSPEC CGI PARAMETERS sspec spec index RETURN VALUE NULL Failure NULL Success pointer to requested function SEE ALSO sspec addfunction sspec getfvdesc char sspec getfvdesc int form int var DESCRIPTION Gets the description of a variable that is displayed in the HTML form table PARAMETERS form spec index of the form var Index into the FormVar array of the variable RETURN VALUE NULL Failure NULL Success description string SEE ALSO sspec setfvdesc 90 rabbit com Server Utilitv Librarv sspec getfventrytype int sspec getfventrytype int form int var DESCRIPTION Gets the type of form entry element that should be used for the given variable PARAMETERS form spec index of the form var Index into the FormVar array of the variable RETURN VALUE 1 Failure Type of form entry element on success HTML FORM TEXT is a text box HTML FORM PULLDOWN isa pull down menu S
273. gram Flash Serial Flash i TCP IP Manual Vol 2 rabbit com 11 Let us work again from left to right in the Application block To reiterate the Application block represents the coding that you have to do First there is the compile time initialization Taking the super simple example illustrated in Figure 2 2 Dynamic C code is given with the relevant part highlighted in boldface define TCPCONFIG 1 use dertcp lib use http lib ximport hellowww html hellowww html SSPEC MIMETABLE START SSPEC MIME html text htmi SSPEC MIMETABLE END SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE hellowww html hellowww html SSPEC RESOURCETABLE END void main sock init http init for http handler The first boldface line is the ximport directive This tells the compiler to include the specified file in the program flash and make it accessible via the hellowww htmi constant In the diagram the arrow from compile time initialization to program flash represents this inclusion In most cases you would be including more than just one file The three lines starting with SSPEC_MIMETABLE START are initialization statements for the MIME table In this case there is a single mapping from resources that end with html to a MIME type of text html All MIME types are registered with the relevant standards body and must be entered correctly so that the browser does not get confused text html is
274. har far url DESCRIPTION Connect to the HTTP server referenced in url and GET the resource referenced in url This function is like httpc get but with a URL instead of separate host authentication port and file parameters PARAMETERS s Pointer to socket structure to use for connection url URL in the following format items in are optional http user pass Jhostnamel portj filename RETURN VALUE 0 Success EINVAL Error parsing URL E2BIG URL is too big to parse Increase URL MAX BUFFER SIZE to handle larger URLs NETERR_DNSERROR Can t resolve hostname EXAMPLE Connect to google com and request their homepage httpc get _url amp hsock http www google com TCP IP Manual Vol 2 rabbit com 299 httpc headermatch char far httpc headermatch char far header char far match DESCRIPTION See if a header matches a particular field name PARAMETERS header Pointer to a line from the headers match Header to match RETURN VALUE NULL header does not match non NULL far pointer to value of header EXAMPLE returns a pointer to text html httpc headermatch Content Type text html Content Type 300 rabbit com HTTP Client httpe init int httpc init httpc Socket far s tcp Socket tt DESCRIPTION This function initializes the httpc Socket structure and binds it to tcp Socket t NOTE httpc_init isamacroforhttpc_init if using IF_A
275. haracter will be deleted as part of normal mail process ing Thus to actually send a line starting with you must start the line with i e double up an initial period PARAMETERS to from subject message RETURN VALUE None SEE ALSO String containing the e mail address of the destination Maximum of 192 characters Currently only one recipient is supported String containing the e mail address of the source Maximum of 192 charac ters for a return address If no return should be sent by receiver then pass an empty string String containing the subject of the message This may be NULL in which case no subject line will be sent This string may also contain embedded r n sequences so that additional mail header lines may be inserted The length of this string is unlimited String containing the message This string must not contain the byte se quence r n r n CRLF CRLF as this is used to mark the end of the e mail and will be appended to the e mail automatically This message must be null terminated and is only allowed to contain 7 bit characters You can pass NULL if a data handler is to be used to generate the message smtp mailtick smtp status smtp sendmailxmem 360 rabbit com SMTP Mail Client smtp sendmailxmem void smtp sendmailxmem char to char from char subject long message long messagelen DESCRIPTION Start an e mail being sent This is intended for moderately
276. hat uses this function takes one parameter the name of another command Zconsole outputs the associated help text for the requested com mand The help text is the text file referenced in the third field of the ConsoleCommand structure con_list_files This function lists the files in the file system and their file sizes A command that uses this function takes no parameters con_list_variables This function displays the names and types of all variables A command that uses this function takes no parameters con_loginname This function stores an identifier that will be remembered across power cycles with battery backed RAM The existence of the identifier will be used to prompt the user of a new console session Before console access to the controller is allowed a valid identifier must be entered in response to the prompt A command that uses this function takes one parameter an identifier that will be used as the login name 464 rabbit com General Purpose Console con_loginpassword This function stores an identifier that will be remembered across power cycles with battery backed RAM The existence of the identifier will be used to prompt the user for a password after a login name has been entered Before console access to the controller is allowed a valid identifier must be entered in response to the prompt A command that uses this function takes no parameters on the command line but requires a series of user inputs in respo
277. he application the use of the main TCP IP libraries all brought in by dertcp 1lib and the HTTP server library which also brings in the resource manager library zserver lib ximport samples tcpip rabbitweb pages humiditv monitor zhtmi monitor zhtml ximport samples tcpip rabbitweb pages humidity admin zhtml admin zhtml SSPEC MIMETABLE START SSPEC MIME FUNC zhtml text html zhtml_handler SSPEC MIME html text html SSPEC MIMETABLE END SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE index zhtml monitor zhtml SSPEC RESOURCE XMEMFILE admin index zhtml admin zhtml SSPEC RESOURCETABLE END The HTML pages are copied to Rabbit memory using ximport The first one is a status page and the second one is a configuration interface Next the MIME type mapping table is set up This allows zhtml handler to be called when a file with the extension zhtml is processed Then the static resource table is set up which gives the server access to the files that were just copied in using ximport The first parameter is the name of the resource and the second parameter is its address TCP IP Manual Vol 2 rabbit com 251 web groups admin The RabbitWeb server has a concept of user groups which are created using the compiler directive web groups Users can be added to and removed from these groups at runtime by calling the API functions sauth adduser and sauth removeuser The purpose
278. he fields in each resource table static or dynamic are usually manipulated via Zserver functions or by using the SSPEC_RESOURCE macros The field descriptions below are for reference only type This field tells the server if the entry is a file variable or function SSPEC FILE SSPEC VARIABLE SSPEC FUNCTION etc name This field contains the resource name as a null terminated string data Location of data when FILE is the type of data or maximum number of variables in a form when SSPEC_ FORM is the type of data addr Address of function or variable when SSPEC_FUNCTION SSPEC_CGI or SSPEC VARIABLE is the type of data Address of form struct for SSPEC_FORM vartype Type of variable when SSPEC VARIABLE is the type of data or length of data when FILE is the type of data and the length is needed e g a root file For SSPEC_HARDLINK contains the sspec index number of a http flashspecor server spec entry format sprintf format for a variable or form title for a form or base address for SSPEC ROOTFILE For SSPEC LINK points to a string containing the linked to resource name perm Permissions associated with this resource If realm subfield is NULL then the permissions table is consulted as for filesvstem resources Note this field used to be char for the realm string only Programs that used this feature need to be modified This structure is detailed under ServerPermissions There are some other fields that ar
279. he first macro represents the initial baud rate for serial port C The second macro is passed the port number for telnet If you change the number of I O streams update NUM CONSOLES above conse ConsolelO console ioll 41 CONSOLE IO SERC 57600 CONSOLE IO TELNET 23 FF FF F FH F ke This array defines the commands that are available in the console The first parameter for the ConsoleCommand structure is the command specification i e how the console recognizes acommand The second parameter is the function to call when the command is recognized The third parameter is the location of the ximport ed help file for the command Note that the second parameter can be NULL which is useful if help information is needed for something that is not a command like for the SET command below the help file for SET contains a list of all of the set commands Also note the entry for the command which is used to set up the help text that is displayed when the help command is used by itself that is with no parameters const ConsoleCommand console commands HELLO WORLD hello world 0 ECHO Con echo help echo txt HELP con help help help txt mi NULL help tze NISEL TNULD A melp ser eze h SET PARAM con set param help set param txt 1X tant Tate This array sets up the error messages that can be generated CON_STANDARD_ERRORS is amacro that expands to the st
280. he name of a local file but this is a convention only The size 50 parameter specifies the number of characters that the browser will display for file name selection lt TR gt lt TABLE gt lt INPUT TYPE SUBMIT VALUE Upload gt It is necessary to supply a type submit form element The user presses this button to start to post upload process Note that this is another input field however if you leave out the name parameter as in this exam ple then the browser will not send the value of this button back with the form submission If there is only one submit button then there is no need to name it lt FORM gt lt body gt lt html gt Close and complete the form body and entire page If you have an existing application you can take out the relevant parts of the above and insert them in your existing web page The relevant parts are the enctype multipart form data parameter in the lt FORMS element and the lt INPUT type file gt element TCP IP Manual Vol 2 rabbit com 167 If you have an existing application that processes the form data submission you will need to rewrite the CGI function that handles the submitted data This is because the enct ype parameter changes the syntax that the browser uses to encode the data In short you will need to rewrite the CGI as a new style CGI as described in Step 6 Writing a CGI Function Having created the HTML file with the upload form it is necessary to impo
281. he sample program Samples tcpip pop3 pop c provides an example of this style of call back 11 3 2 POP_PARSE_EXTRA call back If POP_PARSE EXTRA is defined you need to provide a call back function with the following proto type int storemail int number char to char from char subject char body int size number body and size are the same as before to has the e mail address of who this e mail was sent to from has the e mail address of who sent this e mail subject has the subject line of the e mail These new fields should be used only the first time your call back is called with a new number field In subsequent calls these fields are not guaranteed to have accurate information See parse extra c in Section 11 5 for an example of this type of call back 366 rabbit com POP3 Client 11 4 API Functions pop3 init int pop3 init int storemail DESCRIPTION This function must be called before any other POP3 function is called It will set the call back function where the incoming e mail will be passed to This probably should only be called once PARAMETERS storemail A function pointer to the call back function RETURN VALUE 0 Success 1 Failure LIBRARY POP3 LIB TCP IP User s Manual rabbit com 367 pop3 getmail int pop3 getmail char username char password long server DESCRIPTION This function will initiate receiving e mail a POP3 request to a remote e mail server IMPO
282. his data structure is used to send and receive The tftp state structure which is required for many of the API functions in TFTP LIB may be allocated either in root data memory or in extended memory This structure is approximately 155 bytes long typedef struct tftp state bvte state Current state LSB indicates read 0 or write 1 Other bits determine state within this see below long buf addr Physical address of buffer word buf len Length of buffer word buf used Amount Tx or Rx from to buffer word next bik Next expected block or next to Tx word my_tid UDP port number used by this host udp_Socket sock UDP socket to use longword rem_ip IP address of remote host longword timeout ms timer value for next timeout char retry retransmit retry counter char flags miscellaneous flags see below Following fields not used after initial request has been acknowledged char mode Translation mode see below char file 129 File name on remote host TFTP server NULL terminated This field will be overwritten with a NULL term error message from the server if an error occurs Is The following macros are valid for tftp_state gt mode define TFTP MODE NETASCII 0 ASCII text define TFTP MODE OCTET 1 8 bit binary define TFTP MODE MAIL 2 Mail remote file name is email address e g user host blob org 9 3 API Functions Any of the following f
283. hold information about the form variables Be sure to allo cate enough entries in the array to hold all of the variables that will go in the form If more forms are needed then more of these arrays can be allocated FormVar myform 5 TCP IP Manual Vol 2 rabbit com 159 These variables will hold the indices in the TCP IP servers object list for the form and the form variables int var int form This array holds the possible values for the fail variable The fail variable will be used to make a pulldown menu in the HTML form const char const fail_options vamaaitum PAGE Email and page Nothing These lines initialize the form variables temphi 80 tempnow 72 templo 65 lmumieliliew O 3 strcpy fail Page The next line adds a form to the dynamic resource table The first parameter gives the name of the form When a browser requests the page my form htm1 the HTML form is generated and presented to the browser The second parameter gives the developer declared array in which form information will be saved The third parameter gives the number of entries in the my form array this number should match the one given in the mv form declaration above The fourth parameter indicates that this form should only be accessible to the HTTP server and not the FTP server SERVER_HTTP should always be given for HTML forms The return value is the index of the newly created form in the dynamic resourc
284. html but by html The name known to the server is determined by the name parameter of the file s resource table entry index html The next change is a new entry in the static resource table This reflects the shift in how the variable io state becomes known to the HTTP server Previously it was done using the web statement of RabbitWeb A second new entry in the resource table is for a CGI function that will handle the processing when io state is updated When using RabbitWeb this same form submission did not require a CGI The enhanced HTTP server took care of all the details for us Without RabbitWeb we have to do the work our selves Fortunately the new stvle CGIs make this job easier A detailed description of writing a new style CGI is given in Section 4 6 HTTP File Upload As we saw in Section 2 7 there isa CGI in http lib that processes file uploads to a filesystem If you study and understand Section 4 6 and the code in http defaultcCGI you will be able to write a new style CGI that will process the form that is sub mitted when io_state is changed 28 rabbit com Web Enabling Your Application Since we are not using RabbitWeb and have changed from using FAT to FS2 the HTML page must be changed As before all changes are in boldface lt HTML gt lt HEAD gt lt TITLE gt Web Variables lt TITLE gt lt HEAD gt lt BODY gt lt H1 gt Web Variables lt H1 gt lt P gt The current value of io state is lt
285. iable foo to be updated whenever a successful update is made Here s how it works e The developer gives foo an initial value e Included in a form is a hidden field that represents the value of foo see the HTML in the SCRIPT tags above In the JavaScript above the lt z echo foo gt is first replaced by the HTTP server with the current value of foo e Inthe browser the JavaScript is executed which takes the value of foo and adds one to it This is the value of the hidden input field e When the form data is submitted the automatic error checking will recognize that the value of foo has been updated along with the other data If all data passes the error checking then the value of foo is incremented by the user s increment value function e If when the form data is submitted the current value of foo plus one does not match the submitted value of foo then we know that an interim update has occurred The value of foo is marked as an error by the server which can be handled by the developer s ZHTML page Note that none of the updated form values will be committed since an error was triggered 266 rabbit com RabbitWeb 5 3 ZHTML Scripting Language This section describes the ZHTML scripting language a set of features that can be included in HTML pages These features interact with some new features in Dynamic C described in Section 5 2 to create an enhanced HTTP server 5 3 1 SSI Tags Statements and Var
286. iable that will be displaved in the first column of the form table If this name is not set it defaults to the name for the variable in the resource table temphi in this case The first parameter is the form in which the variable is located the second parameter is the variable index within the form and the third parameter is the name for the form variable sspec setfvname form var High Temp p This function sets the description of the form variable which is displaved in the third column of the form table sspec setfvdesc form var Maximum in temperature range 60 90 amp deg F This function sets the length of the string representation of the form variable In this case the text box for the form variable in the HTML form will be 5 characters long If the user enters a value longer than 5 char acters the extra characters will be ignored sspec secivlen ierm var 5 This function sets the range of values for the given form variable The variable must be within the range of 60 to 90 inclusive or an error will be generated when the form is submitted PSPS _Seicivramge comm Wee 60 BO 5 This concludes setting up the first variable The next five lines set up the second variable which represents the current temperature var sspec addvariable tempnow amp tempnow INT16 d SERVER_HTTP var sspec addfv form var sSspec Sebiviene comm wes Cuseeeme Teme 5 sspec setivdesc form var Cu
287. iables The new server parsed tag is similar to SSI tags prior to Dynamic C version 8 5 in that they are included in HTML pages and are processed by the server before sending the page to the browser The new tags all have the following syntax lt z statement gt That is a valid statement is preceded by lt z and followed by gt This follows the naming scheme for PHP and XML tags lt php and lt xml respectively and so follows standard conventions To surround a block of HTML do the following lt z statement gt lt H1 gt HTML code here lt H1 gt lt z l is The lt z 7 tags delimit statements This means that you cannot put two statements in a single set of tags For example lt z if error foo echo foo 72 is not valid The if echo and statements must be separated by the lt z 79 tags like the following lt z if error foo gt lt z echo Sfoo 725 lt z gt Note that is considered a statement in ZHTML the close block statement and must always be in its own lt z 7P tags The simplest use of the new SSI tag simply prints the given variable lt z print foo gt The value of the given variable is displayed using a reasonable default printf specifier For example if foo isan int print uses the conversion specifier d foo must be registered with the web server How to register a variable with the web server is de
288. iates a file extension with a MIME type Multipurpose Internet Mail Extension and a function that handles the MIME type Users can override HTTP MAXNAME defaults to 20 characters in their source file If the function pointer given is NULL then the default han dler which sends the content verbatim is used typedef struct char extension 10 char type HTTP_MAXNAME int fptr HttpState MIMETvpeMap For example to create an HTTP server that can serve files with html or gif extensions the following decla ration is required in the application code SSPEC MIMETABLE START SSPEC MIME html text html SSPEC MIME gif image gif SSPEC MIMETABLE END Use of the above macros is the recommended method for maintaining forward compatibility For more information see Section 3 2 5 2 Static MIME Type Table All these macros are doing is generating the correct C syntax for a static constant initializer Note that servers that do not implement MIME such as FTP do not require a MIME table to be defined Currently this table is required only for HTTP 32 rabbit com Server Utility Library 3 1 2 ServerSpec Structure This structure is used for both the static and dynamic resource tables The only difference between these two tables is that one is a constant initialized at compile time and the other is created at runtime in RAM and thus modifiable Historical note The Ht tpSpec data structure in HTTP li
289. ibes the number of 4KB xmem RAM buffers used for decompression This definition is used by the zimport lib library TCP IP Manual Vol 2 rabbit com 43 For details on compression ratios memory usage and performance please see Technical Note 234 File Compression For more information on using zimport and the support libraries please see the Dynamic C User s Manual and the Dynamic C Function Reference Manual All of these documents are available on our website www rabbit com 3 4 HTML Forms This facility is oriented towards the HTTP server however it is Zserver that actually handles the form data as a special resource type in the dynamic resource table only Defining FORM_ERROR_ BUF is required to use the HTML form functionality in ZSERVER LIB The value assigned to this macro is the number of bytes to reserve in root memory for the buffer used for form pro cessing This buffer must be large enough to hold the name and value for each variable plus four bytes for each variable An array of type FormVar must be declared to hold information about the form variables Be sure to allocate enough entries in the array to hold all of the variables that will go in the form If more forms are needed then more of these arrays can be allocated Please see Section 4 5 4 on page 159 for an example program Starting with Dynamic C 8 50 a more flexible way of supporting form generation is available with Rabbit Web See Chapter 5 for
290. ill require 4 more bytes of stack The default is 32 SNMP MAX COMMUNITY NAME The maximum string length of community names i e passwords The default is 16 SNMP MAX COMMUNITIES The number of communities recognized by the SNMP agent The default is 2 or 3 if traps are sup ported SNMP MIB SIZE Defines the maximum size of the MIB tree structure resident in xmem The default size is 4096 bytes The default allows for about 100 objects SNMP PORT The UDP port that the agent will listen on The default is 161 SNMP _ TRAP PORT The UDP port that the agent will send traps to on the SNMP manager The default is 162 SNMP TRAPS Must be defined in the application to support trap sending USE MIB Defining this macro is only necessary if MIB functionality is being used without SNMP TCP IP Manual Vol 2 rabbit com 391 12 4 API Functions This section describes all of the API functions available in SNMP LIB and MIB LIB snmp_add snmp add community snmp append binarv oid snmp append binarv stem snmp append oid snmp append parse oid snmp append parse stem snmp append stem snmp communitv mask snmp communitv name snmp copv oid snmp delete snmp format oid snmp get snmp get indexed snmp get next snmp init parms snmp last index snmp last int snmp last len snmp last long snmp last maxlen snmp last mem snmp last objectIiD snmp last snmp tvpe snmp last tvpe snmp last xmem snmp monitor snmp prin
291. in greater detail below 4 5 2 1 SSI Feature SSI commands are an extension of the HTML comment command lt This is a comment gt They allow dynamic changes to HTML files and are resolved at the server side so the client never sees them HTML files that need to be parsed because they contain SSI commands are conventionally recognized by the HTTP server by the resource name extension shtml The supported SSI commands are e echo var e exec cmd e include file They are used by inserting the command into an HTML file lt include file anyfile gt The server replaces the command include file with the contents of anyfile exec cmd executes a command i e and old style CGI and replaces the SSI command with the output 1 This is just a convention If you add a MIMETypeMap entry SSPEC MIME FUNCC shtmi text html shtml handler then you are following this convention TCP IP Manual Vol 2 rabbit com 151 Dynamically Changing the Display of a Variable on a Web Page The Ssi shtml file located in Samples Tcpip Http Pages gives an example of dynamically changing a variable on a web page using echo var lt img SRC Tel iiecheo wer leci sis In an shtml file the lt echo var ledi gt is replaced by the value of the variable Led1 from the static resource table SSPEC RESOURCETABLE START SSPEC RESOURCE ROOTVAR SSPEC RESOURCE ROOTVAR SSPEC RESOURCE ROOTVAR SSPEC RE
292. ings can be larger than four bytes so real istically this macro only affects strings Please note that the macro HTTP MAXBUFFER limits the size of the root buffer that is used to hold the output of ZHTML commands Strings the size of RWEB ZHTML MAXVARLEN are outputs of ZHTML commands and will need to fit in the buffer of size HTTP MAXBUFFER if they are to be sent over the net work This effectively limits the value of RWEB ZHTML MAXVARLEN to be no more than the value of HTTP MAXBUFFER Both macros default to 256 If RWEB ZHTML MAXVARLEN is increased HTTP MAXBUFFER should be increased by the same amount RWEB WEB ERROR MAXBUFFER This macro defines the size of a buffer in xmem that is used to hold WEB ERROR error messages This buffer limits the total size of the error messages associated with a single form update Defaults to 512 TCP IP Manual Vol 2 rabbit com 289 5 5 3 Compiler Directives The RabbitWeb compiler directives are summarized here web Registers a variable array or a structure with the server For more information see Section 5 2 1 The web statement has several optional parts that can be used when a variable or array or structure is registered The optional parts are e Anerror checking expression to limit the acceptable values that are submitted For more information see Section 5 2 2 A macro called WEB_ERROR can be included in the error checking expression to associate a string with an error For more info
293. int io state web io state void mv io polling void void main sock init http init for 74 mv io polling http handler void my io polling io state read that io device The differences between the above code and the tov example in the previous section are in boldface All the differences relate to the use of RabbitWeb The first addition is a define of USE RABBITWEB This is necessary in order to include the necessary library code Next there is a modification to the MIME table The SSPEC_MIME_FUNC macro defines an entry that says that if the resource name ends with html then the MIME type is text html as before and there is a special scripting function that must be run by the HTTP server This scripting function is called zhtml handler it is provided by the HTTP library ZHTML is the unique embedded scripting lan guage that converts script files into ordinary HTML so the browser can understand it The int io state and web statements define and register a web variable Such a variable is an ordi nary global variable as far as your C program is concerned In addition the script is able to access it 1 Most applications will want to use a different resource suffix to distinguish between ordinary HTML files and script files The samples provided with dynamic C use zhtml for script files and html for plain HTML In this sample we only have script files so it is convenient to
294. ion This function may be used by CGI applica tions to determine if a socket is readable or not See sock_readable for more information PARAMETER state HTTP state structure as provided in the first parameter to the CGI function RETURN VALUE If parameter is a TCP or SSL server 0 socket is not readable It was aborted by the application or the peer has closed the socket and all pending data has been read by the application This can be used as a definitive EOF indica tion for a receive stream non zero the socket is readable The amount of data that the socket would deliver is this value minus 1 which may turn out to be zero if the socket s buffer is temporarily empty or the socket is not yet connected to a peer If parameter is a UDP server 0 socket is not open non zero socket is open This value minus 1 equals the size of the next datagram in the receive buffer that would be returned by udp recvfrom etc Note that ICMP error messages are also considered if the socket is set up to receive ICMP messages LIBRARY HTTP LIB 236 rabbit com HTTP Server http sock writable int http sock writable HttpState state DESCRIPTION HTTP wrapper function for socket writable function This function may be used by CGI applica tions to determine if a socket is writable or not See sock_writable for more information PARAMETER state HTTP state structure as provided in the first parameter to the CGI function RE
295. ioned above The POP3 library parses the incoming mail more fully to provide the Sender Recipient Subject and Body fields as separate items to the call back function TCP IP Manual Vol 2 rabbit com 365 11 2 Steps to Receive E mail l pop3_ init is called to provide the POP3 library with a call back function This call back will be used to provide you the incoming data This function is usually called once 2 pop3 getmail is called to start the e mail being received and to provide the library with e mail account information 3 pop3_tick is called as long as it returns POP_PENDING to actually run the library The library will call the function you provided pop3 init several times to give you the e mail 11 3 Call Back Function There are two types of call back functions which are described here 11 3 1 Normal call back When not using POP_PARSE EXTRA you need to provide a function with the following prototype int storemail int number char buf int size The parameter number is the number of the e mail being transferred usually 1 for the first 2 for the sec ond but not necessarily The numbers are only guaranteed to be unique between all e mails transferred The buf parameter is the text buffer containing one line of the incoming e mail This must be copied out immediately as the buffer will be different when the next line comes in and your call back is called again size is the number of bytes in buf T
296. is a wrapper fortftp init andtftp tick Itdoes not return until the complete file is transferred or an error occurs Note that approximately 750 bytes of free stack will be required by this func tion PARAMETERS put 0 get file from remote host 1 put file to host buf addr Physical address of data buffer len Length of data buffer This is both an input and a return parameter It should be initialized to the buffer length On return it will be set to the actual length received for a get or unchanged for a put mode Data representation O NETASCI 1 OCTET binary 2 MAIL host Remote host name or NULL to use default BOOTP host hostfile Name of file on remote host or e mail address for mail sock UDP socket to use or NULL to re use BOOTP socket if available RETURN VALUE 0 OK transfer complete 1 Error from remote side transfer terminated In this case ts_addr gt file will be overwritten with a NULL terminated error message from the server 2 Error could not contact remote host or lost contact 3 Timed out transfer terminated 4 sock parameter was NULL 7 host was NULL LIBRARY TFTP LIB TCP IP Manual Vol 2 rabbit com 351 352 rabbit com TFTP Client RABBIT 10 SMTP MAIL CLIENT SMTP Simple Mail Transfer Protocol is one of the most common ways of sending e mail SMTP is a simple text conversation across a TCP IP connection The SMTP server usually resides on TCP port 25 waiting fo
297. is in use It is used by the resource manager to apply access permissions to the resources contained in a filesystem This is necessary because not all filesystems can associate file ownership and access rights with individual files e The static resource table This is the classic method of defining resources in Dynamic C This table is optional since all necessary resources may be loaded in a filesystem or in the dynamic resource table Most applications will contain at least a few static resources as an initial default or fallback or for data that will never change such as a logo image e Program flash This really represents the loading of resource files into program memory via the ximport directive There will almost always need to be a few ximport files but this can be limited to a few kilobytes total 2 Runtime initialization Your main function needs to call some specific library functions once only when it starts e sock init This is always mandatory It initializes the TCP IP networking system e sspec automount This is optional It initializes the available filesystems FS2 and or FAT for use by the resource manager Zserver e http init This is mandatory It initializes the HTTP server e Various functions for setting up a user ID table the rule table and or the dynamic resource table These are optional but would be used in the majority of applications The user ID table can only be initialized at
298. is is one of the following enumerated values e MIME DISP NONE unspecified disposition e MIME DISP INLINE the content is to be displayed inline e MIME DISP ATTACHMENT the content is only to be displayed if there is some action by the user e MIME DISP FORMDATA the content is form field data or an uploaded file Of these only NONE and FORMDATA are really relevant to HTTP It is only valid to call this when the action code is CGI_ START CGI_DATA or CGI_ END NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Content disposition code as documented above LIBRARY HTTP LIB SEE ALSO http_getAction TCP IP Manual Vol 2 rabbit com 201 http getContentLength long http getContentLength HttpState state DESCRIPTION Return the length of data in the current part of a multi part data stream The return value is inter preted differently depending on the action code It is only valid to call this when the action code is CGI_ START CGI_DATA or CGI_ END When CGI_ START this returns the value of the ContentLength header for this part or 1 if there was no such header When CGI_DATA or CGI END it is the total number of bytes that have actually been read and presented to the CGI This increases for each CGI DATA call until it represents the total content length when action is CGI END NOTE This is implemented
299. is macro specifies the mask that is passed into the servermask parameter in sspec addfsfile calls when a new file is created In particular this defines which serv ers will be allowed to access this file By default it is defined to SERVER_FTP SERVER WRITABLE FIP DTPTIMEOUT The default is 16 the same as FTP_ TIMEOUT This applies to the data transfer port instead of the command port The data transfer port is involved with get store commands as well as direc tory listings FIP EXTENSIONS The macro is not defined by default Define it to allow the server to recognize the DELE SIZE and MDTM commands If this macro is defined then the FTP handler structure FTPhandlers is augmented with pointers to mdtm and delete handlers FTP INTERFACE This macro defaults to IF DEFAULT i e the single default interface Define to IF_ANY if FTP sessions can be accepted on any active interface or a specific interface number e g IF_ETH0 to allow sessions on that interface only Note that you are currently limited to a single interface or all interfaces This macro is only relevant starting with Dynamic C version 7 30 FTP MAXLINE The default is 256 the number of bytes of the working buffer in each server This is also the max imum size of each network read write The default value of 256 is the minimum value that allows the server to function properly FTP MAXSERVERS The default is 1 the number of simultaneous connections the FTP server
300. is not consulted SSPEC VIRTUAL is not a valid handle for other functions SEE ALSO sspec findnextfile 85 TCP IP Manual Vol 2 rabbit com sspec findfsname int sspec findfsname byte filenum word server DESCRIPTION Find the server spec entry for fi lenum The entry must be of type SSPEC FSFILE and be allowed with the specified server PARAMETERS filenum File to search for This value is the number passed in as the second parameter to fcreate or the return value from fcreate_unused server The server making the request e g SERVER HTTP RETURN VALUE 1 Failure 20 Success index into resource list SEE ALSO sspec_findname 86 rabbit com Server Utility Library sspec findnextfile int sspec findnextfile int start word servermask DESCRIPTION Find the first spec file entry at or following the start spec that is accessible by the given server When the end of the RAM entries is reached the flash entries are searched Virtual filesystem en tries are not considered Only entries for which sspec gettvpe would return SSPEC FILE are considered If vou are using this function to iterate through the available resources then the caller is respon sible for incrementing the starting point To do this vou can call the function sspec nexthandle which will return the next valid handle after the given one or 1 if no more handles PARAMETERS start The array index at which to begin the s
301. isting of the available files The listing shows only the files that the logged in user can access Notice the definition for TCP_CONFIG When the value for this macro exceeds 100 a special configura tion file is pulled in that will not be overridden by future updates of Dynamic C In the file CUSTOM CONFIG LIB you may specify any network configuration that suits your purposes Please see LIB TCPIP TCP CONFIG LIB for examples of setting up a library of configuration options 8 5 Getting Through a Firewall If a client is behind a firewall it is incumbent upon the client to request that the server do a passive open on its data port instead of the normal active open This is so that the client can then do an active open using the passively opened data port of the server thus getting through the firewall Typically the server would not be behind a firewall 8 6 FTP Server Commands The following commands are recognized by the FTP server The reply codes sent in response to these com mands are detailed in Section 8 7 on page 344 They are noted here to associate them with the commands that may cause them to be sent are Possible Command Description Reply Codes ADOR The current data transfer completes before the abort command is 226 read by the server CDUP A special case of CWD Change Working Directory the parent of 250 431 the working directory is changed to be the working directory i CWD Changes wor
302. it be a normal integral web registered variable a loop variable a numeric literal or a count expression For example lt z if foo 0 gt HTML code lt z Is or lt z if foo foo gt HTML code lt z gt are both legal TCP IP Manual Vol 2 rabbit com 269 The table from the previous example was modified to allow one of the values to be displayed in an input widget whereas all the other values are simply displayed lt TABLE gt lt TR gt lt z for SA 0 A lt count foo 0 SA gt lt TD gt lt z if SA 3 gt lt INPUT TYPE text NAME lt z varname Sfoo SA gt VALUE lt z print S foo SA gt gt gja gt lt z if A t 3 gt lt z print foo A gt pe gt lt z gt lt TR gt lt TABLE gt The if statements can be nested Even for loops can be nested within other for loops The nesting level has an upper limit defined by the macro ZHTML MAX BLOCKS which has a default value of 4 5 3 3 Selection Variables Put together i f statements and for loops are useful for selection type variables To iterate through all possible values of a selection type variable and output the appropriate lt OPTION gt or lt OPTION SELECTED gt tags something like the following can be done lt z for SA 0 SA lt count select var SA gt lt OPTION lt z if selected select_var A gt SELECT
303. its own error checking expression struct foo bar web bar a 0 lt Sbar a amp amp Sbar a lt 10 web bar b 5 lt Sbar b amp amp Sbar b lt 5 In the two code sections shown above two similar methods for registering a structure are presented The difference between these two methods is that the first one registers the entire structure as a single web vari able and the second one registers each element as separate web variables In the first case a change to any element of the structure causes the guard expression to be evaluated In other words changing either bar a or bar b will cause the guard expression to be evaluated and so both variables will be checked In the second case bar a and bar b are registered as independent web variables and so changing one does not cause the guard expression of the other one to be evaluated Structure elements can be specified separately in arrays of structures as well struct foo bar 3 web bar a 0 lt Sbar a web bar b Sbar a gt 10 The same holds true for arrays of structures in which the structures themselves contain arrays struct foo int a int b 2 E struct foo bar 3 web bar a 0 lt Sbar a Of special note are variables with more than one array index Which index is referring to Consider the following example web bar e blel 0 c Sbar 0 b 1 amp amp S bar 0 b 1 lt 10 In this case the
304. ivered reli ably i e the message may be lost in the network There is no acknowledgement of trap receipt by the agent You must define SNMP_TRAPS to use this function PARAMETERS ipaddr IP address of network management agent c index Community table index This is the value returned by snmp add communitv ormav be SNMP TRAPDEST for the pre defined default trap destination communitv trap num Trap number to use This must be 2 0 Negative numbers are reserved for SNMP predefined trap tvpes Otherwise generic traps are sent noids Number of MIB tree indices in the following list mav be zero This must be less than or equal SNOMP MAX BINDINGS indices Array of MIB tree indices Each element in this array is the MIB tree index of an object to send with the trap message Tree indices may be obtained us ing snmp last index and other MIB functions RETURN VALUE 1 error trap not sent because there was an error constructing the message probably because too many or too long variables were specified or because the message could not be sent using UDP Otherwise length of constructed message returned LIBRARY SNMP LIB SEE ALSO snmp_monitor 442 rabbit com SNMP snmp unmonitor int snmp unmonitor word index DESCRIPTION Stop monitoring the object that was previously monitored by snmp monitor This function must be used if the object being monitored is to be deleted from the MIB tree You must define SNMP_ T
305. keeps returning CGI_MORE until the operation either completes or permanently fails The above code does not show the CGI returning zero Look at the code in the default handler http defaultcCGI to see this being done You may notice the repetition of parts of this code for example the calls to http switch CGI This is for clarity you can condense some of this by factoring out the common parts The CGI remembers where it was up to by using another cond variable COND_ LEN This is all that is required since the contents of http getData and its length are guaranteed not to be changed on the next call when the CGI returns CGI_ MORE Writing Responses to the Client from a CGI Function A CGI function is able to generate all or part of the response to the client To do this it has to follow the HTTP specification That is it must write the response headers plus the HTML content The HTTP head ers must be the first thing written At a minimum the header lines look like the following HTTP 1 0 200 OK Date Sun 20 Jan 1980 23 27 10 GMT Content Type text html NOTE Each line must be terminated with a CRLF that is r n and there must be a blank line after the last header The date string can be constructed using the http_date_str function 178 rabbit com HTTP Server You can create the headers in one hit using the following code char date 30 sprintf http getData s HTTP 1 0 200 OK r nDate s r nCon
306. king directory 250 431 DELE Delete the specified file 250 450 550 LIST Displays list of files requested by its argument in ls l format This 150 226 425 gives extra information about the file A eee rai 213 250 MDTM Shows the last modification time of the specified file 450 550 MODE Confirms the mode of data transmission Only stream mode is 200 504 supported Displays list of files requested by its argument with names only MEST This allows an application to further process the files End 220 429 Specifies no action except that the server send an OK reply It does NOOP 200 not affect any parameters or previously entered commands Password for the user name sent in clear text It is accepted only PASS after USER returns code 331 230 990 342 rabbit com FTP Server amas Possible Command Description Reply Codes Requests a passive open on a port that is not the default data port PASV The server responds with the host and port address on which itis 227 452 listening Changes the data port from the default port to the port specified in PORT the command s argument The argument is the concatenation of a _ 200 32 bit internet host address and a 16 bit TCP port address PWD Prints the working directory name 257 QUIT Closes the control connection If a data transfer is in progress the 221 connection will not be closed until it has completed RETR Transfer
307. known as its object identifier or OID The rules for naming and defining managed objects are specified by Structured Management Information SMD This formal definition is compiled by the SNMP manager allowing the manager to understand the structure of the MIB on the managed device In Section 12 2 we will look at a demo program that will clearly illustrate the correspondence between the SMI defined MIB used by the SNMP manager and the MIB used by the SNMP agent 12 1 2 SNMP Agent An agent listens on UDP port 161 SNMP_ PORT of its device for SNMP messages from a manager Pro grammatically the SNMP agent is fairly simple Any complexity lies in the organization of the managed objects that the agent accesses The agent sends messages back to the manager in response to the get get next and set requests that it receives For a get next request the agent returns the next OID in lexicographic order from the OID speci fied in the variable binding of the PDU Both get and set requests are atomic They may request acting on multiple managed objects but the agent will only process the request if all of the managed objects are accessible Agents may also send unsolicited messages to a manager These unsolicited messages are called traps They may be used to signal the manager that something has gone wrong perhaps a variable has gone out of range or a light bulb has burned out or they may be used for informational purposes 374 rabbit com SN
308. lash This function is deprecated as of Dynamic C 8 50 Use sspec findname PARAMETERS name Name in text of the spec to find RETURN VALUE The spec entry LIBRARY HTTP LIB http finishCGI int http finishCGI HttpState state DESCRIPTION Indicate to the HTTP server that this CGI has finished processing data from this multi part data stream The server reads and discards data to the end of the entire stream including epilog The next call to the CGI function will have an action code of CGI_ EOF or possibly CGI ABORT if there was a stream error PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE 0 LIBRARY HTTP LIB SEE ALSO http_getAction http_skipCGI http_abortCGI http_switchCGI http_abortCGI http_write 196 rabbit com HTTP Server http genHeader void http genHeader HttpState state char buf int buflen int code char content type int more hdrs char content DESCRIPTION This function builds HTTP headers to send in response to a request PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function buf Buffer to store headers and copy of content buflen Size of buffer code HTTP Status code e g 200 for OK content type Content type string or NULL for default of text html more hdrs 0 no more headers 1 caller will add headers 2 caller will add headers but call custom head
309. lash character If this function is not called the root directory name is set to by http init dfltname Default file name to use This is appended to the directory part of the URL if the URL actually refers to a directory If this function is not called the de fault file name is set to index html by http init If this parameter is NULL there will be no default name A request for a directory will generally return a 404 error not found to the client If it is not NULL this parameter must be a null terminated string It must not start or end with a character RETURN VALUE 0 OK E2BIG rootdir was too long It should be limited to less than about 12 characters but you can increase the value of SSPEC_MAXNAME if necessary EINVAL rootdir was NULL or did not start and end with a forward slash character LIBRARY HTTP LIB SEE ALSO http_handler http_init 228 rabbit com HTTP Server http setState int http setState HttpState state int val DESCRIPTION Set the current primary HTTP CGI state variable Use of this state variable is entirely up to the application however it is initialized by the HTTP server to zero before calling the CGI for the first time NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function val New value for the primary state variable RETURN VALUE Returns the new value that is val LIBRA
310. last _ type snmp type snmp last type snmp parms p DESCRIPTION Returns the internal type of the last object retrieved from the MIB tree Each object has two types The SNMP type see snmp last snmp tvpe indicates the type of object to ex ternal entities using SNMP to examine objects on this agent The internal type indicates the mem ory layout for the object in the MIB tree The same memory layout may be used for different SNMP types and vice versa PARAMETERS p Parameter structure that was used previously in a call to a retrieval function such as snmp get indexed snmp get or snmp get next RETURN VALUE Internal tvpe of the object The currentiv supported tvpes are e SNMP SHORT 16 bit integer e SNMP LONG 32 bit integer e SNMP STR null terminated string SNMP OCT variable length binary octet string e SNMP_FOCT fixed length binary string e SNMP_OID Object ID LIBRARY MIB LIB SEE ALSO snmp init parms snmp get snmp get next snmp get indexed snmp last int snmp last long snmp last mem snmp last xmem snmp last snmp tvpe snmp last len 420 rabbit com SNMP snmp last xmem long snmp last xmem snmp parms p DESCRIPTION Return the physical address of the last object retrieved from the MIB tree The object may have been defined to reside in either xmem or root data space and may be of any type PARAMETERS p Parameter structure that was used previously in a call t
311. le The difference between and the importance of the latest submitted value and the latest committed value of a variable will make more sense when you have read Section 5 2 2 Also variables in web guards must be simple variables for example int long float char or string char array They cannot be structures or arrays The admin group is given full access to the variable access is read and write by default while all other users are limited to read only access If no group parameter is given then anyone can read or write hum_alarm The order of group names is important If admin came before all ro then the admin group would not have write access 252 rabbit com RabbitWeb int alarm ilmeervell 5 char alarm email 501 web alarm interval X O lt Salarm interval amp amp Salarm_ interval lt 30000 X groups all ro admin web alarm email groups all ro admin These lines declare and register an integer variable and a string The variable alarm interval gives the minimum amount of time in minutes between two alarms thus preventing alarm flooding The variable alarm email gives the email address to which alarms should be sent This concludes the compile time initialization part of the code void main void int userid mu 4 S0p hum alarm 75 alarm interval 60 strcpy alarm email somebody nowhere org secle dmit initialize TCP IP stack he
312. lication protocols file EXLENSIONS sess cssesiceesscveoceesscansvvechintecsencpdecer 32 148 FEP GHG tite si A a 313 file andlers 5 s5cccciseesesedscacesaseseeds eb eee 324 PUPP l E E E EE EEEE 321 ME SIZE EER 317 HET P Ghent i e oes 295 Pile tan SEER ss eko i AEN 314 FA PEP S61 VOR A 137 firewall e oee erer E AEE E 342 POP3 chent i a 365 FLOW onttol serei ak eeheeeeeeta eee 483 SMTP client o seenennnnznezznnanenenznnzznnanzan 353 FTP client oo cee eenennnzznnennnznnnnznanznnnnzna 313 320 6 TE E a a eee 449 FTP SERVER omero eiea EY 321 344 TFTP client seeren eseon orere eE iE 345 FTP server commands ccsssceeessreeeeees 342 343 authentication Function Reference EEP AT 145 Authentication and Identification NM oes soe taee ute secces sage cegestct te eecteesaeess 354 sauth adduser ss eeeennnenzzzznnenzzznnaz 46 B sauth authenticate ss sseeeennenezzznnnzni 47 sauth getpassword se eeeenennzneneni 48 basic authentication sse enennnnnennn 145 sauth_getserver Ce yore Goede see 48 BOOTP DHCP Sauth_getuserid sse eseenenennzzznzni 49 used with TFTP is iii iet ez 345 sauth_getusermask esseesemsmnnnnznnnnn 50 sauth getusername L eee 31 C sauth_getwriteaccess sssesseeeeeesneneni 52 sauth remMOVEUSET ceececeeteceesteeeeeseees 53 callbacks sauth setpassword s sessensenenzzznnnzenzznnza 54 FTP data transfers ss ss seseenene
313. lity Library sspec needsauthentication int sspec needsauthentication int sspec DESCRIPTION Checks if the item represented by the spec entry needs authentication for access This is defined by having a non NULL realm string for the resource This function is deprecated starting with Dynamic C 8 50 in favor of sspec checkpermissions Itis retained for cases where the permissions structure for a resource contains an authentication method of SERVER AUTH DEFAULT PARAMETERS sspec spec index RETURN VALUE 0 Does NOT need authentication 1 Does need authentication 1 Failure no permissions struct assigned or invalid sspec handle SEE ALSO sspec getrealm sspec checkpermissions TCP IP Manual Vol 2 rabbit com 105 sspec open int sspec open char name ServerContext context word mode DESCRIPTION Open a file resource by name The name may refer to a flash or RAM spec entry or may be the name of a file in a filesystem The resource namespace is specified as a directory hierarchy similar to a Unix like filesystem The root directory is the base for all named resources If s2 1ib is included then files stored in the FS2 filesystem are accessible under a mount point called s2 FS2 files do not have native names Instead each file is numbered from 1 to 255 Zserver assigns names to FS2 files by appending the file number in decimal to the string file For exampl
314. long fixed messages that are stored in extended memory e g via ximport ed file See smtp sendmail for more details PARAMETERS to String containing the e mail address of the destination from String containing the e mail address of the source subject String containing the subject of the message message Physical address in xmem containing the message The message must NOT contain the byte sequence r n r n CRLE CRLP as this is used to mark the end of the e mail and will be appended to the e mail automatically messagelen Length of the message in xmem RETURN VALUE None LIBRARY SMTP LIB SEE ALSO smtp mailtick smtp status smtp sendmail TCP IP Manual Vol 2 rabbit com 361 smtp setauth int smtp setauth char username char password DESCRIPTION Sets the username and password to use for SMTP AUTH Authentication You must define USE SMTP AUTH in your program if you want to use SMTP AUTH on your outbound connec tions To disable SMTP authentication set both username and password to 77 empty strings PARAMETERS username This is copied into the SMTP state structure Note that some SMTP servers require a full email address while others just want a username password This is copied into the SMTP state structure RETURN VALUE SMTP_OK server name was set successfully SMTP_USERNAMETOOLONG the username was too long SMTP_PASSWORDTOOLONG the username was too long SEE ALSO smtp sendmail sm
315. lowest blocks in the diagram are divided into two groups with a dashed outline The upper group is labelled filesystems and the lower storage Both of these groups are indefinitely extensible meaning that new classes of storage and their organization filesystems may be added in future releases of Dynamic C or by you The arrows between these groups are indicative of the most common patterns of communication others may be defined 10 rabbit com Web Enabling Your Application 2 4 Architecture of a Toy Application Using the diagram of the previous section as a basis we now focus on writing a simple web enabled appli cation The following diagram is the same as the one above except that the relevant parts have been visu ally emphasized This diagram is essentially the toy application that was described at the start of this chapter It shows the mandatory components for all web enabled applications Later we introduce the other elements of the diagram to show how a fully featured application is built up Figure 2 2 Minimum components for a web enabled application Application Compile Time Run Time Main Application CGI Initialization Initialization Loop Specifics I O Functions web Variables See Requests Context i Zserver TCP IP IE Resource Manager ee Virtual File System CA Metadata Resources ee File Systems Static Dynamic 51 Resource Resource FAT 4 Table Table H NEM Storage Pro
316. lt and custom error messages e Help text for Zconsole commands including custom commands e Multiple I O streams that can be used simultaneously e A fail safe backup system for configuration data 14 1 1 File System Requirement Prior to Dynamic C 7 30 an application program using Zconsole must include the lines use filesvstem lib If using the improved file system available with DC 7 05 substitute fs2 lib for filesvstem lib use zconsole lib Starting with Dynamic C 7 30 using the file system is no longer necessary TCP IP Manual Vol 2 rabbit com 459 14 1 2 TCP IP and Zconsole Dynamic C TCP IP functionality may be used by a Zconsole application program by including the state ment use dertcp lib in the program Other TCP IP protocols may be added with use statements of the appropriate libraries 14 2 Login Name and Password There is a sample program Samples tcpip LOGINCONSOLE C that demonstrates the use of the login name password functionality for Zconsole Zconsole command functions con loginname con_loginpassword and con_logout are described in Section 14 4 1 1 starting on page 463 The structure that saves the name and password information can be backed up using the backup macro CONSOLE BACKUP LOGIN Please see Section 14 7 starting on page 484 for details on the backup system 14 3 Zconsole Commands and Messages Zconsole is a command driven application A command is issued
317. lude HTTP transfer coding tokens such as amp 64 decimal for at sign where appropriate Encodes these characters lt gt amp Source string is NULL byte terminated Destination buffer is bounded by len This function is reentrant PARAMETERS dest Buffer where encoded string is stored sre Buffer holding original string not changed len Size of destination buffer RETURN VALUE dest There was room for all conversions NULL Not enough room LIBRARY HTTP LIB SEE ALSO http_urldecode TCP IP Manual Vol 2 rabbit com 191 http date str char http date str char buf DESCRIPTION Print the date time zone adjusted into the given buffer This assumes there is room PARAMETERS buf The buffer to write the date into This requires at least 30 bytes in the desti nation buffer RETURN VALUE A pointer to the string LIBRARY HTTP LIB SEE ALSO http_handler 192 rabbit com HTTP Server http defaultCGI int http defaultCGI HttpState state DESCRIPTION This function should not be called directly by the application It is intended to be used as a new style CGI for handling file uploads See samples tcpip http upld_fat c for an example of using this function This CGI function accepts POST requests from the client browser which may contain one or more files that are being uploaded It looks at the field name of the form data in the request If the field name starts with
318. lure SEE ALSO sspec getfvdesc sspec setfventrytype int sspec setfventrytype int form int var int entrytype DESCRIPTION Sets the type of form entry element that should be used for the given variable PARAMETERS form spec index of the form var Index into the FormVar array of the variable entrytype HTML FORM TEXT for a text box HTML FORM PULLDOWN for a pull down menu The default is HTML FORM TEXT RETURN VALUE 0 Success 1 Failure SEE ALSO sspec getfventrvtvpe 122 rabbit com Server Utilitv Librarv sspec setfvfloatrange int sspec setfvfloatrange int form int var float low float high DESCRIPTION Sets the range of a float variable PARAMETERS form spec index of the form var Index into the FormVar array of the variable low Minimum value of the variable high Maximum value of the variable RETURN VALUE 0 Success 1 Failure SEE ALSO sspec setfvrange sspec setfvoptlist TCP IP Manual Vol 2 rabbit com 123 sspec setfvlen int int form int var int len DESCRIPTION Sets the length of a form variable the maximum length of the string representation of the vari able Note that for string variables 1en should include the NULL terminator PARAMETERS form spec index of the form var Index into the FormVar array of the variable len Length of the variable RETURN VALUE 0 Success 1 Failure SEE ALSO sspec getfvlen sspec setfvname int
319. ly The currently logged in user The current working directory 20 File descriptor for last file listed 1 Error 330 rabbit com FTP Server ftp dflt cd int ftp dflt cd int cwd char dir int uid DESCRIPTION Change to new directory This is called when the client issues a CWD command The FTP serv er itself has no concept of what a directory is this is meaningful only to the handler PARAMETERS cwd Integer representing the current directory dir String that indicates the new directory that will become the current directory The interpretation of this string is entirely up to the handler The dir string will be passed as to move up one level uid The currently logged in user RETURN VALUE 0 No such directory exists 1 Root directory 50 Anything that is meaningful to the handler TCP IP Manual Vol 2 rabbit com 331 ftp dflt pwd int ftp dflt pwd int cwd char buf DESCRIPTION Print the current directory passed as cwd as a string The result is placed in buf whose length may be assumed to be at least FTP_MAXLINE 6 The return value is ignored PARAMETERS cwd The current directory buf Pointer to buffer to put the string RETURN VALUE The return value is ignored 332 rabbit com FTP Server ftp dflt mdtm unsigned long ftp dflt mdtm int fd DESCRIPTION This handler function is called when the server receives the FTP command MDTM The return val
320. m MTA 417 14 4 1 Zconsole Commands 462 snmp_last_objectID eee 418 14 4 2 Zconsole Error Messages 469 ey ee pegierecseereagereiss jin 14 5 Zconsole I O Interface 472 simp last nem 42 14 5 1 How to Include an I O Method 472 snmp monitor EEEE 422 14 5 2 Predefined I O Methods 472 SAMP_print_tree eee 425 14 5 3 Multiple I O Streams 473 Aa aN A 14 6 Zconsole Execution seen 474 dl a a a 14 6 1 File System Initialization 474 snmp_set_dflt_communities E 429 14 6 2 Serial Buffers 474 SIMI l l i 430 14 6 3 Using TCP IP 474 snmp set INt en 431 14 6 4 Required Zconsole Functions 475 snmp set long fri ia Se 432 console init s se ennenenzenenzznza 475 snmp_set_ObjectID 10 433 console tick 475 snmp_set_oct EEE RETRE ERRERA 434 14 6 5 Useful Zconsole Function 476 snmp set oid prreerenzzzznnnnznnznzznzzzi 435 con_backup 476 sl eee a 15 e A ae pora e 438 con backup reserve 00 477 oo ee 439 con_ehk_timeout sesecssrsevveresernsen 477 snmp_start E EET 440 con_load_backup a eb cae ak ee SUMP STOP reiii sinnis 440 Pen Dok i Mb d 479 mA to ji bon et files IX 479 an T a E ness 442 con set user idle 0 0 0 cee cece 480 ces a tah anitor ie a 443 con set timeOut eneee 480 afi ae oe A 444 con set user timeOut ssemma 481 SnD i Patent A 445 console disable nn 481 Sin acne BAe ses A os ae vianate 446 console enable eee 482 snmp add n 447 14 6 6 Zconsole Exe
321. mail message must be ASCII encoded and formatted with RFC822 headers Sending e mail via TFTP is deprecated Use SMTP instead since TFTP servers may not implement mail PARAMETERS ts Pointer to tftp state RETURN VALUE 0 OK 4 Error default socket in use LIBRARY TFTP LIB TCP IP Manual Vol 2 rabbit com 347 tftp initx int tftp initx long ts addr DESCRIPTION This function is called to complete initialization of the TFTP state structure where the structure is possibly stored somewhere other than in the root data space This is a wrapper function for tftp init See that function description for details PARAMETERS ts addr Physical address of TFTP state struct tftp state RETURN VALUE 0 OK 1 Error default socket in use LIBRARY TFTP LIB 348 rabbit com TFTP Client tftp tick int tftp tick struct tftp state ts DESCRIPTION This function is called periodically in order to take the next step in a TFTP process Appropriate use of this function allows single or multiple transfers to occur without blocking For multiple concurrent transfers there must be a unique tftp state structure and a unique UDP socket for each transfer in progress This function calls sock tick PARAMETERS ts Pointer to TFTP state This must have been set up using tftp init and must be passed to each call of tftp tick without alteration RETURN VALUE 1 OK transfer not yet complete 0 OK transf
322. might expect near the mid dle of these Note that we are not considering the size of the application other than the web interface part For example you may have a sophisticated G code interpreter and motion control system where the web interface is limited to simply enabling disabling the actuators and showing an error log to maintenance personnel For the purposes of our discussion this would be a small application The next section describes a smaller than small application that is a toy which we use to show the bare essentials of a web enabled application 2 2 The Smallest Web Server in the WWW Before moving on to real applications the following sample code shows how to create the simplest possi ble web server It does nothing but show Hello WWW on the browser There are two files needed for this The first is the Dynamic C code to be loaded to the target board which must support TCP IP The second is the web page content itself written in a syntax known as HTML HyperText Markup Language The second file is effectively included in the program using the ximport directive toy http c define TCPCONFIG 1 use dertcp lib use http lib ximport hellowww html hellowww_html SSPEC MIMETABLE START SSPEC MIME htmi text htmi SSPEC MIMETABLE END SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE hellowww html hellowww html SSPEC RESOURCETABLE END void main sock init http ini
323. minating CRLF null The minimum reasonable value is about 15 for format 0 and 80 for format 1 context Server context This structure will have the following fields initialized userid current user who is doing the listing or 1 if no specific user server mask bit of the server who is performing the listing cwd set to the directory to list The sspec_cd function can be used to set this field correctly This struct must be the same instance for all calls in a single directory listing sequence 80 rabbit com Server Utility Library sspec dirlist cont options Listing options This is a bit field that should have a combination of the fol lowing flags SSPEC LIST LONG Long format listing else just names SSPEC LIST END Close the current directory listing For the long format the template is lt permissions gt 1 lt user gt lt group gt lt length gt lt date gt lt name gt Where permissions is a string of 10 characters in 3 sets of 3 plus one Each set of 3 indicates read write or execute permissions for the user group and world respectively The 1st char is q if the entry is a directory or otherwise Since Zserver does not really support file owners or groups or execute permissions the 3 sets will be either rw or r or sometimes w The user bits are set according to the current user s access The group bits are set if any other user has access and the
324. more information on this enhanced HTTP server 44 rabbit com Server Utility Library 3 5 API Functions The resource manager API functions are described in this section These functions give servers a consis tent interface to files variables and client information sauth_adduser sauth_authenticate sauth_getpassword sauth_getserver sauth_getuserid sauth_getusermask sauth_getusername sauth_getwriteaccess sauth_removeuser sauth_setpassword sauth_setserver sauth_setusermask sauth setwriteaccess sspec access sspec addCcGI sspec addform sspec addfsfile sspec addfunction sspec addfv sspec addrootfile sspec addrule sspec adduser sspec addvariable sspec addxmemfile sspec addxmemvar sspec aliasspec sspec automount sspec cd sspec checkaccess sspec checkpermissions sspec close sspec delete sspec dirlist sspec fatregister sspec fatregistered sspec findfv sspec findname sspec findfsname sspec findnextfile sspec getfileloc sspec getfiletvpe sspec getformtitle sspec getfunction sspec getfvdesc sspec getfventrvtvpe sspec getfvlen sspec getfvname sspec getfvnum sspec getfvopt sspec getfvoptlistlen sspec getfvreadonlv sspec getfvspec sspec getlength sspec getMIMEtvpe sspec getname sspec getpermissions sspec getpreformfuncti on sspec getrealm sspec getservermask sspec gettvpe sspec getuserid sspec getusername sspec getvaraddr sspec getvarkind sspec getvartvpe sspec getxvaraddr sspec mkdir sspec
325. mp deg F lt TD gt lt TR gt lt TABLE gt lt P gt lt INPUT TVPE submit VALUE Submit gt lt INPUT TYPE reset Value Reset lt FORM gt lt BODY gt lt HTML gt 154 rabbit com HTTP Server The form might display as shown here ACME Thermostat Settings Netscape of x File Edit View Go Communicator Help Back Forward Reload Home Search Netscape Print sy x Bookmarks Location ffile C1 mpform html AT What s Related When the form is displaved bv a G browser the user can change values in 4 the form But how does this changed data get back to the HTTP server By AC ME Th ermostat S ettin gs using the HTTP POST command When the user presses the Submit button the browser connects to the HTTP server and makes the following request Name Value Description High Temp Jao Maximum in temperature range F 7 Low Temp ss Minimum in temperature range F POST myform HTTP 1 0 some header infor Submit Reset mation Content Length 19 where mvform is the CGI program that was specified in the ACTION attribute of the FORM tag and POST is Resin Die IEEE I 4 the METHOD attribute of the FORM tag Content Length defines how many bytes of information are being sent to the server not including the request line and the headers Then the browser sends a blank line followed by the form information in the following manner temphi 80 amp tem
326. must be a blank line after the line Subject test mail 10 2 SMTP Authentication In most situations Internet access is provided by an Internet Service Provider ISP Usually the ISP runs an email server that will accept emails without authentication from customers that are within their net work Users outside of their network are not allowed to send email through their servers because the mail server would quickly become a gateway for spam With more people on the go with laptops SMTP authentication allows them to send email through a trusted server without being directly on the network An informative tutorial on SMTP authentication is available at www fehcom de qmail smtpauth html Default behavior prior to Dynamic C 9 21 was for the login to fail if authentication failed With Dynamic C 9 21 the SMTP library will fall back on unauthenticated login if authentication fails To restore the old behavior when using Dynamic C 9 21 define the macro SMTP AUTH FAIL IF NO AUTH Three methods of authentication are recognized by the implementation of an SMTP client AUTH PLAIN The client sends AUTH PLAIN lt token gt where lt token gt is the Base64 encoded string user name Ousername Opassword that will look something like AUTH PLAIN dGVzdABOZXNOAHR1c3RWYXNz The server responds with a message indicating whether authentication was successful AUTH LOGIN Client sends AUTH LOGIN command server responds with 334 VXNIcm5hbW
327. must be rebuilt through other means RETURN VALUE 0 Successfullv restored the server spec and server auth tables 1 Failure SEE ALSO sspec save sspec setsavedata 116 rabbit com Server Utilitv Librarv sspec rmdir int sspec rmdir char name ServerContext context DESCRIPTION Delete a named directory in the FAT filesystem PARAMETERS name Name of directory to delete context Current server context RETURN VALUE 0 OK EPERM Nota filesystem that supports deletion of directories EACCES Not authorized Any other negative values indicate an error SEE ALSO sspec delete sspec mkdir sspec_open sspec save int sspec_save void DESCRIPTION Saves the servers object list and server authorization list along with some user specified data if set up with sspec setsavedata to the file system This does not save the actual files and variables but only the structures that reference them If the files are stored in flash then the references will still be valid Files in volatile RAM and variables must be rebuilt through other means RETURN VALUE 0 Successfully save the server_spec and server_auth tables 1 Failure SEE ALSO sspec restore sspec setsavedata TCP IP Manual Vol 2 rabbit com 117 sspec seek int sspec seek int sspec long offset int whence DESCRIPTION Seek to specified offset in the file resource The next sspec_read or sspec write call will star
328. myCGI cgi fptr Pointer to the function The prototype for this function is int fptr HttpState state There is a specific documented interface that must be used when specifying this type of CGI handler function See the manual for details servermask Bitmask representing valid servers currently only useful with SERVER_HTTP RETURN VALUE 20 Successfully added spec index 1 Failed to add function SEE ALSO sspec addfsfile sspec addfunction sspec addrootfile sspec addvariable sspec addxmemvar sspec addxmemfile sspec aliasspec sspec addform TCP IP Manual Vol 2 rabbit com 59 sspec addform int sspec addform char name FormVar form int formsize word servermask DESCRIPTION Adds a form set of modifiable variables to the TCP IP servers object list Make sure that SSPEC MAXSPEC is large enough to hold this new entry This function is currently only useful for the HTTP server PARAMETERS name Name of the new form form Pointer to the form array This is a user defined array to hold information about form variables formsize Size of the form array servermask Bitmask representing valid servers currently only useful with SERVER_HTTP RETURN VALUE 20 Success location of form in server spec list 1 Failed to add form SEE ALSO sspec addfsfile sspec addfunction sspec addrootfile sspec addvariable sspec addxmemvar sspec addxmemfile sspec aliasspec sspec addfv 60 rabbit com Server
329. n Finally we have to consider what to do at the end of all parts CGI_ EOF or if the connection was can celled CGI_ ABORT You may recall that the CGI has two responsibilities one is to process the incoming data and the other is to write some results back to the client We have already done the former it is only left to do the latter Writing results to the client means we have to generate the proper HTTP response including all the neces sary headers and web page content The CGI can do this itself by putting strings in the buffer provided by the http getData call Alternatively the CGI can simply redirect back to another local or even remote web page and not bother writing anything itself If the CGI wants to generate the response itself then this has the advantage of being slightly more effi cient but the disadvantage of requiring more code in the CGI Usually the application already has some sort of web page that can display the necessary results This is often an SSI page that is dynamically generated using a specialized function or may be just a static page for example index htm1 Action Code CGI EOF Since referring to another web page is easiest it is shown first case CGI EOF cgi redirectto s index htmi break The cgi redirectto function tells the HTTP server to stop calling this CGI function and tell the client to retrieve its next web page from the specified location in this case the i
330. n char delim DESCRIPTION Read the next byte s from the given resource until specified delimiter is read and transferred to buffer If EOF is encountered before reading a delimiter char then the buffer may not be terminat ed with the delimiter char Similarly if the delimiter was not found before the given buffer was full The buffer is not null terminated PARAMETERS sspec Open file handle This must be a handle returned by sspec_open buf Buffer into which data is copied len Length of the above buffer delim Delimiter character RETURN VALUE 0 No data is currently available 1 len The specified number of characters has been copied to the supplied buffer and the cur rent file position has been advanced by that many bytes Less than len bytes may be read in which case the server should test for EOF slen No data was copied because the underlying filesystem is unable to return a partial record and maintain its current position The return value is the minimum sized buffer which should be passed on the next call Note this sort of return is not currently implemented by any of the file systems however servers should be coded to handle this case for future anticipated systems which have record level access rather than byte level The following return values are negatives of the values defined in errno lib EINVAL len parameter was lt 0 EBADF The specified handle was not open or invalid Any other negative values in
331. nated string This name is assumed to be rel ative to context gt cwd if it does not begin with a character Other wise the name is assumed to be relative to context gt rootdir context Additional context information The ServerContext structure is set up by the caller See sspec_open for documentation on this structure For this function context gt userid should be set to the current user whose access is being tested or may be set to 1 to test access by the server in general RETURN VALUE 20 Success The return value is a bitmask of the following values e O READ user server has read access e O WRITE user server has write access e 0 zero no access The following return values are negatives of the values defined in errno lib ENOENT The resource was not found e EINVAL The resource name was malformed e g too long or context was NULL or the resource was not a file type SEE ALSO sspec read sspec write sspec seek sspec tell sspec close sspec checkpermissions 58 rabbit com Server Utilitv Librarv sspec addcCGI int sspec addCGI char name void fptr word servermask DESCRIPTION Add a CGI function to the RAM resource list This function is currently only useful for the HTTP server in which case the function is registered as a CGI processor Make sure that SSPEC MAXSPEC is large enough to hold this new entry PARAMETERS name URL name of the new function for example
332. nce all matching is done using absolute path names If this prefix string exactly matches an existing entry in the table that entry is replaced Otherwise a new entry is created if possible This string is not copied only the pointer is stored Thus p x must point to static storage that is a string constant or a global variable Initial characters other than are reserved for future use realm If not NULL is an arbitrary null terminated string that may be used by the server For HTTP this is used as the realm of the resource This string is not copied only the pointer is stored Thus the parameter must point to static storage readgroups A word with a bit set for each group that can access this resource for reading A maximum of 16 different user groups can exist writegroups A word witha bit set for each group that can access this resource for writing The user must also be given write permission to resources in the userid table entry for the appropriate server s servermask The server s that are allowed to access this resource Servers have pre defined bits This parameter should be a combination of SERVER_HTTP web server SERVER_ FTP file transfer protocol server SERVER_ SMTP email SERVER_HTTPS secure web server SERVER_SNMP SNMP agent SERVER_USER user defined server SERVER_ANY for all servers method Allowable authentication method s to be used when accessing this resource If zero then the reso
333. nction must be used to make the variable name safe for transmission NAME lt z varname Sfoo 3 gt That is varname automatically encodes the variable name correctly 5 3 2 Flow Control In addition to simply displaying variables in your HTML documents the new ZHTML tag allows some simple looping and decision making 5 3 2 1 Looping A for loop when combined with arrays makes it easy to display lists of variables The format of the for loop is as follows lt z for A start A lt end A step gt lt H1 gt HTML code here lt H1 gt lt z gt where e A A single letter variable name from A Z These loop control variables take on an unsigned int value e start The initial value of the for loop The value of the variable will start at this value and count to the end value e end The upper value of the for loop The operator may be any one of the following lt gt lt SS LS step The number by which the variable will change for each iteration through the loop The operator may be any one of the following step step Note that A will increment the vari able by 1 268 rabbit com RabbitWeb Note that although this for loop looks like the regular Dynamic C for loop its use is restricted to what is documented here To display a list of numbers in HTML using a for loop you can do something like this lt TABLE gt lt TR gt lt z for SA 0 SA lt 5
334. nction that will be called when the user supplied data has been restored RETURN VALUE 0 Successfully set up the user supplied data 1 Failure SEE ALSO Sspec Save sspec restore TCP IP Manual Vol 2 rabbit com 131 sspec setuser int sspec setuser int sspec int userid DESCRIPTION Set the read permission mask of a spec entry usually a file The permissions for this resource are set to readable only by the group s which this user is a member of Write access is set to none This function is deprecated in Dynamic C 8 50 Use sspec_setpermissions instead PARAMETERS sspec spec index this must refer to a RAM resource userid user index RETURN VALUE 0 Success 1 Failure SEE ALSO sauth adduser sspec getusername sspec setpermissions 132 rabbit com Server Utilitv Librarv sspec stat int sspec stat char name ServerContext context SSpecStat sg DESCRIPTION Get information about a resource by name The name may refer to a flash or ram spec entry or may be the name of a file in a filesystem See sspec_open fora more detailed description of the name and context parameters PARAMETERS name Resource name as a null terminated string This name is assumed to be rel ative to context gt cwd if it does not begin with a character Other wise the name is assumed to be relative to context gt rootdir context Additional context information The ServerContext stru
335. nd is issued with no parame ters It is not defined by default so has no default value TCP IP Manual Vol 2 rabbit com 487 14 9 Sample Program The sample program Samples zconsole tcpipconsole c demonstrates many of the features of zconsole 1lib Among the features this application supports is network configuration uploading web pages changing variables for use with web pages sending mail and access to the console through a telnet client Please note that all libraries needed by zconsole 1ib must be included with use statements before the use statement for the Zconsole library The following code is taken from tcpipconsole c Size of the buffers for serial port C If you want to use another serial port you should change the buffer macros below appropriately and change the console_io array below el define CINBUFSIZE 1023 define COUTBUFSIZE 255 yf Maximum number of connections to the web server This indicates the number of sockets that the web server will use ey define HTTP_MAXSERVERS 2 Maximum number of sockets this program can use The web server is taking two sockets the mail client uses one socket and the telnet interface uses the other socket z define MAX_SOCKETS 4 All web server content is dynamic so we do not need http_flashspec a define HTTP NO FLASHSPEC ff The file system that the console uses should be located in flash a define FS FLASH Th
336. ndex htm1 page on the current server The onus is on the client browser to go and get that page It will come straight back to this server but the CGI does not have to worry about it Easy TCP IP Manual Vol 2 rabbit com 173 In a similar vein you can use the http switchCGi function Again the current CGI does not have to generate a response The difference is that the HTTP server goes straight to the specified web page and presents it to the client on the same connection rather than requiring the client to come back to the server with a new request http switchCGI can transfer control to any local web page as if the client had directly requested that resource If the resource happens to be another new style CGI like the one we are describing then it gets control with the current action code which will usually be CCI EOF Otherwise the resource is pro cessed as if it was directly retrieved by the client by name Note the current CGI must not have written anything back to the client otherwise the data wil not be intelligible to the client Here is an example case CGI EOF http switchCGI s index html break As you can see it is very similar to the cgi_ redirectto case Action Code CGI ABORT The conventions for having the CGI generate its own response back to the client are covered in the next section titled Writing Responses to the Client from a CGI Function First we look at the proper handling o
337. ndex shtml il ji eloloiiei gL il LEGE GIE IA EZ ZAZA IR TR SSPEC RESOURCE ROOTVAR SSPEC RESOURCE ROOTVAR SSPEC RESOURCE ROOTVAR SSPEC RESOURCE ROOTVAR B SSPEC RESOURCE FUNCTION leditog cgi SSPEC RESOURCE FUNCTION led2tog cgi SSPEC RESOURCE FUNCTION led3tog cgi SSPEC RESOURCE FUNCTION ledatog cgi SSPEC RESOURCETABLE END ledi ledi PTRIG led2 led2 PTRIG Wiles leds PERIG led4 led4 PTRIG n m alinclese Ime index html showsre shtml showsrc_shtml ESOL IL_GCjalie z ledon gif ledon gif ledoff gif i ISWEEOM Cie DETON Gali I ega EU SE MO O 00 ol nn n Nn leditoggle led2toggle led3toggle led4toggle ii 150 rabbit com HTTP Server void main strcpy led1 ledon gif strcpy led2 ledon gif strcpy led3 ledoff gif strcpy led4 ledon gif B secle ilme 5 aeto dnit tep reseryeport 80 while 1 http handler When you compile and run ssi c you see the LNK light on the board come on Point your browser at the controller e g http 10 10 6 100 The ACT light will flash a couple of times and your browser will display the page This program displays pictures of LEDs Their state is toggled by pressing the image of a button This pro gram uses Server Side Includes SST and the old style of CGI SSPEC RESOURCE FUNCTION Use of SSI is explained
338. needsauthenticat ion sspec open sspec pwd sspec read sspec readfile sspec readvariable sspec remove sspec removerule sspec removeuser sspec resizerootfile sspec restore sspec rmdir sspec save sspec seek sspec setformepilog sspec setformfunction sspec setformprolog sspec setformtitle sspec setfvcheck sspec setfvdesc sspec setfventrvtvpe sspec setfvfloatrange sspec setfvlen sspec setfvname sspec setfvoptlist sspec setfvrange sspec setfvreadonlv sspec setpermissions sspec setpreformfuncti on sspec setrealm sspec setsavedata sspec setuser sspec stat sspec tell sspec write TCP IP Manual Vol 2 rabbit com 45 sauth adduser int sauth adduser char username char password word servermask DESCRIPTION This function adds a user to the user table It fills in the fields of the ServerAuth structure as sociated with this user Three of the fields are specified by the parameters passed into the function Two other fields one for the user group mask and the other for the write access mask are given default values The default for the user group mask is the assigned index number 0 to SAUTH MAXNAME 1 as a bit number that is 1 lt lt index This effectively creates each user in a unique single group Since this does not offer any real control over the assigned group mask it is recommended to use sauth setusermask after this to assign the correct access masks The default for the write
339. nfiguration MACTOS u 356 HTTP serve occcccccccccccccccccccceccececcecesceccecuscesens 137 247 poe Ure pre ees ne te Pe reer ere 142 151 HTTP NO FLASHSPEC nooiens 39 S9 A aera 145 HttpState s semm mnenenenenznnnnenzenennnneenzenenz nn ena 138 SSPEC MAX FATDRIVES essenzi 40 SSPEC MAX OPEN seeseeeenzznzzznenzenzznnnazenzantnz 41 496 rabbit com Index SSPEC_MAXNAME om cess ceeeeeeeeeeeeeene 40 SSPEC MAXRULES Lee eeenenzznnnenzznzznnnnznzzni 40 SSPEC MAXSPEC arenend ienr 41 SSPEC NO STATIC Le eeennnnzznnnnnzznnnenenanzztnn 39 SSPEC USERSPERRESOURCE e eennnnn 41 SSPEC XMEMVARLEN seeeesseeennenzznnnenzznntzn 41 stack free space for TFTP functions nn 346 Static resource table sssseserenennzennnenzannnnnazazzntzn 42 static WED pages isi sc cssesssssccsscersseseavessesabnansseatesonpsee gt 146 T tenet ee ee 449 458 TELNET COOKED L ernenenznnenenznonennnnz 455 TETP Client siek i a die elite Sevens 345 351 LL 8 10 6 E 146 TIMEZONE i knee iii 143 SA A G 145 U URL encoded data ss ssseeeenzznnnnnnenzzennennna 156 user table sssseeenennnnnnnenzenznnnnnnazzznnnnnnazznnnnnnnana 16 USETS Mistika A 35 V VSERIAL DEBUG sse seeeenenzznnnennenznnntnnnnza 450 VSERIAL NUM GATEWAXS cccccceeeeees 450 WwW web browser control sse sssesennezzznntnenzznntznzn 3 29 well known ports FTP servet cccccccccesssseccceeesesseeeecesesseeeceecenseaees 321 HTTP SOF
340. ngth of the file specified by the sspec index Note that compressed files z import return 1 because their expanded length is not known until they are processed PARAMETERS sspec spec index of file in resource list RETURN VALUE 1 Failure compressed file or other type whose effective length is not known 20 Success length of the file in bytes SEE ALSO sspec readfile sspec getfileloc TCP IP Manual Vol 2 rabbit com 95 sspec getMIMEtype MIMETypeMap sspec getMIMEtvpe char name ServerContext context DESCRIPTION Return the MIME type information for a specified resource name in the given server context Note that the available MIME types are set up by defining a global variable or constant table using the definition for example const MIMETypeMap http tvpesll html text html NULL gif image gif NULL jk The name http tvpes is required for backward compatibilitv even though servers other than HTTP can make use of MIME tvpes When searching for the appropriate type the rule table is consulted first Only if this results in a NULL MIME type pointer is the http tvpes table consulted See sspec open fora detailed description of the parameters PARAMETER name Name of the resource context Current server context RETURN VALUE Pointer to the appropriate table entry MIMETypeMap is defined as tvpedef struct char extension 10 File extension or suffix cha
341. nlV venera 127 shtml addvariable ss emenennnennn 246 sspec_setpreformfunction 129 shtml delfunction sse meenennenenzzn 247 HTTP Server shtml_delvariable ss sse mmnnennenennzn 247 http findname e nnennennn 196 Sspe AGCUSER is kaa sk e Sea 67 http getcontext wo eee eeeeeeeeseeeees 204 sspec_Checkaccess wn 75 http handler s screcresniniorirnnisisrss 218 sspec_getuserid esi 101 http idle sceso 218 sspec getusermame l eennenennnn 102 http Mit de arabe eda de erett site 219 sspec needsauthentication 105 http 18 SECUTe en 219 sspec readfile mm eneneennn 112 EGP safe rererere eE E 222 SSpec TEMOVE lenza 113 http set anONVMOUS Lemna 224 Sspec reMOVEUSET LL eeennnennnen 115 http set path skrins nisemizen 228 SSPCC_TESTOLE Lis si sse iein 116 http setauthentication mn 225 SSPCCUSAVE cc csedeidsnsseresstensvcecestesbonecdecssee 117 http shutdown mol eeneenennen 230 sspec_Setsavedata sse eeren 131 http STATUS cocsciscsrsessssesscaresvercieerescncssetessee 241 SSPCC_SCCUSED j ecescciessensssesessee svespeetersveness 132 MIME Types SNMP sspec_getMIMEtype 0 0 ee eeeeeeeeeee 96 SDMP add is sis See 393 Resource Access Control snmp add communitv we e en 396 SSPECLACCESS perstat nsei EE Fe 58 snmp_append_binary_oid Low 397 sspec checkpermissions seen 76 snmp append binarv stem L 398 sspec getpermissions eee eee 98
342. nly likely to see CTE_BINARY since HTTP is an 8 bit protocol and most clients browsers will not bother to encode the data Encoding is only an issue for internet mail which sometimes has to cross interfaces that do not support full 8 bit binary transfers If the CGI detects a transfer encoding that requires non null operation that is CTE QPor CTE BASE64 then it should either reject the transfer or decode the data as it comes in It is only valid to call this when the action code is CGI_ START CGI_DATA or CGI_ END PARAMETER NOTE This is implemented as a macro state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Transfer encoding code as documented above LIBRARY HTTP LIB SEE ALSO http_getAction TCP IP Manual Vol 2 rabbit com 215 http getURL char http getURL HttpState state DESCRIPTION Return the URL of the current HTTP client request In a CGI this will usually be something like foo cgi NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Null terminated string containing the URL Note that GET style form parameters will be stripped off for example the URL foo cgi A 99 amp D 45 will be returned as foo cgi The GET parameters are available using http getCond LIBRARY HTTP LIB SEE ALSO http_getAction 216 rabbit com HTTP Server
343. nmp _ init parms snmp set oid snmp append parse oid snmp append stem TCP IP Manual Vol 2 rabbit com 399 snmp append parse oid snmp oid snmp append parse oid snmp oid oid char name DESCRIPTION Appends the specified OID string expressed in dotted decimal format to the OID currently set in the OID structure This function is identical to snmp_append_ parse _ stem except that it uses an snmp oid structure PARAMETERS oid Pointer to snmp oid structure to set If NULL does nothing but return NULL name OID string in dotted decimal notation e g 7 5 99 RETURN VALUE Returns oid unless the OID string is too long to fit in the snmp oid structure in which case NULL is returned If oid is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp append oid snmp append parse stem snmp set stem 400 rabbit com SNMP snmp append parse stem snmp parms snmp append parse stem snmp parms p char name DESCRIPTION Appends the specified OID string expressed in dotted decimal format to the OID currently set in the parameter structure This function is identical to snmp append parse oid except that it uses an snmp_parms structure PARAMETERS p Pointer to parameter structure to set If NULL does nothing but return NULL name OID string in dotted decimal notation e g 7 5 99 RETURN VALUE Returns p unless the OID string is too long to fit in
344. nmp init parms snmp set stem etc RETURN VALUE NULL if p was NULL or if there is no object with the given OID Otherwise returns p LIBRARV MIB LIB SEE ALSO snmp init parms snmp set stem snmp append stem snmp get indexed snmp get next snmp last int snmp last long snmp last mem snmp last xmem snmp last tvpe snmp last len 408 rabbit com SNMP snmp get indexed snmp parms snmp get indexed snmp parms p word i DESCRIPTION Retrieves the object whose MIB tree index is given by i The object information is stored in p and can be examined using the snmp last series of functions The object ID of the re trieved object may be obtained by calling snmp copv oid The object ID is automatically setin p sosnmp_get_next can be called repeatedly to retrieve higher objects in ascend ing sequence of object ID See documentation for snmp last index for information on MIB tree indices PARAMETERS p Parameter structure that was previously initialized by calls to snmp init parms snmp set stem etc i Index of object e g from snmp last index RETURN VALUE NULL if p was NULL or if there is no next object Otherwise returns p LIBRARV MIB LIB SEE ALSO snmp init parms snmp set stem snmp append stem snmp copv oid snmp get snmp get next snmp last index snmp last int snmp last long snmp last mem snmp last xmem snmp last tvpe snmp last len TCP IP Manual Vol 2 rabbit
345. nmp_add and snmp_xadd The macros ensure that the correct type and length parameters are passed The macros for snmp_add are snmp add int p n i snmp add uint p n i snmp add long p n i snmp add ipaddr p n i snmp add timeticks p n i snmp add ulong p n i snmp add str p n s m snmp add oct p n s m snmp add foct p n s m snmp add objectID p n s where parameters p and n are as for this function i is an integer or long integer address s isa char and mis a maximum length TCP IP Manual Vol 2 rabbit com 393 PARAMETERS p tvpe snmp add continued Pointer to parameter structure to set If NULL does nothing but return NULL Optional extra OID level to temporarily append to the OID in p If 1 this is not done Otherwise the level is appended the value added then the ex tra level removed It is not possible to specify OID levels greater than ol 1 Type of value to add This is a composite of the internal type indicating the memory layout and the type visible to SNMP agents The possible composite types are selected from the following list SNMP INTEGER AS SHORT SNMP INTEGER AS LONG SNMP_INTEGER SNMP_OCTETSTR_VARIABLE SNMP_OCTETSTR_NULLTERM SNMP ASCIISTR SNMP OCTETSTR FIXED SNMP OBJECT ID SNMP IPADDR AS OCT SNMP IPADDR AS LONG SNMP COUNTER AS SHORT SNMP COUNTER AS LONG SNMP COUNTER SNMP GAUGE AS SHORT SNMP GAUGE AS LONG SNMP GAUGE SNMP TIMETICKS SNMP_P_INTEGER lt
346. nse to prompts In the following screen shot the command is named login password and is typed in by the user All other screen text shown here was printed by Zconsole B Tera Term COM2 YT Oe x File Edit Setup Control Window Help BasicConsole Version 1 8 ogin passwor password ew Password Retype new Password Password Accepted OK If no identifier is stored for the password a lt CR gt must be sent in response to the prompt for the old pass word NOTE A login name must be stored by a command using con loginname for a login password to be applicable i e if a password has been stored but no login name new console sessions will not prompt for the password or a login name If a login name is applicable but there is no pass word new console sessions will prompt for the login name and grant access after a valid name is entered without prompting for a password con_logout This function exits the current console session and begins a new session by entering the initialization state of Zconsole A command that uses this function takes no parameters con_mail This function sends e mail to the server specified by con mail server with the return address specified by set_mail_from A command that uses this function takes one parameter the destina tion e mail address If the command is named mail the usage is mail destination where com The first line of the message will be used as the subject and th
347. nt ftp data _ handler cont d PARAMETERS dhnd Pointer to data handler function or NULL to remove the current data handler dhnd data A pointer which is passed to the data handler function This may be used to point to any further data required by the data handler such as an open file de scriptor opts Options word currently reserved set to zero LIBRARY FTP CLIENT LIB SEE ALSO ftp client setup ftp last code int ftp last code void DESCRIPTION Returns the most recent message code sent by the FTP server RFC959 describes the codes in de tail This function is most useful for error diagnosis in the case that an FTP transfer failed RETURN VALUE Error code a number between 0 and 999 Codes less than 100 indicate that an internal error oc curred e g the server was never contacted LIBRARY FTP CLIENT LIB SEE ALSO ftp client setup ftp client tick TCP IP Manual Vol 2 rabbit com 319 7 3 Sample FTP Transfer Program Name Samples tcpip ftp ftp_client c define MY_IP ADDRESS 10 10 6 105 define MY_NETMASK 255 255 255 0 define TCPCONFIG 1 memmap xmem use tde E p Lalo use ftp client lib define REMOTREREOS TEN M ONOMA define REMOTE PORT 0 main char buf 2048 int TSI ik WP prine Calling sock init i Val secle _almalie 5 Set up the ftp transfer This is to the host defined above with a normal anonymous e mail password login info A get of the file bar is reques
348. ntation RLER RLER encoding is performed as follows each OID level is an unsigned number between 0 and 232 1 inclusive Reading from left to right each level is encoded and written left to right If the level is less than 254 it is written as a single byte with that value Otherwise if it is less than 65536 it is written as OxFE yy zz OxFE where yy is the MSB of the 16 bit value and zz is the LSB Otherwise the number is 2 65536 and it is written as 6 bytes OXFF ww xx yy zz OxFF where ww is the MSB of the 32 bit number and zz is the LSB The total length of the constructed string is passed in len Note that there are other functions which provide easier ways of setting the object ID in the pa rameter structure This function and related functions serve the purpose of setting the current object identifier in the parameter structure This is necessary for other functions such as snmp_add_int which need to know the applicable object identifier PARAMETERS p Pointer to parameter structure to set If NULL does nothing but return NULL len Length of eos eos Encoded OID string RETURN VALUE Returns p unless the OID string is too long to fit in the parameter structure in which case NULL is returned If p is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp append stem snmp set parse stem snmp set oid 438 rabbit com SNMP snmp set str snmp parms snmp s
349. nting the same type of authentication Rest assured that the HTTP server and other servers provided with Dynamic C always enforce the suggested authentication method The final NULL parameter allows some arbitrary data to be stored in the rule table entry This data is avail able to the server It is not currently used by any of the servers in Dynamic C but it may be useful if you implement your own server Now let s turn to the user ID initialization sauth setusermask sauth adduser admin dog SERVER ANY admin group NULL This is a nested function call sauth adduser is called first to add a user called admin with pass word dog This user is visible to all servers SERVER ANV The result of this function call is a userID handle which is the first parameter to sauth setusermask This function explicitly assigns a group mask to the user You can omit this call however the default method of assigning group masks is designed to be backward compatible with old versions of the librarv and mav not be what vou want when using new features Xou should alwavs use the sauth setusermask function for each user ID In this example we have added access control to the code We do not need to change the ZHTML script although in realitv vou would probablv want to Using the script unchanged when the user tries to retrieve index html the browser will prompt for a userid and password If one of the valid users is
350. number of dvnamic RAM resource table entries to allocate for the global arrav server spec Each entry takes SSPEC MAXNAME 23 bytes of root memory or SSPEC MAXNAME 33 if FORM ERROR BUF is defined Defaults to 10 entries approximately 530 bytes Do not set higher than 511 SSPEC MAX OPEN Determine the maximum number of simultaneously open resources Defaults to 4 Choose this number carefully since each entry can take up a fairly large amount of root storage depending on the mix of filesystems in use Unless you are anticipating a very busy server 4 should be enough If you increase the default value of HTTP MAXSERVERS from 4 you may experience 404 or 503 messages The solution is to increase SSPEC_MAX OPEN Ideally this value should be HTTP MAXSERVERS FTP MAXSERVERS any special use of zserver 1ib that you create SSPEC XMEMVARLEN Defines the size of the stack allocated buffer used by sspec readvariable when read ing a variable in xmem It defaults to 20 3 2 5 Macros for Control Data Initialization As of Dynamic C 8 50 the following macros are available for building the static tables used by the servers 3 2 5 1 Static Rule Table Resource rules are used to associate access information with resource names The following macros define and initialize a static rule table If using a static rule table the dynamically added entries will be searched before the static ones SSPEC FLASHRULES Define this if your a
351. nzenezznnzznzzzi 318 sauth SELSETVET ceccccccccssscsessessessseesesseesesseese 55 sending HTTP headers en 143 sauth setusermask sennen 56 CGE e ea e E eee 138 153 sauth_setwriteaccess ior 57 console serial based cccecccceesseeeeeeeeeeree 459 491 CGI D C81 COMUMUE ioris 186 cgi redirectto L eeenenennennznn 187 daemons Cgi sendstring innies 188 ri 316 http abortCGl even eee 189 FIP server ienien RAA 340 http_defaultCGI Le 193 HTTP server c c sccccosscsesevsesosscsvseesecvassesoeseseseose 218 http_finishCGI nn 196 POP chent i ceicase iat sdonesadncaie 369 http genHeader s esssennnnznnnznnnn 197 telnet sierp neiaie noi Eesi ieii 456 http get SOCk Luwesmsmnnnnnnnneni 213 Hip ek E E 349 http getAction suriros 198 AS C ien se e 475 http getCond LL eee 200 DHCP BOOTP See BOOTP DHCP http_getContentDisposition 201 directory listing a ipod skedi ka ra 79 http getContentLength mn 202 dynamic Web pages eses es eeerenezzznennnnnzznenznn 149 http getContentTVpe 203 TCP IP Manual Vol 2 rabbit com 493 http getContext on 204 Dvnamic RAM Resource Table http Pet ata s1 sesiesonezznz iei i 205 sspec AdACGI oo sccsseisassseesesseeveresssentecsescsee 59 http getDataLength nn 206 sspec addform we 60 bttp getField L vissssseinrezsinnizzznsenpenteptizzoeeies 207 sspec addisfile c ccssesessseeseepesonesersnessses 61 http getHTTPMethod 208 sspec addfunction
352. o a retrieval function such as snmp_get_indexed snmp_get or snmp get next RETURN VALUE If p was NULL returns 0 Otherwise returns the phvsical 20 bit linear address of the object LIBRARV MIB LIB SEE ALSO snmp init parms snmp get snmp get next snmp get indexed snmp last int snmp last long snmp last mem snmp last tvpe snmp last len TCP IP Manual Vol 2 rabbit com 421 snmp monitor int snmp monitor word index long minval long maxval word minintvl word maxintvl word nmesg longword ipaddr word c index int trap num word noids word indices DESCRIPTION Sets up automatic monitoring of a specified managed object This monitors the object which must be integer type so that if the object goes outside the specified lower and upper bound trap mes sages will be sent This function overcomes some of the limitations of the normal snmp_trap mechanism in that it performs automatic retransmissions to practically ensure that the network management agent notices the condition The managed object must exist in the MIB tree and must not be deleted while it is being moni tored Any given object can only be monitored once If the object is already being monitored a call to this function with the same object index will change the monitor settings for that object You must define SNMP_TRAPS to use this function The maximum number of different objects which may be monitored is specified by SNM
353. o change above root directory ENOENT 3rd parameter was TRUE and the directory did not exist SEE ALSO sspec pwd 74 rabbit com Server Utilitv Librarv sspec checkaccess int sspec checkaccess int sspec int userid DESCRIPTION This function checks whether or not the specified user has permission to access the specified re source in the resource table Only read access is checked This function is deprecated as of Dynamic C 8 50 Use the function sspec checkpermissions instead PARAMETERS sspec spec index userid user index RETURN VALUE 0 User does not have access 1 User has access 1 Failure SEE ALSO sspec_needsauthentication sspec_checkpermissions TCP IP Manual Vol 2 rabbit com 75 sspec checkpermissions int sspec checkpermissions int sspec ServerContext context DESCRIPTION Returns the access permissions for the given server and user for the given resource sspec access performs the same function except that a resource name can be given rath er than an open resource handle PARAMETERS sspec spec index context Server context The relevant fields are context gt server the current server SERVER HTTP etc context gt userid current user or 1 for testing the server in general When testing the server in general both O_ READ and O_ WRITE will be re turned RETURN VALUE 20 Bitwise combination of e O READ resource is readable e O WRITE resource h
354. o parse the POSTed data RETURN VALUE 0 There is more processing to do 1 Form processing has been completed LIBRARY HTTP LIB TCP IP Manual Vol 2 rabbit com 221 http safe int http safe char to char from int tolen int fromlen DESCRIPTION Convert a http unsafe string in from length fromlen into a properly escaped string For example the string hello amp goodbye lt gt would be changed to hello amp amp goodbye amp lt amp gt Returns non zero if result could not fit in tolen 1 bytes A null is always added thus tolen should account for this Double quotes are escaped since the result may itself be quoted Newline characters are turned into HTML line break lt BR gt markup Control characters codes less than 32 are turned into amp xx where xx is the hexadecimal control char value The source string can contain null character s which is why its length is passed in the parameter fromlen PARAMETERS to Destination buffer for escaped string from Source buffer for string to convert tolen Length of destination buffer must be at least equal to f romlen since string is never smaller than source string fromlen Length of source buffer RETURN VALUE 0 Success non zero if resulting string plus its null terminator could not fit in the provided buffer LIBRARY HTTP LIB SEE ALSO http_handler 222 rabbit com HTTP Server http scanpost int http scanpost char tag char buffer
355. obably the most common way of retrieving e mail from a remote server Most e mail programs such as Eudora MS Outlook and Netscape s e mail client use POP3 The protocol is a fairly simple text based chat across a TCP socket normally using TCP port 110 There are two ways of using POP3 LIB The first method provides a raw dump of the incoming e mail This includes all of the header information that is sent with the e mail which while sometimes useful may be more information than is needed The second method provides a parsed version of the e mail with the sender recipient subject line and body text separated out In both methods each line of e mail has CRLF stripped from it and 0 appended to it 11 1 Configuration The POP3 client can be configured through the following macros POP BUFFER SIZE This will set the buffer size for POP PARSE EXTRA in bytes These are the buffers that hold the sender recipient and subject of the e mail POP_BUFFER_SIZE defaults to 64 bytes POP DEBUG This will turn on debug information It will show the actual conversation between the device and the remote mail server as well as other useful information POP NODELETE This will stop the POP3 library from removing messages from the remote server as they are read By default the messages are deleted to save storage space on the remote mail server POP PARSE EXTRA This will enable the second mode creating a parsed version of the e mail as ment
356. ocket http getSocket HttpState state DESCRIPTION Return the current HTTP server socket The socket may be written read however this is inadvis able since it may interfere with the server s use of it NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Pointer to the HTTP server s TCP socket structure LIBRARY HTTP LIB SEE ALSO http_getAction TCP IP Manual Vol 2 rabbit com 213 http getState int http getState HttpState state DESCRIPTION Return the current primary HTTP CGI state variable Use of this state variable is entirely up to the application however it is initialized by the HTTP server to zero before calling the CGI for the first time NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Value of primary state variable LIBRARY HTTP LIB SEE ALSO http_getAction 214 rabbit com HTTP Server http getTransferEncoding char http getTransferEncoding HttpState state DESCRIPTION Return the current encoding of the data which is being provided by the client This is one of the following enumerated values CTE BINARY The default TE 7BIT 7 bit safe ASCII BBIT 8 bit ASCII QP Quoted printable mm ta m ti C C C TE_BASE64 Base 64 Of these the CGI is o
357. of doing this is to define a set of users plus a method of authenticating those users and attaching a set of permissions to each resource The Dynamic C libraries allow you to do this fairly easily via two tables The relevant tables are The User Table The user table contains a list of user IDs short strings and authentication information currently a pass word string Each user table entry also contains a group mask The group mask indicates the user groups to which this user belongs Up to 16 groups can be defined and any given user can belong to one or more of these 16 groups There are two additional masks in each user table entry The first is a write access mask that indicates which server s allow the user to write modify its resources The second mask indicates the server s that can recognize the user The Rule Table The rule table is a list of information associated with each resource name generally called permissions Each resource has the following information e The realm string that may be used by certain servers including HTTP e The group mask of the user groups that are allowed read only access e The group mask of the user groups that are allowed modify write access e The server s that are allowed any access to this resource e The authentication method that is recommended e The MIME type of the resource Resources in the static and dynamic resource tables may be set up to have their own
358. of the form function spec index of the function This is the return value of sspec addfunction RETURN VALUE 0 Success 1 Failure SEE ALSO sspec_setformepilog 120 rabbit com Server Utility Library sspec setformtitle int sspec setformtitle int form char title DESCRIPTION Sets the title for an automatically generated form PARAMETERS form spec index of the form title Pointer to the title of the HTML page RETURN VALUE 0 Success 1 Failure SEE ALSO sspec getformtitle sspec setfvcheck int sspec setfvcheck int form int var int varcheck DESCRIPTION Sets a function that can be used to check the integrity of a variable The function should return 0 if there is no error or 10 if there is an error PARAMETERS form spec index of the form var Index into the FormVar array of the variable varcheck Pointer to integrity checking function RETURN VALUE 0 Success 1 Failure SEE ALSO sspec setfvfloatrange sspec setfvoptlist sspec setfvrange TCP IP Manual Vol 2 rabbit com 121 sspec setfvdesc int sspec setfvdesc int form int var char desc DESCRIPTION Sets the description of a variable that is displayed in the HTML form table PARAMETERS form server spec index of the form var Index into the FormVar array of the variable desc Description of the variable This text will display on the HTML page RETURN VALUE 0 Success 1 Fai
359. og events to the STDIO window in Dynamic C This provides a convenient way of troubleshooting an e mail problem SMTP DOMAIN This macro defines the text to be sent with the HELO client command Many mail servers ignore the information supplied with the HELO but some e mail servers require the fully qualified name in this field i e somemachine somedomain com If you have problems with e mail being reject ed by the server turn on SMTP_ DEBUG If it is giving an error message after the HELO line talk to the administer of the machine for the appropriate value to place in SMTP_ DOMAIN If you do not define this macro it will default to MY_IP_ ADDRESS define SMTP DOMAIN somemachine somedomain com SMTP MAX DATALEN Defaults to 256 Maximum buffer size for server responses and short client requests SMTP MAX PASSWORDLEN Defaults to 16 Maximum length of the password used in authentication SMTP MAX USERNAMELEN Defaults to 64 Maximum length of the user name used in authentication SMTP MAX SERVERLEN Defaults to MAX_ STRING which defaults to 50 Maximum length of mail server name SMTP SERVER This macro defines the mail server that will relay the controller s mail This server must be con figured to relay mail for your controller You can either place a fully qualified domain name or an IP address in this field define SMTP SERVER mail mydomain com define SMTP SERVER 10 10 6 19 SMTP TIMEOUT This macro tells the SMTP code
360. ole lib SEE ALSO con set user timeout con set timeout unsigned long con set timeout unsigned int seconds DESCRIPTION Returns the value that MS TIMER should have when the number of seconds given have elapsed LIBRARY zconsole lib SEE ALSO con chk timeout 480 rabbit com General Purpose Console con set user timeout void con set user timeout void funcptr DESCRIPTION Sets a user defined function that will be called when a timeout event has occurred The user defined function should take an argument of type ConsoleState LIBRARY zconsole lib SEE ALSO con set user idle console disable void console disable int which DESCRIPTION Disable processing for the designated console inthe console io array This function along with console enable allows the sharing of the Zconsole port with some other process ing PARAMETER which The console to disable LIBRARV zconsole lib SEE ALSO console init console enable TCP IP Manual Vol 2 rabbit com 481 console enable void console enable int which DESCRIPTION Enable processing for the designated console in the console _io array This function along with console disable allows the sharing of the Zconsole port with some other process ing PARAMETER which The console to enable LIBRARY zconsole lib SEE ALSO console init console disable 482 rabbit com General Purpose Console 14 6
361. on NOTE Throughout this document the FAT file system is the destination for the uploaded file The FAT uses a variety of storage media from the onboard serial flash to NAND flash or SD cards 164 rabbit com HTTP Server 4 6 2 How Do Use the New CGI Facility There are a number of steps some of which will be familiar to users of CGIs in previous releases They are listed here and described in more detail in the following pages The steps if coding from scratch are use dertcp lib and specify network configuration options use lt filesystem s of choice gt and specify the file system configuration define USE HTTP UPLOAD use http lib Create an initial web page with a form asking for the file s to be uploaded The main requirement is that you specify enctype multipart form data inside the lt FORM gt tag s nA A U N e D Write a CGI function if not using the default one provided 7 Create an initial resource table containing at least an entry for each of the above two resources the web page and the CGI 8 Create a list of content type mappings i e the MIME table 9 Create rules which limit the upload facility to select user groups 10 Create a set of user IDs 11 In the main program call http handler ina loop Step 1 Specify Network Configuration To make use of HTTP upload you need to perform the usual inclusion and configuration of the network ing library dcrtc
362. on 0 to disable basic authentication Set to 1 by default 4 2 1 Sending Customized HTTP Headers to the Client The callback macro HTTP CUSTOM HEADERS will be called whenever HTTP headers are being sent It must be defined as a function with the following prototype void mv headers HttpState state char buffer int bytes state Pointer to the state structure for the calling web server buffer The buffer in which the header s can be written bytes The number of bytes available in the buffer Typically the macro would be defined by the user before the use http lib statement like in the following define HTTP CUSTOM HEADERS state buffer bytes my headers state buffer bytes Then for the above to work my headers must be defined by the user like so void my_headers HttpState state char buffer int bytes strcpy buffer Hello Rabbit r n printf bytes d n bytes In the real world the user may need to check the number of bytes available to be sure they don t overwrite the buffer The buffer must end with r n and be NULL terminated TCP IP Manual Vol 2 rabbit com 143 4 2 2 Saving Custom Headers from the Client Customers may want to save some specific headers that a web client sends to the server as part of a request One possibility for this is to check the browser version of the client and display a different page depending on that value This is mostly useful for CGI functions
363. on after a couple of seconds Point your internet browser at the controller e g http 10 10 6 100 The ACT light will flash a couple of times and your browser will display the page 146 rabbit com HTTP Server Program Name Samples tcpip http Static c define TCPCONFIG 1 define TIMEZONE 8 memmap xmem kuse dortop libp use http lib ximport samples tcpip http pages static html index html ximport samples tcpip http pages rabbitl gif rabbitl gif SSPEC MIMETABLE START SSPEC MIME html Meest isjeml U SSPEC MIME gif image gif SSPEC MIMETABLE END SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE index html index html SSPEC RESOURCE XMEMFILE rabbiti gif rabbit1_gif SSPEC RESOURCETABLE END main sock init Initializes the TCP IP stack werp taie h p Initializes the web server te reservepori 90 5 while 1 http handier The program serves the static html file and the rabbit1 gif file to any user contacting the con troller If you want to change the file that is served by the controller find and modify this line in Static c ximport samples tcpip http pages static html index html Replace static html with the name of the file you want the controller to serve TCP IP Manual Vol 2 rabbit com 147 4 5 1 1 Adding Files to Display Adding additional files to the controller to serve as web pages is slightly more complicated First add an ximport lin
364. on page 468 Each of these functions return 0 when it has more processing to do and thus will be called again 1 for successful completion of its task and 1 to report an error Parameters needed by the commands using these functions are passed on the command line con add nameserver This function adds a name server to the list of name servers unlike con set nameserver that clears the list of name servers and adds one name server A command that use this function takes one parameter the IP address of the name server in dotted quad notation con_createv This function creates a variable that can be used with SSI commands in SHTML files Certain SSI com mands can be replaced by the value of this variable so that a web page can be dynamically altered without re uploading the entire page Note however that the value of the variable is not preserved across power cycles although the variable entry is still preserved That is the value of the variable may change after a power cycle It can be changed again though with a put v command It works in the following fashion if the command is called CREATEV usage createv lt varname gt lt vartype gt lt format gt lt value gt strlen A web variable that can be referenced within web files is created lt varname gt is the name of the variable lt vartype gt is the type of the variable INT8 INT16 INT32 FLOAT32 or STRING lt format gt is the printf style format sp
365. onfiguration Reload the page with committed values Of the five rows two have Local TCP Port 1234 text entries and three have Baud Rate 9600 drop down menus one for Data Bits 8 each of the three selection variables defined in the Parity Nong fi Dvnamic C application code Stop Bits 1 gt shown above We will not show the rest of the HTML code here because it is too repetitive and we have seen similar code in the humidity detector example There are two lines however that are worth further discussion SANUS eSeic fi NAME lt zZ varname Sserial portsISAJ tep port gt SLAh 5 WALUI I222 eto Sserie joes ISA ceo _ joe PS s The two text fields in the above form are created with INPUT tags like the one shown here Recall that the NAME attribute does not allow the use of or The call to varname solves that problem for us lt SELECT NAME lt z varname Sserial ports SA ser parity gt gt 424 printe select Sserial pores SA ser parity Ps lt SELECT gt TCP IP Manual Vol 2 rabbit com 287 The SELECT tag is used to create a drop down menu in HTML which is a convenient way to display a RabbitWeb selection type variable 5 5 RabbitWeb Reference This section is the repository of some specialized details such as the grammars that describe the scripting language and the Dynamic C enhancements It is also intended as a way to quickly find descriptions of particular components of the
366. only time the server changes the cond variables is at the start of a completelv new form submission in which case thev are usuallv set to zero But don t depend on them being zero since a form submission can sometimes contain svntax that sets them to non default values You can rely on http getState returning zero on the very first call thereafter it is not touched but can be manipulated by the CGI calling the function http setState 172 rabbit com HTTP Server Having retrieved the open file handle you didn t save it in a static variable did you it is used in the sspec write call http getData returns the available data and http getDataLength returns its length in bytes The maximum length that http getDataLength will return is HTTP MAXBUFFER which is a macro controlled by the application defaulting to 256 Often the available data length will be less than this even in the middle of a long file Note that the return code from sspec write is not checked This is a shortcoming that we fix later since the solution can be slightly complex For now we just hope that it works Action Code CGI END The next thing to consider is closing the file when the upload is complete For this we make use of the CGI END action code case CGI END handle http getCond s COND HANDLE sspec close handle break This is quite simple We simply retrieve the handle and close it Response to the Client Redirectio
367. opying the original entry into the new entry Note that aliasing can also be done for files and other types of server objects sspec aliasspec form index html sspec aliasspec form These lines complete the sample program They initialize the TCP IP stack and web server and run the web server SOCK slmalie g aeto dmit p while 1 http handler This is the form that is generated ACME Thermostat Settings Netscape File Edit View Go Communicator Help KI Back Forward Reload Home Search Netscape Print Security Shop TEN AG Bookmarks Goto v 37 What s Related ACME Thermostat Settings Name Value Description High Temp jo Maximum in temperature range 60 90 F Current Temp 72 Current temperature in F Low Temp js Minimum in temperature range 50 80 F Failure Action Pae H Action to take in case of air conditioning failure Humidity 0 30 Target humidity between 0 0 and 1 0 Submit Reset TCP IP Manual Vol 2 rabbit com 163 4 6 HTTP File Upload This section describes the HTTP file upload feature available starting with Dynamic C 8 50 The enhanced CGI capabilities of this version of Dynamic C allow files of unlimited size to be uploaded using a web interface It has always been possible to upload files using FTP however it is usually more convenient to use a browser based upload 4 6 1 What is a CGI Function and Why is I
368. ore details length On upload length of file on download size of buffer This parameter limits the transfer size to a maximum of 32767 bytes For larger transfers it will be necessary to use a data handler function RETURN VALUE 0 Success NETERR_DNSERROR Couldn t resolve hostname from URL NETERR_HOST_REFUSED Couldn t connect to FTP server EINVAL Error parsing URL E2BIG URL is too big to parse Increase URL MAX BUFFER SIZE to handle larger URLs LIBRARY FTP CLIENT LIB SEE ALSO ftp client setup ftp client tick ftp data handler TCP IP Manual Vol 2 rabbit com 315 ftp client tick int ftp client tick void DESCRIPTION Tick function to run the FTP daemon Must be called periodically The return codes are not very specific You can call ftp last code to get the integer value of the last FTP message received from the server See RFC959 for details For example code 530 means that the client was not logged in to the server RETURN VALUE FTPC AGAIN still pending call again FTPC_OK success file transfer complete FTPC_ERROR failure call ftp last code for more details FTPC NOHOST failure Couldn t connect to remote host FTPC NOBUF failure no buffer or data handler FTPC TIMEOUT warning Timed out on close data may or may not be OK FTPC_DHERROR error Data handler error in FTPDH_END operation FTPC CANCELLED FTP control socket was aborted reset by the server LIBRARY FT
369. ork once the original handle is closed You can test whether such a virtual handle has been returned using the macro SSPEC IS VIRT sspec PARAMETERS sspec sspec index that this function will alias name Alias name RETURN VALUE 1 Failure 20 Success return location of alias i e new index SEE ALSO sspec addform sspec addfsfile sspec addfunction sspec addrootfile sspec addvariable sspec addxmemfile TCP IP Manual Vol 2 rabbit com 71 sspec automount int sspec automount word which void xx fatstuff void fs2stuff void reserved DESCRIPTION This function automatically initializes and mounts the specified filesystem s for use by Zserver Mounting a filesystem creates an entry point to that filesystem for the server You must use the appropriate filesystem library for example FS2 LIB otherwise the file system will not be mountable If using the FAT library you must include one or more driver libraries such as sflash fat 1lib before use fat lib Only the default device from the first driver li brary will be initialized and used by this routine If you need to use any other devices you will need to initialize them individually and call the sspec fatregister function SSPEC MAX FATDRIVES will also need to be increased from its default value of one For the FAT library this routine calls fat Init and mounts the first available FAT partition on that drive if any If
370. ose the serial port PARAMETERS id ID of the gateway to change as specified in the spec table RETURN VALUE 0 Success 1 Failure LIBRARY VSERIAL LIB 450 rabbit com Telnet vserial init int vserial init void DESCRIPTION Initializes the daemon and parses the spec table RETURN VALUE 0 Success 1 Failure LIBRARY VSERIAL LIB vserial keepalive int vserial keepalive int id long timeout DESCRIPTION This function sets the keepalive timer to generate TCP keepalives after timeout periods of in activity This helps detect if the connection has gone bad Keepalives should be used at the application level but if that is not possible then timeout should be set so as to not overload the network The standard timeout is two hours and should be set sooner than that only for a Very Good Reason PARAMETERS id Unique gateway identifier timeout Number of seconds of inactivity allowed before a TCP keepalive is sent A value of 0 shuts off keepalives RETURN VALUE 0 Success 1 Failure LIBRARY VSERIAL LIB TCP IP Manual Vol 2 rabbit com 451 vserial listen int vserial listen int id long baud int port long remote host int flags DESCRIPTION Listens on the specified port for a telnet connection The gateway process is started when a con nection request is received On disconnect re listen happens automatically PARAMETERS id baud port remote host flags RETU
371. ot have write access 1 User has write access 1 Failure SEE ALSO sauth setwriteaccess 52 rabbit com Server Utility Library sauth removeuser int sauth removeuser int userid DESCRIPTION Remove the given user from the user list IMPORTANT Any associations of the given user with web pages should be changed Other wise no one will have access to the unchanged web pages Authentication can be turned off for a page with sspec setrealm sspec PARAMETERS userid Index in user table RETURN VALUE 0 Success 1 Failure SEE ALSO sauth_adduser TCP IP Manual Vol 2 rabbit com 53 sauth setpassword int sauth setpassword int userid char password DESCRIPTION Sets the password for a user PARAMETERS userid Index of user in user table password User s new password RETURN VALUE 0 Success 1 Failure SEE ALSO sauth_getpassword 54 rabbit com Server Utility Library sauth setserver int sauth setserver int sauth int server DESCRIPTION Sets whether a user is visible to the specified server s PARAMETERS sauth User index server Server bitmask with bit set to 1 to make this user known to the server If this parameter is zero then the user is visible to ALL servers however it is recommended to pass the value SERVER_ANY in this case RETURN VALUE 0 Success 1 Failure SEE ALSO sauth_getserver TCP IP Manual Vol 2 rabbit com
372. ource Resource FS2 FAT i Table Table i Cond BIENE eae ane ise Storage Program acl Battery Serial As mentioned previously Zserver implements a virtual filesystem that can be used by an application for a clean consistent interface to the various available methods of resource organization An application can also bypass the resource manager and access a filesystem directly Note that there is no arrow in the dia gram showing this line of communication Looking at the bottom of the diagram in Figure 2 6 you can see that there are some additional hardware requirements when using FAT or FS2 The FAT needs a serial flash and FS2 needs a second flash or bat tery backed RAM as well as a Rabbit 2000 or 3000 processor 22 rabbit com Web Enabling Your Application The sample program is now expanded to use a FAT filesystem and has the ability to upload files to it As before the changes are in boldface define FAT USE FORWARDSLASH define FAT BLOCK define USE HTTP UPLOAD define TCPCONFIG 1 define USE RABBITWEB 1 define USE HTTP BASIC AUTHENTICATION 1 use sflash fat lib use fat lib use dertcp lib use http lib web groups monitor group admin group ximport mv app zhtml mv app zhtml SSPEC MIMETABLE START SSPEC MIME FUNC html text html zhtml_handler SSPEC MIME cgi SSPEC MIMETABLE END SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE index html mv app zhtml SSPEC RESOU
373. owing code shows the relevant sections for following this protocol int len newlen define COND LEN 1 case CGI DATA handle http getCond s COND HANDLE len sspec write handle http getData s http getDatalLength s if len lt 0 permanent error sspec close handle http switchCGI s upld_err html else if len lt http getDataLength s no error but not all written http setCond s COND LEN len save place in file return CGI MORE tell server we re not done break TCP IP Manual Vol 2 rabbit com 177 case CGI CONTINUE CGI_MORE returned last time handle http getCond s COND HANDLE get file handle len http getCond s COND LEN get place in file Try writing the part that wasn t written newlen sspec_write handle http getData s len http getDatalLength s len if newlen c 0 permanent error when retrving sspec close handle http switchCGI s upld_err html else sum the total written count len newlen if len lt http getDataLength s still haven t written all http setCond s COND LEN len save new place return CGI MORE tell server we re not done break The important point is that when CGI_ CONTINUE is the action code the CGI retries the failed part of the previous operation then tests whether it is complete On completion the usual 0 return code is returned otherwise the CGI
374. owing line in your application program use dertcp lib If you are serving web pages you must also include http lib and if you are sending e mail you must include smtp lib 474 rabbit com General Purpose Console 14 6 4 Required Zconsole Functions To run the console the following two functions are required console init int console init void DESCRIPTION This function will initialize Zconsole data structures It must be called before console tick is called for the first time This function also loads the configuration infor mation from the file system RETURN VALUE 0 Success 1 No configuration information found lt 0 Indicates an error loading the configuration data 1 indicates an error reading the 1st set of information 2 the 2nd set and so on LIBRARY zconsole lib console tick void console tick void DESCRIPTION This function needs to be called periodically in an application program to allow Zconsole time for processing LIBRARY zconsole lib TCP IP Manual Vol 2 rabbit com 475 14 6 5 Useful Zconsole Function Most of the following functions are only useful for creating custom commands con backup int con backup void DESCRIPTION This function backs up the current configuration RETURN VALUE 0 Success 1 Failure LIBRARV zconsole lib SEE ALSO con backup reserve con load backup con backup bvtes long con backup bvtes void DESCRIPT
375. p 1lib At its simplest it is two lines of code at the top of your main program define TCPCONFIG 1 use dertcp lib This specifies that the default TCP networking configuration is to be used If you want to change the default networking configuration first read the comments at the top of tcp config lib HTTP upload usually requires at least two additional libraries to be included a file system library and http lib itself A file system is required otherwise the uploaded file has nowhere to go although you can write a CGI which processes the file as it is uploaded in which case you do not need to store it perma nently and thus you do not need to include a file system the following discussion assumes that you are using a file system TCP IP Manual Vol 2 rabbit com 165 Steps 2 3 and 4 Specify File system and Web Server You need to include the file system library or libraries before including http 1ib This is because the HTTP library needs to know about the filesystem s it is going to support In addition you need to tell the HTTP library to use the upload facility For example if you want to use the FAT file system then you would write the following define TCPCONFIG 1 use dertcp lib fuse fat lib Step 2 the filesystem define USE HTTP UPLOAD Step 3 enable upload feature use http lib Step 4 HTTP server code The order of the above statements is important A possible exception is that the ord
376. p to the handler to ensure that another FTP server is not accessing a file which is opened for write The open call for the other server should return FTP_ERR_UNAVATL if the current server is writing to a file PARAMETERS fd The file descriptor returned when the file was opened buf Pointer to the data to be written offset Offset in the file at which to start len The number of bytes to write RETURN VALUE 20 The number of bytes written If this is less than len an error occurred 1 Error 328 rabbit com FTP Server ftp dflt close int ftp dflt close int fd DESCRIPTION The default close handler does nothing but return zero The handler may close the specified file and free up any temporary resources associated with the transfer PARAMETERS fd The file descriptor returned when the file was opened RETURN VALUE 0 TCP IP Manual Vol 2 rabbit com 329 ftp dflt list int ftp dflt list int item char line int listing int uid int cwd DESCRIPTION Returns the next file for the FTP server to list The file name is formatted as a string PARAMETERS item line listing uid cwd RETURN VALUE Index number starting at zero for the first function call Subsequent calls should be one plus the return value from the previous call Pointer to location to put the formatted string Boolean variable to control string form 0 print file name permissions date etc 1 print file name on
377. pec open call The context structure contains some details such as the current user ID but the details are usually not relevant to the CGI function itself The file is created if it does not exist and it is ini tially truncated if it already exists The return value from sspec open is stored in the cond variable COND_HANDLE which is a macro we defined to zero so we wouldn t have to remember hard coded num bers The return value is either negative if there was an error or not negative in which case it is a valid file handle We check the cond variable just set to make sure it has a valid value The else clause is added so that if the part is not a file to upload the rest of the data for this part is ignored This is convenient since we don t want to get called with CGI_DATA or CGI END if this is not a file If http skipCGI is called then the next action code will be either CGI_ START if there is another part or CGI_ EOF if there were none Note that we are also calling http_skipCGI in the case that the file could not be opened Action Code CGI DATA Let s now turn to saving the data For this we make use of the CGI DATA action code int handle case CGI DATA handle http getCond s COND HANDLE sspec write handle http getData s http getDataLength s break First the open file handle is retrieved from the cond variable This works because the HTTP server does not touch these variables between calls The
378. pen to press the submit button at about the same time Thus it is important to write the CGI function so that it is re entrant This basically means that the function should not update global or static variables The CGI should not attempt to modify directly any of the fields in the Ht tpState structure otherwise the server may become inop erable API Functions The HTTP library provides a set of API functions that can be called safely from the CGI The list of safe functions is in the index under Function Reference CGI It is unwise to make direct calls to TCP IP functions especially functions that may not return for a long time such as sock read How to Transfer Form Submission Data To understand how to write a CGI function it is necessary to have some understanding of the protocol used to transfer the form submission data Since the data can consist of one or more files and or form fields there needs to be a way of separating them within the one sequential stream of data that is sent by the client 168 rabbit com HTTP Server The way this is done is that the client specifies a unique string that separates each item of data The follow ing text is a dump of the actual data sent by a client with some irrelevant details omitted and with com ments added in italics POST upload cgi HTTP 1 1 This indicates that it is POSTed form data and the target handler is upload cgi Content length 277 This gives the total number
379. plo 65 That is it sends back name and value pairs separated by the amp character There can be some further encoding done here to represent special characters but we will ignore that in this explanation The server must read in the information decode it parse it and then handle it in some fashion It will examine the new values and assign them to the appropriate C variables if they are valid 4 5 3 2 POST Style Form Submission If an HTML file specifies a POST style form submission that is METHOD POST the form will still be waiting on the socket when the old style CGI handler is called Therefore it is the job of the CGI han dler to read this data off the socket and parse it in a meaningful way The sample files Post c and Post2 cinthe Samples Tcpip Http folder show how to do this The HTTP POST command can put any kind of data onto the network There are many encoding schemes currently used but we will only look at URL encoded data in this document Other encoding schemes can be handled in a similar manner TCP IP Manual Vol 2 rabbit com 155 4 5 3 3 URL Encoded Data URL encoded data is of the form name1l value1 amp name2 value2 and is similar to the CGI form submis sion tvpe passed in normal URLs This has to be parsed to name value pairs The rest of this section details an extensible wav to do this This initializes two possible HTML form entries to be received and a place to store the results defin
380. pplication is using static rules You must define this if you want to use the macro SSPEC RULETABLE START If you define SSPEC FLASHRULES and you do not need dynamic rules you can define the macro SSPEC_MAXRULES to zero to recover the root memory that would be wasted otherwise SSPEC RULETABLE START SSPEC RULE prefix realm rg wg sm SSPEC MM RULE prefix realm rg wg sm method mimetype SSPEC RULETABLE END This sequence of macros is used to define static rules See the documentation with the sspec addrule function for more information You must define SSPEC_FLASHRULES to use these macros TCP IP Manual Vol 2 rabbit com 41 3 2 5 2 Static MIME Type Table This table maps file extensions and MIME types You only need such a table if using a server that requires MIME types Currently only the HTTP server needs this SSPEC MIMETABLE START SSPEC MIME extension tvpe SSPEC MIME FUNC extension tvpe function SSPEC MIMETABLE END This sequence sets up the MIME type mapping table Currently only a static MIME table is sup ported Though you cannot dynamically add new MIME types to this table it is possible to allo cate new MIMETypeMap structures in RAM and assign them to specific resources using sspec_addrule orsspec_setpermissions Such entries will not be accessed using the default resource name extension method 3 2 5 3 Static Resource Table The static resource table associates the names of web server resources
381. ps track of state information in this structure EXAMPLE To iterate through all resources under A 7 ServerContext ctx int item char buf 80 word opts word n ctx rootdir ctx server SERVER FTP ctx userid sauth getuserid foo SERVER FTP sspec cd A amp ctx for item 0 item gt 0 item sspec dirlist item buf sizeof buf amp ctx SSPEC LIST LONG if item s 0 printf buf finished now can re use ctx TCP IP Manual Vol 2 rabbit com 79 sspec dirlist cont To iterate through the first 5 resources only opts SSPEC LIST LONG for item 0 n 0 item gt 0 n if n gt 4 opts SSPEC_LIST_END item sspec dirlist item buf sizeof buf amp ctx opts if item gt 0 printf buf PARAMETERS item Directory entry to list If zero this always returns the first entry in the direc tory Thereafter pass the return value from the previous call to this function to get the next item s NOTE the return value does not necessarily count up 1 2 3 etc Apart from 0 the only values you should pass in this parameter are previous return values otherwise the results will be undefined line Points to buffer that is filled with resulting string The string will be termi nated with r n CRLF then a NULL linelen Length of the above buffer If it is not long enough then the line will be trun cated however it will still have the ter
382. r SSPEC MIMETABLE END SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE index html mv app zhtml SSPEC RESOURCETABLE END int io state web io state auth basic groups monitor group ro admin group void mv io polling void void main sspec addrule index html Pet admin groupjmonitor group 0 SERVER HTTP SERVER AUTH BASIC NULL sauth setusermask sauth adduser admin dog SERVER ANY admin group NULL sauth setusermask sauth adduser monitor cat SERVER ANY monitor group NULL sock init http init for my_io_polling http handler void mv io polling io state read that io device 18 rabbit com Web Enabling Vour Application The first change is the definition of USE HTTP BASIC AUTHENTICATION This sets up the HTTP server to be able to process this form of authentication If not defined then the server is unable to do this there is little point in setting up any other access controls if the user cannot be verified Next the user groups are defined In this case we are defining an admin and a monitor group Pre sumably the admin group has ability to alter the state of the controller but the monitor group can only read its current state The names admin group and monitor group are actually defined to be unsigned integer constants with just one bit set out of 16 The web registration of the io state variable is augmented with some access
383. r as provided in the first parameter to the CGI function dp Buffer containing data to be written as an xmem address obtained from for example xalloc len Maximum number of bytes to write to the socket RETURN VALUE Number of bytes of written or 1 if there was an error LIBRARY HTTP LIB TCP IP Manual Vol 2 rabbit com 239 https set cert void https set cert SSL Cert t far cert DESCRIPTION Register a server certificate with all HTTPS server instances Client hosts such as web browsers will verifv this certificate and mav refuse to connect if there is no certificate or the server certif icate is not valid This must be called at least once otherwise there mav be no default certificate Alternativelv vou can use the method that was deprecated in Dvnamic C 10 54 Have the follow ing line at the top of vour main program ximport cert dcc SSL CERTIFICATE where cert dcc is the name and path of the server certificate file to use which must be in dcc format The use of SSL CERTIFICATE is deprecated since https set cert provides a more flexible interface PARAMETER cert Pre parsed certificate as generated by SSL new cert LIBRARV HTTP LIB SEE ALSO SSL new cert 240 rabbit com HTTP Server http status int http status void DESCRIPTION Determine whether the HTTP server is allowing connections RETURN VALUE 0 server is currently disabled non zero server is enabled
384. r all resources need to be limited to a select set of users e If so how confident does your application need to be that the user s credentials are valid e Do you need to be able to upload large amounts of data over say 250 bytes e Do you want to update the web pages themselves or maybe even the entire application firmware e Is the application small medium or large e Do you want to use this same web interface to configure all aspects of the application including for example the network settings In other words is the web interface going to be the only interface once the unit leaves the factory TCP IP Manual Vol 2 rabbit com 3 The first and second questions relate to user authentication and access control The next two questions relate to the HTTP upload facility The last two questions concern the overall design of your application in particular a large application may necessitate more storage than is usually available for a given Rabbit product and may require a sophisticated filesystem to manage the large number of resources Since the terms small medium and large are rather vague we shall define them by example A small appli cation would be limited to less than 10 different web pages and up to about 30 different controls but tons to press dials to twiddle options to select etc A large application may have upwards of 100 pages and more than 10KB of configurable data A medium application sits as you
385. r clients to connect Define SMTP_ PORT to override the default port number Sending mail with the Dynamic C SMTP client library is a simple process demonstrated in the sample program shown in Section 10 3 Dynamic C 9 introduced SMTP authentication described below in Section 10 2 10 1 Sample Conversation The following is a typical listing of mail from the controller me somewhere com to someone somewhereelse com The mail server that the controller is talking to is mail somehost com The lines that begin with a numeric value are coming from the mail server The other lines were sent by the controller More information on the exact specification of SMTP and the meanings of the commands and responses can be found in RFC821 at www ietf org 220 mail somehost com ESMTP Service WorldMail 1 3 122 ready HELO 10 10 6 100 250 mail somewhere com MAIL FROM lt me somewhere com gt 250 MAIL FROM lt me somewhere com gt OK RCPT TO lt someone somewhereelse com gt 250 RCPT TO lt someone somewhereelse com gt OK DATA 354 Start mail input end with lt CRLF gt lt CRLF gt From lt me somewhere com gt To lt someone somewhereelse com gt Subject test mail test mail 250 Mail accepted QUIT 221 mail somehost com QUIT TCP IP Manual Vol 2 rabbit com 353 You can see a listing of the conversation between your controller and the mail server by defining the SMTP_DEBUG macro at the top of your program Note that there
386. r simplicity it only supports listening on TCP sockets meaning that Ethernet to serial devices can only be started by another device initiating the network connection to the Rabbit Each serial port is associated with a specific TCP port The Rabbit listens on each of these TCP ports for a connection It then passes whatever data comes in to the associated serial port and vice versa 5 4 1 Dynamic C Application Code The program starts with a configuration section define TCPCONFIG 1 This define statement sets the predefined TCP IP configuration for this sample If the default network configuration of 10 10 6 100 255 255 255 0 and 10 10 6 1 for the board s IP address netmask and gate way nameserver respectively are not acceptable change them before continuing See LIB TCPIP TCP CONFIG LIB for instructions on how to change the configuration Const chan portetconti ijit 11 1i y define E2S_BUFFER_SIZE 1024 define HTTP_MAXSERVERS 1 define MAX TCP SOCKET BUFFERS HTTP_MAXSERVERS sizeof ports config define SERINBUFSIZE 127 define SEROUTBUFSIZE 127 Each element in array ports config corresponds to a serial port In the following code the size of this array will be used in for loops to identify initialize and monitor the serial ports A buffer is defined that will hold the data that is being passed from the Ethernet port to the serial port The number of server instances is set to one and the number of socket buff
387. r type SSPEC MAXNAME MIME type e g text html int fptr Server specific processing e g SSI MIMETvpeMap A valid pointer is always returned If the appropriate table entry cannot be located by the re source s extension or using a rule see sspec addrule then the first table entry is returned SEE ALSO sspec_addrule 96 rabbit com Server Utility Library sspec getname char sspec getname int sspec DESCRIPTION Returns the name of the spec entry represented by the sspec index This only works for RAM and flash table entries PARAMETERS sspec spec index RETURN VALUE NULL Failure INULL Success pointer to name string TCP IP Manual Vol 2 rabbit com sspec getpermissions int sspec getpermissions int sspec char realm word readgroups word writegroups word servermask word method MIMETypeMap mimetype DESCRIPTION Get the permission access control attributes of a resource Except for sspec all parameters are pointers to variables that will be set to the appropriate return value If the parameter is NULL then that information is not retrieved NOTE The data at realm and mimetype should not be altered by the caller The data is read only PARAMETERS sspec realm readgroups writegroups servermask method mimetype RETURN VALUE 0 Success spec index Pointer to pointer to realm string Pointer to mask of user groups who have read acces
388. rabbit com SNMP snmp append binary oid snmp oid snmp append binary oid snmp oid oid word len char bname DESCRIPTION Append the object ID encoded as a string of bytes to the OID currently set in oid This function may be used when all levels in the OID string are numbers between 0 and 255 inclusive Each OID level is simply the binary value of each byte pointed to by bname The number of levels i e bytes is specified by len For example to append 255 6 0 1 make the following call snmp append binary oid oid 4 xFF x06 x00 x01L This function is identical to snmp append binary stem except that it uses an snmp_ oid structure PARAMETERS oid Pointer to snmp oid structure to set If NULL does nothing but return NULL len Number of bytes in bname bname Pointer to first byte of OID RETURN VALUE Returns oid unless the OID string is too long to fit in the snmp oid structure in which case NULL is returned If oid is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp append oid snmp append binary stem snmp set stem TCP IP Manual Vol 2 rabbit com 397 snmp append binary stem snmp parms snmp append binary stem snmp parms p word len char bname DESCRIPTION Append the object ID encoded as a string of bytes to the OID currently set in p This function may be used when all levels in the OID string are numbers between 0 and 255 incl
389. realistic we need to add some application specifics and the ability to customize the resource returned to the browser depending on the relevant state of the application The following diagram shows the necessary parts Figure 2 3 Minimum components for a web enabled application with dynamic content Application Compile Time Run Time Main Application CGI Initialization Initialization Loop Specifics LQ Functions web Variables Saar Requests Context Metadata Resources Zserver Resource Manager p Virtual File Virtual File System Static Resource Table Dynamic Resource Serial Flash Battery Backed RAM The easiest way to introduce dynamic content is to use RabbitWeb and the associated scripting language SSI can be used instead described in Section 4 5 2 1 This example illustrated in Figure 2 3 assumes that you have RabbitWeb Chapter 5 describes RabbitWeb and the scripting language ZHTML in detail TCP IP Manual Vol 2 rabbit com 13 The following code is a simplification of Samples tcpip rabbitweb web c define TCPCONFIG 1 define USE RABBITWEB 1 use dertcp lib use http lib ximport my app zhtml my app zhtml SSPEC MIMETABLE START SSPEC MIME FUNC html text html zhtml_handler SSPEC MIMETABLE END SSPEC RESOURCETABLE START SSPEC RESOURCE XMEMFILE index html my app zhtm1 SSPEC RESOURCETABLE END
390. rectory Navigation sspec_getfVNaMe Lena 92 SSPO CSCO i e e 74 sspec getfVnum e neneenenzzzznnzn 93 SSpe dIVUISt siiisisiis jint pesinat ini nien EB 79 sspec gettVOpt 0 ee enenennznznenn 93 SSPOC PW ccsscsscstiscaessnsasstsedvasstenssabieccresets 109 sspec_getfvoptlistlen eee 94 494 rabbit com Index sspec_getfvreadonly L 94 Resource Retrieval and Update SSpe QetEVSPeC cessere resce 95 SSPE Cloe ii p i 77 sspec_getpreformfunction ee 99 Sspec delete 2 cascaceiaen reins 78 sspec setformepilog 0 0 eee 119 SSPOC_TOK GI nies ezenti start erett 104 sspec_setformfunction mn 120 SSPE OPEN sie gie eu po 106 sspec_setformprolog m nn 120 sspec_readvariable s mn 113 sspec setformtitle sse 121 Sspe rmdir sensit 117 sspec setfvcheck se eeneneeni 121 SSpec SEEK milsa isa tenement mentri 118 SSPEC_SetfVAESC ve eneennenni 122 SSPeG Stat iii sie b 133 sspec_setfventrytype vm sse eeseneeni 122 sspec tell ccassssesevassessteaecpesaisevsnsssetessyeoses 135 sspec setfvfloatrange m mn 123 SSPE WIIE irinenn eE 136 SSpe Setivlen sc cissesscsectisnsnieestessbeiscedeeens 124 Server Resource Management SSPeC_SetfVNAME ms eeeneenznnzza 124 http addfile osise 190 sspec setfvoptlist L 125 hitp delfile s s ssiiieizsiesieteeme i est iross 195 sspec setfvrange sse eeenennenznnzna 126 shtml addfunction sse eeennenenzzn 245 sspec setfvreado
391. rectto HttpState state char url DESCRIPTION This utility function may be called in a CGI function to redirect the user to another page It sends a user to the URL stored in url You should immediately issue a return 0 after calling this function The CGI is considered finished when you call this and will be in an undefined state The HTTP samples work correctly with cgi redirectto because they use macro con stants to define the URL parameter If you manipulate the url string please be aware of the fol lowing issues The library function sets a pointer to the 2nd parameter url The calling routine is respon sible for ensuring that the location represented by the pointer remains valid after the call This is because the URL string will not be processed until after the CGI function is fin ished If the application has MAX_TCP SOCKET BUFFERS and HTTP MAXSERVERS set to more than one it is possible that the CGI function will be called successively with different server states serving different client requests In these circumstances it is necessary to ensure that the pointer to the url is valid for each of the server states After the cgi function has called cgi redirecto and returns 0 the http_handler then causes the server response to be sent to the browser The information is sent as fol lows 1 HTTP header response containing the redirection information response code 302 2 A human readable redirection html pag
392. rial port esej ta Open each serial port serial CSpeia il 7 The above function initializes the Ethernet to serial state machine first bv setting the variable that is used to travel around the state machine e2s_state i state then by setting the function pointers used to access the serial ports For example serAopen is a function defined in RS232 1ib that opens serial port A The switch statement has cases for serial ports B C and D that are not shown here They are function ally the same as the above code for serial port A If the chip on the target board is a Rabbit 3000 there are cases for serial ports E and F as well The default case is an error condition that will cause a run time error if encountered The last statement in the for loop is a call to serial open This function which was described ear lier makes calls to the appropriate serial port functions using the function pointers that were just initial ized 282 rabbit com RabbitWeb void e2s tick void auto int i auto int len auto tcp Socket sock for i 0 i lt sizeof pores contig i sock amp e2s statelil sock switch e2s state i state Calsic eras meatal tep listen sock serial portslil tep port 0 0 NULL 0 e25 Startel state 826 DLIEHHN break case E2S LISTEN if sock waiting sock The socket is no longer waiting if sock_established sock The socket is established e2s state i st
393. rm input The user function must have the following prototype void userfunction int form The function may not use the form parameter but it is useful if the same user function is used for multiple forms PARAMETERS form spec index of the form fptr Pointer to user function to be called just before form generation RETURN VALUE 0 Success 1 Failure SEE ALSO sspec_getpreformfunction TCP IP Manual Vol 2 rabbit com 129 sspec setrealm int sspec setrealm int sspec char realm DESCRIPTION Sets the realm field of a ServerSpec structure for HTTP authentication purposes Setting this field enables authentication for the given spec entry Authentication can be turned off again by passing as the realm parameter to this function Note realm must NOT point to an auto variable since only the pointer is stored The string is NOT copied PARAMETERS sspec spec index this must refer to the RAM resource table realm Name of the realm RETURN VALUE 0 Success 1 Failure SEE ALSO sspec getrealm 130 rabbit com Server Utilitv Librarv sspec setsavedata int sspec setsavedata char data unsigned long len void fptr DESCRIPTION Sets user supplied data that will be saved in addition to the spec and user authentication tables when sspec save is called PARAMETERS data Pointer to location of user supplied data len Length of the user supplied data in bytes fptr Pointer to a fu
394. rmation see Section 5 2 2 1 e The auth parameter is a comma separated list of acceptable authentication methods The possible choices are basic digest and ssl For more information see Section 5 2 3 e The groups parameter is a comma separated list of user groups that are allowed access to the web variable or array or structure For more information see Section 5 2 3 One or more of the optional parts can be used in a web statement web groups This directive defines a web group For more information see Section 5 2 3 web update This directive identifies a user defined function to call in response to a variable update For more informa tion see Section 5 2 4 290 rabbit com RabbitWeb 5 5 4 ZHTML Grammar Terminals are in bold indicate optional parts and seps indicates an OR in the statement zhtml tag gt lt z statement gt statement gt print function printf function varname function print_opt function print_select function if statement for loop print function gt print variable variable gt registered variable loop variable registered variable is an array structure or variable that is registered with the web server loop variable gt A Z loop variable is a one letter variable A Z defined in the for loop and can be used as the index for an array printf function gt printf printf specifier variable The printf specifier is like a
395. ro dmir initialize web server http_set_path index zhtml tcp reserveport 80 sspec addrule admin Admin admin admin SERVER ANY SERVER AUTH BASIC NULL userid sauth_adduser harpo swordfish SERVER_ANY sauth setusermask userid admin NULL while 1 http handler call the http server In main after the local variable userid is declared there is run time initialization of the variables that will be visible on the HTML page Then the stack and the web server are initialized with calls to sock init andhttp init respectively TCP IP Manual Vol 2 rabbit com 253 The function http init sets the root directory to and sets the default file name to index html The callto http set path can be used to change these defaults We only want to change the default filename so in the function call we keep the default root directory by passing as the first parameter and change the default filename by passing index zhtml as the second parameter The reason we want to do this is for when the browser specifies a directory instead of a proper resource name we want to default to using index zhtml in that directory if it exists If we don t use the set path func tion the default is index html which won t work for this sample because the file index html doesn t exist The call to sspec addrule configures the web server to give write and read acce
396. rocessor or something else The master also needs a driver for its end of the slave port connection An example of the software needed on the master is given in MASTER SERIAL LIB The software on the master controller is of course specific to the task at hand In the example driver provided most of the work is done by the slave making minimal changes necessary to the code on the master 14 5 2 4 Custom I O Methods To define a custom I O method you must add a structure of type ConsoleIO to console io This structure holds the common handler functions for the I O method The tick function may have a NULL pointer but the rest of the function pointers must be valid pointers to functions 14 5 3 Multiple I O Streams Each I O method has its own state machine in Zconsole That means that each I O method is independent of the others and they can all be used simultaneously This imposes the important restriction that all com mand handlers be able to run simultaneously on different I O streams or support proper locking for func tions that cannot be performed simultaneously TCP IP Manual Vol 2 rabbit com 473 14 6 Zconsole Execution Normally Zconsole will communicate over a serial link The physical connection will differ slightly from board to board Basically you will need a 3 wire GND RXD TXD serial cable Several initialization steps must be taken at the beginning of an application program to execute the console 14 6 1 File
397. rrent temperature in amp deg F sspec setfvlen form var 5 TCP IP Manual Vol 2 rabbit com 161 Since the value of the second variable should not be modifiable via the HTML form by default variables are modifiable the following line is necessary and makes the given form variable read only when the third parameter is 1 The variable will be displayed in the form table but can not be modified within the form sspec setfivreadonly form var 1 These lines set up the low temperature variable It is set up in much the same way as the high temperature variable var Sepec_acklvamialole cemplo eemlo TATIE sel SERVER HTTP var sspec addfv form var sspec setfvname form var Low Temp sspec setfvdesc form var Minimum in temperature range 50 80 amp deg F sspec setfvlen form var 5 sspec setfvrange form var 50 80 This code begins setting up the string variable that specifies what to do in case of air conditioning failure Note that the variable is of tvpe PTR16 and that the address of the variable is not given to sspec addvariable since the variable fail already represents an address var pepee acdveariable Vrailure tail PIRI as SERVER_HTTP var Sspec_ackliny torm var 5 sspeo setcivaene comm wes Vrailure Agent p sspec setfvdesc form var Action to take in case of air conditioning failure sspec setfvlen form var 20 This line associates an
398. rs can be added to or removed from a user group at run time The groups are defined at compile time in this manner web groups admin users This statement creates the two groups admin and users The symbols admin and users are added to the global C namespace These represent unsigned 16 bit numbers Each group has one of the 16 bits set to 1 so that the groups can be ORed together when multiple groups need to be referenced Note that this limits the number of groups to 16 TCP IP Manual Vol 2 rabbit com 263 The web server does not directly know that admin is for administrative users and users is for everyone else This distinction is made by how the programmer assigns protection to server resources For example web foo foo gt 0 groups users ro admin limits access to the variable foo This variable is read only for those in the users group rw can be specified to mean read write for the admin group but this is the default so it is not necessary The group all is a valid group which will give access to a variable to all users regardless of group affiliation By default all groups have access to all variables The groups is used to limit access Consider the line web foo foo gt 0 groups users ro This line causes the admin group to have no access to the variable foo In other words if there is a groups clause then any group that is not mentioned
399. rs is 15 FTP MAX DIRLEN The default is 64 which is the maximum string length of a directory name FTP MAX FNLEN The default is 16 which is the maximum string length of a file name FTP MAX NAMELEN The default is 16 which is the maximum string length of usernames and passwords FTP MAXLINE The default is 256 which is both the maximum command line length and data chunk size that can be passed between the FTP data transfer socket and the data handler if anv defined FTP TIMEOUT The default is 16 which is the number of seconds that pass before a time out occurs TCP IP Manual Vol 2 rabbit com 313 7 2 API Functions ftp client setup int ftp client setup long host int port char username char password int mode char filename char dir char buffer int length DESCRIPTION Sets up a FTP transfer It is called first then ftp client tick is called until it returns non zero Failure can occur if the host address is zero if length is negative or if the internal control socket to the FTP server cannot be opened e g because of lack of socket buffers PARAMETERS host Host IP address of FTP server port Port of FTP server 0 for default username Username of account on FTP server password Password of account on FTP server mode Mode of transfer FTP MODE UPLOAD or FTP MODE DOWNLOAD You may also OR in the value FTP_MODE_PASSIVE to use passive mode transfer important if you are behind a firewall filenam
400. rsion in this case d because the variable is an integer When the browser gets the results returned by the HTTP server it will see lt HTML gt lt HEAD gt lt TITLE gt Web Variables lt TITLE gt lt HEAD gt lt BODY gt lt H1 gt Web Variables lt H1 gt lt P gt The current value of io state is 50 lt P gt lt BODY gt lt HTML gt Where the 50 represents the current variable value of course it may be any decimal value that an inte ger variable could take 32768 through 32767 This is still a trivial example but it is infinitely more real world than the toy example We have introduced the concept of dynamic content which is required for embedded type applications One thing that has been glossed over is how and even whether the variable can be updated from the browser rather than just within the application Yes all web variables may be updated via the browser This requires use of HTML forms which is a subject covered in Chapter 4 and Chapter 5 We will not go over this again here however the possibility of remote updating introduces us to the topic of the next section access control TCP IP Manual Vol 2 rabbit com 15 2 6 Adding Access Controls If your application allows updating of the controller state via remote access and the network connection allows access from locations that are not always under control then it is important to add some access con trols or security The most common way
401. rt len sock fastread sock e2s buffer E2S BUFFER SIZE iz len lt e Error sock_abort sock e26 StaACe State B26 TNI iE len gt 0 Write the read data to the serial port Note that for simplicity this code will drop bytes if more data has been read from the TCP socket than can be written to the serial port e29 Sicaice lil weLcee ers buiieex len else No data read do nothing Read from the serial port and write to the TCP socket len e2s statelil read e2s buffer E2S BUFFER SIZE unsigned long 0 it lena gt len sock fastwrite sock e2s buffer len iz en lt 0 Exror sock abort sock e25 State state 828 INIT The E2S PROCESS state checks to make sure the user did not abort the connection since the last time the tick function was called If there was no abort an attempt is made to read data from the socket buffer If an error is returned from sock fastwrite the connection is aborted and we go back to the init state the next time the tick function is called If data was read it is written to the serial port If no data was read then nothing happens 284 rabbit com RabbitWeb Next an attempt is made to read data from the serial port If data was read it is then written out to the TCP socket If the data read from the serial port was not written successfully to the TCP socket the connection is aborted and we go back to the init state the n
402. rt it into your main program so that the HTTP server can present it to the user This can be done using ximport or you can write it directly to the filesystem although initially at least this presents a chicken and egg type problem since you might not have established an upload procedure in the first place Step 6 Writing a CGI Function The CGI function is responsible for processing the form submission data as it comes in from the client browser In addition it generally needs to write some sort of response back to the client indicating whether or not the submission was acceptable If you start reading the following and start feeling somewhat overwhelmed please be aware that there is a default CGI function in the HTTP library that is very useful The default CGI called http defaultCGI automatically saves uploaded files into the filesystem If that is all you need to do then you do not need to fully comprehend this section on first reading Note that all of this section is describing new style CGIs Old style CGIs are covered in Section 4 5 3 CGI Syntax All CGI functions are C functions with the following prototype int my CGI HttpState s The HttpState parameter is a pointer to the internal state variables of the HTTP server instance that is handling the current request You can have one or more server instances If there is more than one the same CGI may be invoked at the same time for more than one client if both hap
403. ructure All FTP server instances share the same list of handlers The FTPhandlers structure is defined as typedef struct int open char name int options int uid int cwd int read int fd char buf long offset int len int write int fd char buf long offset int len int close int fd long getfilesize int fd int dirlist int item char line int listing int uid int cwd int cd int cwd char dir int uid int pwd int cwd char buf long mdtm int fd int delete char name int uid int cwd FTPhandlers If you always provide all your own handlers then you can define FTP_NODEFAULTHANDLER to eliminate the code for the default handlers The handlers must be written to the specification described in Section 8 2 2 To use a default handler leave the field NULL If you pass a NULL handlers pointer then the all default handlers will be used The defaults access the server spec list which is set up using the zserver functions sspec addxmemfile sauth adduser etc PARAMETERS handlers NULL means use default internal file handlers Otherwise you must supply a struct of pointers to the various file handlers open read write close get filesize list To not override a particular handler leave it NULL in the structure LIBRARY FTP SERVER LIB SEE ALSO tep tiek 336 rabbit com FTP Server ftp load filenames int ftp load filenames void
404. run time unlike the other tables that may at least partially be initialized at compile time 3 Main loop The final code in the main function continuously calls http handler and possi bly other functions This is mandatory since it allows the HTTP server to process requests from the net work Other functions may be specific to your application For example you may need to poll an I O device in order to obtain best performance 4 Application specifics and I O This is really your part of the application or if you like the back end to the HTTP server There are a number of ways that your application can communicate with the HTTP server These are not all shown on the diagram since it would add needless complexity Your applica tion can directly call functions in the HTTP server in the resource manager Zserver in TCP IP and TCP IP Manual Vol 2 rabbit com 7 just about anywhere else One very clean and powerful interface is provided via web variables pro vided by RabbitWeb software which was introduced in Dynamic C 8 50 5 CGI functions CGI stands for Common Gateway Interface however this acronym has a more specific use in Dynamic C it refers to a C function that is called by the HTTP server to generate some dynamic content for the browser This is the only truly optional block Many applications can be written without resorting to CGI functions however there are some cases where the power and flexibili
405. rver after the CGI previously returned CGI MORE LIBRARY HTTP LIB SEE ALSO functions mentioned above http_defaultCGI TCP IP Manual Vol 2 rabbit com 199 http getCond int http getCond HttpState state int idx DESCRIPTION Return the current HTTP condition state variable aka cond variable There are HTTP MAX COND of these integer state variables thus idx must be between 0 and HTTP MAX COND I inclusive Use of cond variables is entirely up to the application however they are initialized by the HTTP server under certain conditions By default they are set to zero at the start of each request from the client If the client request includes URL GET type parameters of the form http host re source html A 1 amp B 2 amp C 3 etc then cond state 0 is set to the value for A cond state 1 is set to the value for B etc The values must be integers which are coerced into 16 bit signed integers NOTE This is implemented as a macro PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function idx Index of cond variable 0 HTTP_ MAX COND 1 Validity is not checked RETURN VALUE Value of cond variable idx LIBRARY HTTP LIB SEE ALSO http_getAction http_setCond 200 rabbit com HTTP Server http getContentDisposition char http getContentDisposition HttpState state DESCRIPTION Return the current disposition of the data which is being provided by the client Th
406. s Pointer to mask of user groups who have write access Pointer to servers allowed to access this resource Pointer to required authentication method Pointer to pointer to MIME table entry lt 0 Failure For example an invalid sspec handle SEE ALSO sspec setpermissions sspec checkpermissions sspec access 98 rabbit com Server Utilitv Librarv sspec getpreformfunction void sspec getpreformfunction int form DESCRIPTION Gets the user function that will be called just before HTML form generation This function is use ful mainly for custom form generation functions PARAMETERS form spec index of the form RETURN VALUE NULL No user function NULL Pointer to user function SEE ALSO sspec setpreformfunction sspec setformfunction sspec getrealm char sspec getrealm int sspec DESCRIPTION Returns the realm of the spec entrv represented bv sspec PARAMETERS sspec spec index RETURN VALUE NULI Failure INULL Success pointer to the realm string SEE ALSO sspec setrealm TCP IP Manual Vol 2 rabbit com sspec getservermask int sspec getservermask int sspec word servermask DESCRIPTION Gets the server mask for the given spec entry This is the bitmask passed in when the entry is cre ated with the sspec_add functions This function only works for RAM and flash table entries PARAMETERS sspec spec index of the variable servermask Address in which the serv
407. s array index of the ServerAuth structure for authenticated user SEE ALSO sauth_adduser TCP IP Manual Vol 2 rabbit com 47 sauth getpassword sauth getpassword int userid DESCRIPTION Get the password for a user PARAMETER userid user index RETURN VALUE NULL password string NULL Failure SEE ALSO sauth_setpassword sauth getserver int sauth getserver int sauth DESCRIPTION Returns whether or not a user is visible to particular server s PARAMETER sauth user index RETURN VALUE 0 This user is visible to all servers 30 Visible to select servers One bit is set for each server that knows about this user 1 Failure for example sauth is an invalid index into the user table SEE ALSO sauth_setserver 48 rabbit com Server Utility Library sauth getuserid int sauth getuserid char username word server DESCRIPTION Gets the user index for a user PARAMETERS username User s name If this name is not found then the list is re scanned looking for an entry with an empty user name and a password that matches username The second pass is only done for servers that allow password only matching Such servers must be specified by defining a symbol SERVER PASSWORD ONLY to be a bitmask of such servers server Server s for which we are looking up Use SERVER ANY if not concerned with the server mask RETURN VALUE 20 Success index of user in the user table 1 Fail
408. s a copy of the file specified in the pathname argument 150 226 from the server to the client 425 550 l TM ee 213 250 SIZE Returns the size of the specified file 450 550 Stores a file from the client onto the server The file will be 150 226 250 STOR overwritten if it already exists at the specified pathname or it will 425 450 be created if it does not exist 452 550 STRU Confirms the supported structure of a file Only file structure is 200 504 supported a continuous stream of data bytes SYST Sends the string RABBIT2000 215 TYPE Confirms the transfer type The types IMAGE binary ASCH and 200 504 Local with 8 bit bytes are all supported and are treated the same USER User name to use for authentication 331 530 TCP IP Manual Vol 2 rabbit com 343 8 7 Reply Codes to FTP Commands The FTP server replies to all of the commands that it receives The reply consists of a 3 digit number fol lowed by a space and then a text string explaining the reply All reply codes sent from the FTP server are listed here Reply Code Reply Text 150 File status okay about to open data connection 200 Command okay 202 Command not implemented superfluous at this site 211 System status or system help reply 213 File status 214 Help message On how to use the server or the meaning of a particular non standard command This reply is useful only to the human
409. s the result This makes root dir invisible to the end user The leading slash is included but the trailing slash is omitted from the result unless the result is just For example if context gt rootdir points to A and context gt cwd contains A ftpfiles ftpfiles will be the result returned in buf PARAMETERS context Server context structure Two fields in this are of interest root dir points to a virtual root directory for this server and cwd is a character array con taining the CWD buf Points to buffer that is filled with resulting string This buffer is assumed to be dimensioned at least SSPEC_MAXNAME chars long and it will be null terminated on return RETURN VALUE The buf parameter is returned SEE ALSO sspec cd TCP IP Manual Vol 2 rabbit com 109 sspec read int sspec read int sspec char buf int len DESCRIPTION Read the next byte s from the given file resource PARAMETERS sspec Open file handle This must be a handle that was returned by sspec open buf Buffer into which data is copied len Length of the above buffer If 1en is zero then the return value will be the minimum number of characters that could be read at the current position which is usually at least 1 except at EOF 0 Thus this function can be used to test for end of file EOF that is if sspec read sspec NULL 0 0 is TRUE then EOF has been reached in the file identified by sspec
410. sages This address will be added to the outgoing e mail and should be valid in case the e mail needs to be returned A command that uses this function takes one parameter the return address con set mail server This functions identifies the SMTP server to use A command that uses this function takes one parameter the IP address of the SMTP server con set nameserverl This function changes the name server for the board A command that uses this function takes one parame ter the IP address of the new name server in dotted quad notation e g 192 168 1 1 con set netmask This function changes the netmask of the board A command that uses this function takes one parameter the new netmask in dotted quad notation e g 255 255 255 0 con set tcpip debug This function is intended to aid in development and debugging A command that uses this function takes one parameter the numerical level of debugging messages The higher the number the more verbose the TCP IP debugging messages will be con show This function displays the current configuration of the board IP address netmask and gateway If the developer s application has configuration options she would like to show other than the IP address net mask and gateway she will probably want to implement her own version of the show command The new show command can be modelled after con_show in ZConsole lib A command that uses this function takes no parameters con_show
411. scribed in Section 5 2 1 A variable must begin with a character to access its last submitted value This value may or may not have been committed The last committed value is accessible using as in lt z print foo gt TCP IP Manual Vol 2 rabbit com 267 Why is there a distinction between the last submitted value and the last committed one In other words does it matter in the HTML code whether the submission value is valid It can See Section 5 3 5 for more information To specify a printf style conversion specifier the printf function can be used but with the limitation that it will only accept one variable as an argument lt z printf sld Slong foo gt Note that the print function does not generate the code for the form widget itself this is done with the INPUT tag an HTML tag that generates a specific form element Here is an example of using the print command to display a value in a form widget lt INPUT TYPE text NAME foo SIZE 10 VALUE lt z print foo gt gt For the value to be updateable the NAME field must be the name of the variable Otherwise when the form is submitted the web server will not know where to apply the new value This is not true of arrays When referencing arrays the name must differ somewhat from the C name because the and symbols are not valid in the NAME parameter of the INPUT tag due to limitations in HTTP The varname fu
412. sed to create the MIB are described in Section 12 4 A pointer to the parameter structure snmp parms was passed to all functions and also set to the return value This is the recommended way of doing the MIB tree setup since if any step fails it will return NULL Passing the NULL on to subsequent functions is harmless and avoids the need to do error checking after each call Only at the end of sequence should p be tested for NULL Notice that the root of the MIB tree is set to SNMP ENTERPRISE oemExperiments demos rabbitsemiDemoSNMP1 using the call p snmp append parse stem p 3 1 1 TCP IP Manual Vol 2 rabbit com 383 The entire MIB tree can be rooted at a different point simply by changing this one call But wait you may well ask where did the oemExperiments demos etc come from Before I answer that let s look at a tree diagram of the MIB that was created in the previous code fragment The initial OID stem is set to 43 6 1 4 1 SNMP_ ENTERPRISE by the call to snmp init parms The first two levels in the tree iso org 1 3 are condensed to 43 to save transmitting an extra byte The first 1 in 1 3 6 1 4 1 is multiplied by 40 then added to the second number 3 resulting in 1 40 3 43 or Ox2b This initial OID corresponds to the Rabbit Semiconductor node rabbitsemi on the enterprise subtree Leaf nodes are created using the snmp add macros After the leaf node for rw_tt is creat
413. sed with other API functions that need the context structure For example sspec open MyFile http getcontext servno O READ 0 will open MyFile for reading for the server instance identified by servno 36 rabbit com Server Utility Library 3 1 7 SSpecStat Structure This structure holds status information about a file resource It is filled in by the function sspec stat The fields of SSpecStat are flags A 16 bit mask that passes information about the file resource The flags field can be anv number of the following SSPEC ATTR MDTM have modification date time SSPEC ATTR LENGTH have current length SSPEC ATTR WRITE file is writable SSPEC ATTR EXEC file is executable SSPEC ATTR HIDDEN Hidden attribute bit SSPEC ATTR SVSTEM Svstem attribute bit SSPEC ATTR ARCHIVE Archive attribute bit SSPEC ATTR DIR directorv name SSPEC ATTR COMPRESSED stored in compressed format SSPEC_ATTR_MAXLENGTH have maximum length SSPEC_ATTR_SEEKABLE resource is randomly accessible SSPEC ATTR EXTENSIBLE File may be expanded at end mdtm Modification date time SEC_TIMER format this field is only valid if SSPEC ATTR MDTM is set length The current file size this field is only valid if SSPEC ATTR LENGTH is set maxlength The maximum allowable file size this field is only valid if SSPEC ATTR MAXLENGTH is set perm Pointer to ServerPermissions struct This structure is described above 3 1 8 sspec fatinfo
414. server and goes back to the initial state Hence a CGI function may want to reset this timeout if it needs more processing time but care should be taken to make sure that the server is not locked up forever This can be achieved like this state gt main_timeout set_ timeout HTTP TIMEOUT HTTP TIMEOUT is the number of seconds until the web server will time out It is 16 seconds by default buffer A buffer that the developer can use to put data to be transmitted over the socket It is of size HTTP MAXBUFFER defaults to 256 bytes Note It is not recommended to directly access buffer or p below Use the new style CGI functions and the http write http getData andhttp getDataLength functions instead These create a much easier to use and safer method of reading writing data to the client p Pointer into the buffer given above See above note method This should be treated as read only It holds the method by which the web request was submitted The value is either HTTP METHOD GET or HTTP METHOD POST for the GET and POST request methods respec tively Use http getHTTPMethod for new code url This should be treated as read only It holds the URL by which the current web request was submitted If there is GET style form information then that information will follow the first NULL byte in the url array The form infor mation will itself be NULL terminated If the information in the url array is trunc
415. set is the byte number relative to the first byte of the entire FTP stream This is useful for data handler functions that do not wish to keep track of the current state of the data source dhnd_data is the pointer that was passed to ftp_data_handler flags contains an indicator of the current operation e FTPDH_IN data is to be stored on this host obtained from an FTP download e FTPDH OUT data is to be filled with the next data to upload to the FTP server e FTPDH END data and len are irrelevant this marks the end of data and gives the function an opportunity to e g close the file Called after either in or out processing e FTPDH ABORT end of data error encountered during FTP operation Similar to END ex cept the transfer did not complete Can use this to e g delete a partially written file The return value from this function depends on the in out flag For FTPDH_IN the function should return 1 en if the data was processed successfully and download should continue 1 if an error has occurred and the transfer should be aborted For FTPDH_OUT the function should re turn the actual number of bytes placed in the data buffer or 1 to abort If zero is returned then the upload is terminated normally For FTPDH_ END the return code should be zero for success or 1 for error If an error is flagged then this is used as the return code for ftp client tick For FTPDH ABORT the return code is ignored 318 rabbit com FTP Clie
416. show the write permission for writable files NOTE The user will need to override both the write and close default file han dlers to provide full support for writing a file SSPEC NO STATIC This macro must be defined in any FTP server application compiled with Dynamic C 8 50 or later TCP IP Manual Vol 2 rabbit com 323 8 2 File Handlers Default file handlers are provided The defaults access the server spec list which is set up using sspec addxmemfile sauth adduser etc The default file handlers are used when NULL is passed to the initialization function ftp init 8 2 1 Replacing the Default Handlers The FTPhandlers structure contains function pointers to the file handlers This structure may be passed to ftp init to selectively replace the default file handlers You may provide a NULL pointer for han dlers that you do not wish to override If you have defined F TP EXTENSIONS then there are an addi tional two function pointers that should be initialized typedef struct int open int read int write int close long getfile int dirlist int cd int pwd ifdef FTP EXTENSIONS long mdtm int delete tendif FTPhandlers size Starting with Dynamic C 7 30 all FTP server instances share the same set of data handlers Before this release there was a separate copy of the handler pointers for each instance of the server This change do
417. sources on the Web and in any major book store The Dynamic C implementation of TCP IP comprises several libraries The main library is DCRTCP LIB As of Dynamic C 7 05 this library is a light wrapper around DNS LIB IP LIB NET LIB TCP LIB and UDP LIB These libraries implement DNS Domain Name Server IP TCP and UDP User Datagram Protocol This along with the libraries ARP LIB ICMP LIB IGMP LIB and PPP LIB are the transport and network layers of the TCP IP protocol stack The Dynamic C libraries e BOOTP LIB e FTP SERVER LIB e FTP CLIENT LIB e HTTP LIB e HTTP CLIENT LIB e POP3 LIB e SMNP LIB e SMTP LIB e TFTP LIB e VSERIAL LIB implement application laver protocols Except for BOOTP which is described in the Dvnamic C TCP IP User s Manual Vol 1 these protocols are described here in the following chapters All user callable functions are listed and described in their appropriate chapter Example programs throughout both volumes of the manual illustrate the use of all the different protocols The sample code also provides templates for creating servers and clients of various types To address embedded system design needs additional functionality has been included in Dynamic C s implementation of TCP IP There are step by step instructions on how to create HTML forms allowing remote access and manipulation of information There is also a serial based console that can be used with TCP IP to open up legacy
418. specific permissions independent of the rule table itself Resources in a filesystem may be very numerous hence a simple one to one table would waste a lot of storage To solve this problem the rule table uses a name prefix matching algorithm Using this technique entire directories of resources need only have one rule table entry pro vided that all resources therein use the same permissions 16 rabbit com Web Enabling Your Application The following diagram shows the application components when access control is added Figure 2 4 Minimal components of a web enabled application with dynamic content and access control Application Compile Time Run Time Main Application CGI Initialization Initialization Loop Specifics Q Functions web Variables Saez Requests Resources Content Metadata Zserver TCP IP Resource Manager Static Dynamic Resource Resource Table Table The main difference between this and the previous diagram is that the Rule Table and User Table blocks have been activated TCP IP Manual Vol 2 rabbit com 17 The sample program is now expanded to add access control As before the changes are in boldface define TCPCONFIG 1 define USE RABBITWEB 1 define USE HTTP BASIC AUTHENTICATION 1 use dertcp lib use http lib web groups monitor group admin group ximport my_app zhtml mv app zhtml SSPEC MIMETABLE START SSPEC MIME FUNC htmi text html zhtml_handle
419. ss 62 http get HTTPMethod str 209 sspec addrootfile ss 64 http getHTTPVersion 0 210 sspec addvariable ee eeeeeeeeeeees 68 http get HTTPVersion str 211 sspec addxmemfile nn 69 http getRemainingLength 212 sspec addxmemvar Lumen 70 http getSocket en 213 SSpe AJJASSPEC os cp ccceassepesssssssenssctostoenesenes 71 http getState esse seeserereees 214 sspec_resizerootfile sen 116 http getTransferEncoding 215 Dvnamic Rule Table hitp etU RL sisien aeizi entanti tenerezza 216 sspec_addrule oo eee 65 http_getUserState 0 mn 217 sspec remOVerule l eenesnnnena 114 http setCond nee nn 226 E mail http SetState 32i ssessezrezoenzizznzzenzenzenzioteeztas 229 pop3 getmail wn 368 http sKIpCGL sessi 230 POPS AMILT 367 http sock bvtesreadv nn 231 POPS TICK l sess eons 369 http sock fastread s mn 232 smtp mailtiek 0 0 eee enn 359 http sock fastwrite men 233 smtp sendmail cee eeceeseeeeeceseeceeeeeees 360 http sock gets Lumen 234 smtp sendmailxmem semen 361 http sock mode en 235 SMP Status cesscscsvesecseeesscessrsesseenoesecnserenses 364 http sock readable oe 236 File Svstem Specifics http sock tbleft L 238 sspec automMOUNt LL 72 http sock writable mn 237 sspec fatregister seen 82 http sock Write sse eennnnenn 238 sspec fatregistered ss 83 http sock xfastread
420. ss to the directory admin to any members of the admin group and to require basic authentication for any access to this directory The call to sauth_adduser adds the user named harpo with a password of swordfish to the list of users kept by the server The next function call sauth setusermask adds the user named harpo to the user group named admin This sequence of calls allows you to restrict access to the file humidity admin zhtmi Only members of the user group admin which in this case is the one user named harpo can get the server to display a file resource that starts with admin Recall that the file humidity admin zhtml was copied to memory by the ximport directive and given the label admin_zhtml The file was then added to the static resource table and given the name admin index zhtmli This is the name by which the server recognizes the file and the name by which access to it is restricted The web server is driven by the repeated call to http handler The second part of our example requires additions to the HTML page that is served by our web server The use of the new scripting language will be explained as it is encountered in the sample pages Regular HTML code will not be explained as it is assumed the reader has a working knowledge of it If that is not the case refer to one of the numerous sources that exist on the web etc for information on HTML 5 1 2 HTML Pages for Humidity Detector This sample requires two HTM
421. ssword J Save this password in your password list Cancel 1 In this example we also choose to use a rule table This is not strictly necessary since no filesystem is in use The alternative is to use a different form of initializing the static resource table namely by using the SSPEC RESOURCE P XMEMFILE macro which allows permission information to be stored in the static table instead of in the rule table See Section 3 2 5 3 Static Resource Table TCP IP Manual Vol 2 rabbit com 19 The third and fourth parameters indicate the group s that have read and write access to the resource Both groups are allowed read access and none write 0 Note that the resource in this case is the index html page not the variables which may or may not be displayed on it Since this web page actually a ZHTML script is in program flash it is obviously not modifiable The SERVER_HTTP parameter indicates that this resource is only visible from the HTTP server This would be more relevant is there was another server such as FTP running concurrently SERVER_AUTH_ BASIC indicates that the server should use basic authentication when the browser calls for this resource Note that Zserver does not enforce the method of authentication it only stores the recommended method in the rule table Any enforcement of authentication requires the co operation of the server since each different type of server may have widely different means of impleme
422. st recent modification date unknown returned for unrecognized method Other strings may be returned in the future SEE ALSO http_getHTTPMethod http_getAction TCP IP Manual Vol 2 rabbit com 209 http getHTTPVersion char http getHTTPVersion HttpState state DESCRIPTION Return the HTTP version number of the current request protocol The CGI might need to look at this in order to generate the correct response headers NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE One of the following codes HTTP VER 09 version 0 9 HTTP VER 10 version 1 0 HTTP VER 1l1 version 1 1 Other codes may be returned in the future LIBRARY HTTP LIB SEE ALSO http_getAction 210 rabbit com HTTP Server http getHTTPVersion str char http getHTTPVersion str HttpState state DESCRIPTION Return the HTTP version number of the current request protocol The CGI might need to look at this in order to generate the correct response headers PARAMETERS state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE One of the following strings 0 9 version 0 9 1 0 version 1 0 1 1 version 1 1 unknown unknown version Other strings may be returned in the future LIBRARY HTTP LIB SEE ALSO http_getHTTPVersion http_getAction TCP IP Manual
423. t for http handler 4 rabbit com Web Enabling Your Application The second file named he 1 lowww html is coded as follows lt HTML gt lt HEAD gt lt TITLE gt Hello WWW lt TITLE gt lt HEAD gt lt BODY gt lt H1 gt Hello WWW lt H1 gt lt BODY gt lt HTML gt That s all there is to it However there is actually a lot of activity going on beneath the covers For a start the use dcrtcp lib directive and the TCPCONFIG macro definition bring in the TCP IP networking suite and configure it Unless you have a private test network you probably have to modify the default setting how to do that is beyond the scope of this chapter it is described in volume 1 of the manual The use http lib statement is required in order to bring in the web server The next lines down to the start of the main function are setting up tables that are consulted by the HTTP server and other libraries in order to do the right thing Finally the main function calls the necessary runtime initialization of the network and the HTTP server It then calls the HTTP server in an endless loop which drives the entire system into motion The html file is ASCII text in HTML syntax which is transferred back to the browser when it is requested Apart from the server adding some header lines the html file is transferred verbatim This markup is merely telling the browser to display Hello WWW as a Ist level heading i e
424. t gt lt FORM gt lt BR gt lt FORM ACTION upload cgi METHOD POST enctvpe multipart form data gt lt TABLE BORDER 0 CELLSPACING 2 CELLPADDING 1 gt lt TR gt lt TD ALIGN RIGHT gt File to upload lt BR gt to A new htm lt TD gt lt TD gt lt INPUT TYPE FILE NAME A new htm SIZE 50 gt lt TD gt lt TR gt lt TABLE gt lt INPUT TYPE SUBMIT VALUE Upload gt lt FORM gt lt BODY gt lt HTML gt 24 rabbit com Web Enabling Your Application The text in boldface is the description of a new form which when displayed by the browser allows a file to be uploaded to a FAT filesystem The FORM tag includes the METHOD attribute which is the same as that of the first form The Web V ari ables ACTION attribute has changed to specify the The current value of io_state is 50 ables Aozilla Build ID 2001090111 Eile Edit View Search Go Bookmarks Tasks Help CGI function that was Enter anew value if you dare added to the server s static resource table this so Submit Reset is the default CGI pro vided by the server File to upload When ie Upload but to JA fnew ht e ton is clicked Upload http_defaultcGI will be called by the server A new attribute is included that specifies the MIME type used to submit the form to the server enctype multipart form data This is the MIME type required when the returned document includes files Note that the two forms are being submitte
425. t Useful The HTTP library provided with Dynamic C allows the association of C functions with web page URLs When the user via their web browser retrieves a specified resource the C function may be called from the HTTP server Such a function is called a Common Gateway Interface CGI function and it is responsible for generating a response to the user s request The advantage of using a CGI is that it can generate web page content on the fly and cause the browser to display or do anything that it is capable of In addition the CGI is able to read data that was sent by the browser Previous to this release of Dynamic C the CGI was limited to handling relatively small amounts of data sent from the browser This is satisfactory for processing simple forms but does not allow large data sets to be uploaded This release of Dynamic C supports upload of one or more files from the browser The files can be of unlimited size In conjunction with the latest Zserver resource manager enhancements introduced in Dynamic C 8 50 the uploaded files may be stored in the FS2 or FAT file systems or even processed dynamically The new CGI file upload facility enables a range of convenient firmware features Possibilities include Remote firmware updates Web page content updates i e publishing e Executable interpreter scripts Remote hardware updates if using an FPGA or other configurable logic device e Firmware configurati
426. t at this position Note that offsets that are not in the file are clamped to the start or end of the file as appropriate Clamp is terminology meaning that a value past the end is set to the end or a value before the beginning is set to the beginning For example if a file is actually 10 bytes then seek to position 20 is actually a seek to position 10 Likewise seek to 20 is set to position 0 PARAMETERS sspec Open file handle This must be a handle that was returned by sspec open offset Byte offset whence Reference point for seek One of the following constants e SEEK SET start of file offset should be non negative e SEEK CUR current position in file offset may be negative zero or positive e SEEK_END end of file offset should be non positive to stay within the file RETURN VALUE 0 OK The following return values are negatives of the values defined in errno lib e EINVAL whence parameter was invalid e EBADF The specified handle was not open or invalid EPERM Operation not permitted on this file resource This is usually because the resource is not seekable such as a compressed file e Any other negative values indicate an error SEE ALSO sspec close sspec write sspec read sspec tell sspec open 118 rabbit com Server Utility Library sspec setformepilog int sspec setformepilog int form int function DESCRIPTION Sets the user specified function that will be called when th
427. t field which is a single line text entry box The NAME parameter defines what the name of that particular input variable is so that when the information is returned to the server then the server can associate it with a particular variable The VALUE parameter defines the current value of the parameter The SIZE parameter defines how long the text entry box is in characters At the end of the HTML page in our example the Submit and Reset buttons are defined with the INPUT tag These use the special types submit and reset since these buttons have special purposes When the submit button is pressed the form is submitted by calling the CGI program myform 4 5 3 1 Sample HTML Page An HTML page that includes a form may look like the following lt HTML gt lt HEAD gt lt TITLESACME Thermostat Settings lt TITLE gt lt HEAD gt lt BODY gt lt H1 gt ACME Thermostat Settings lt H1 gt lt FORM ACTION myform html METHOD POST gt lt TABLE BORDER gt lt TR gt lt TD gt Name lt TD gt lt TD gt Value lt TD gt lt TD gt Description lt TD gt lt TR gt lt TR gt lt TD gt High Temp lt TD gt lt TD gt lt INPUT TYPE text NAME temphi VALUE 80 SIZE 5 gt lt TD gt lt TD gt Maximum in temperature range amp deg F lt TD gt lt TR gt lt TR gt lt TD gt Low Temp lt TD gt lt TD gt lt INPUT TYPE text NAME templo VALUE 65 SIZE 5 gt lt TD gt lt TD gt Minimum in temperature range a
428. t parms snmp get snmp get next snmp get indexed snmp add snmp_xadd snmp delete 412 rabbit com SNMP snmp last int int snmp last int snmp parms p DESCRIPTION Return the short integer value of the last object retrieved from the MIB tree The object must be of a short integer type and may be in either xmem or root storage If the object is in fact a long integer then the return value will reflect only the low 16 bits of the value If the object is of any other type the returned value will be garbage PARAMETERS p Parameter structure that was used previously in a call to a retrieval function such as sunmp get indexed snmp get or snmp get next RETURN VALUE Returns the object value Result will be garbage if the object is not a short integer type or if p was NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp get snmp get next snmp get indexed snmp last long snmp last mem snmp last xmem snmp last tvpe snmp last len TCP IP Manual Vol 2 rabbit com 413 snmp last len word snmp last len snmp parms p DESCRIPTION Return the current length of the last object retrieved from the MIB tree The object may be of any type and may be in either xmem or root storage The current length may be less than or equal to the result from snmp last maxlen PARAMETERS p Parameter structure that was used previously in a call to a retrieval function such as snmp get indexed snmp_get or snmp get ne
429. t still has the ability to upload files to the filesystem As before the changes are in boldface define USE HTTP UPLOAD define TCPCONFIG 1 define USE HTTP BASIC AUTHENTICATION 1 use fs2 lib define admin group 0x0001 define monitor group 0x0002 use dertcp lib use http lib ximport my app shtml my app shtml SSPEC MIMETABLE START SSPEC MIME FUNC ssi text html shtml handler SSPEC MIME cgi wi SSPEC MIMETABLE END int io state SSPEC RESOURCETABLE START SSPEC RESOURCE ROOTVAR io state amp io state INT16 d SSPEC RESOURCE XMEMFILE index html my app shtml SSPEC RESOURCE CGI upload cgi http defaultCGI SSPEC RESOURCE CGI update cgi VarUpdateCGI SSPEC RESOURCETABLE END void mv io polling void void main int rc io state 42 sspec_addrule index html Pet admin groupjmonitor group 0 SERVER HTTP SERVER AUTH BASIC NULL sauth setusermask sauth adduser admin dog SERVER ANY admin group NULL sauth setusermask sauth adduser monitor cat SERVER ANY monitor group NULL re sspec automount SSPEC MOUNT ANY NULL NULL NULL if rc printf Failed to initialize rc d n Proceeding anyway n rc sock init http init for 27 4 mv io polling http handler TCP IP Manual Vol 2 rabbit com 27 The first change is the removal of the macros we added for FAT and also the removal of use stat
430. t to avoid overwriting past the end of the allocated space for the object Returns p unless p is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp set stem snmp set parse stem snmp append stem snmp_append parse stem snmp set access snmp set callback snmp up stem snmp xadd snmp delete snmp get snmp last index TCP IP Manual Vol 2 rabbit com 395 snmp add community int snmp add community char cname byte mask DESCRIPTION Add anew community with a given access mask to the table of community names The size of the table is specified using SNMP_MAX COMMUNITIES The first 3 communities are automatically defined thus do not need to be added using this function PARAMETERS cname Community name as a null terminated string with a maximum length of SNMP MAX COMMUNITY NAME mask This specifies the access groups one or more of 8 groups to which this com munity belongs Three groups are predefined SNMP PUBLIC MASK public group with read only access SNMP PRIVATE MASK private group with read write access SNMP TRAPDEST MASK trap group with no access RETURN VALUE 1 No room in table 20 Number of entries in community table after current addition This is the community index which is required for other API functions LIBRARY SNMP LIB SEE ALSO snmp set dflt communities snmp set community snmp communitv name snmp communitv mask 396
431. t tree snmp set access snmp set callback snmp set communitv snmp set dflt communities snmp set foct snmp set int snmp set long snmp set objectIiD snmp set oct snmp set oid snmp set parse oid snmp set parse stem snmp set stem snmp set str snmp start snmp stop snmp time since snmp timeticks snmp trap snmp unmonitor snmp up oid snmp up stem snmp used snmp xadd 392 rabbit com SNMP snmp add snmp parms snmp add snmp parms p char n word type void v word maxlen DESCRIPTION Add an object into the MIB tree The parameter structure p must be set up using snmp init parms and other functions such as snmp set stem to indicate the ob ject ID of the object to be added This function is used to add objects which reside in root data storage The object must persist at the specified location v at least until the object is deleted using snmp_delete Typically the object may already exist in some preexisting application e g as a field in some structure The object may be used exactly as an ordinary variable or field except that its value may change whenever tcp_tick is called and there happens to have been an SNMP SET request on that object If SNMP is not being used the object will not be modified by any of the MIB LIB functions snmp add and snmp xadd are the most general functions Cleaner code can result from using the equivalent macro invocations There are 10 macro invocations of s
432. t will be displayed const ConsoleCommand console _commands Tm Om OO HELLO WORLD hello world 0 ECHO con_echo help echo txt HELP con help help help txt NULL help txt SET NULL help set txt SET PARAM con set param 0 SET IP con set ip help set txt SET NETMASK con set netmask help set txt SET GATEWAY con_set_gateway help set txt SET NAMESERVER con set nameserver help set txt SET MAIL NULL help set mail txt SET MAIL SERVER con set mail server help set mail server txt SET MAIL FROM con set mail from help set mail from txt SHOW con show help show txt PUT con put help put txt GET con get help get txt DELETE con delete help delete txt LIST NULL help list txt LIST FILES con list files help list txt LIST VARIABLES con list variables help list txt CREATEV con createv help createv txt PUTV con putv help putv txt GETV con getv help getv txt MAIL con mail help mail txt RESET FILES con reset files 0 RESET VARIABLES con reset variables help reset variables 462 rabbit com General Purpose Console 14 4 1 1 Default Command Functions The following functions are provided in Zconsole lib Each one takes a pointer to a ConsoleState structure as its only parameter following the prototype for custom functions described in Section 14 4 1 2
433. tTransferEncoding http getURL http getUserState http handler http idle http init http is secure http nextfverr http parseform http safe http scanpost http set anonvmous http setauthentication http setCond http setcookie http set path http setState http shutdown http skipCGI http sock bvtesreadv http sock fastread http sock fastwrite http sock gets http sock mode http sock readable http sock writable http sock tbleft http sock write http sock xfastread http sock xfastwrite http status http switchCGI http urldecode http write shtml addfunction shtml addvariable shtml delfunction shtml_delvariable TCP IP Manual Vol 2 rabbit com 185 cgi continue int cgi continue HttpState state char localurl DESCRIPTION Called from a CGI function after processing any data submitted This function continues creating a response as if from a normal GET request to the specified local URL NOTE the CGI function must NOT have sent any data to the socket PARAMETERS state A pointer to the HTTP server state structure localurl The URL string which must be a URL defined in the server spec table oth erwise the browser will see a not found message RETURN VALUE The return value from this function should be used as the return value from the CGI handler func tion that calls it LIBRARY HTTP LIB 186 rabbit com HTTP Server cgi redirectto void cgi redi
434. table must be searched exhaustively for each initial resource access There should be no need for a large number of entries provided that the resource name hierarchy is organized in a reasonably efficient manner For ex ample keep the resources for a particular user or realm in one directory and just add an entry for that directory instead of an entry for each resource This works because the full path name is al ways used for matching and the directory will always be a prefix string of the files that reside in that directory As an alternative to this function you can statically initialize a rule table using the following mac ros define SSPEC FLASHRULES Required use zserver lib this library SSPEC RULETABLE START SSPEC RULE prefix realm rg wg sm SSPEC RULE prefix realm rg wg sm SSPEC MM RULE prefix realm rg wg sm meth mime SSPEC MM RULE prefix realm rg wg sm meth mime SSPEC RULETABLE END The SSPEC MM RULE macro parameters are basically the same parameters as would be passed to this function These macros define and initialize a constant rule table named f rule table SSPEC RULE just omits the rarely used method and mimetype fields When using a static rule table the dynamically added entries are searched before the static ones TCP IP Manual Vol 2 rabbit com 65 sspec addrule cont PARAMETER pfx Prefix of resource name This must include the initial character si
435. te gt length buffer to write out if state gt offset lt state gt length state gt offset sock fastwrite amp state gt s state gt buffer int state gt offset int state slength int state soffset else state soffset 0 state gt length 0 else switch state gt substate case 0 strepy state gt buffer HTTP 1 0 200 OK r n r n state slength strlen state gt buffer state soffset 0 state gt substate break case l strcpy state gt buffer lt html gt lt head gt lt title gt Results lt title gt lt head gt lt body gt r n state slength strlen state gt buffer state gt substate break case 2 initialize the FORMSpec data FORMSpec 0 value 0 Xo FORMSpec 1 value 0 0 state gt p state gt buffer state gt substate break TCP IP Manual Vol 2 rabbit com 157 case 3 parse the POST information if parse post state sprintf state gt buffer lt p gt Username s lt p gt r n lt p gt Email s lt p gt r n FORMSpec 0 value FORMSpec 1 value state slength strlen state gt buffer state gt substate break case 4 strcpy state gt buffer lt p gt Go lt a href shome lt a gt lt body gt lt html gt r n state gt length strlen state gt buffer state gt substate break default state gt substate 0 return 1 return 0 158 rabbit com HTTP
436. ted which will be stored in buf i primet Calling ico elieme se icujo a if ftp client setup resolve REMOTE HOST REMOTE PORT anonymous anoneanon com FTP MODE DOWNLOAD bar NULL buf sizeof buf printf FTP setup failed n exit 0 Prinke hooping on fEp client etic 7 vn while ret Hic Glieme tiek continue it l ret printf FTP completed successfully n ftp client filesize returns transfer size since we asked for download but ftp client filesizefbj 0 primer DAA Se Va low else rime YEW teilecls status gAn ret 320 rabbit com FTP Client RABE Tete 8 FTP SERVER This chapter documents the FTP server The following information is included e configuration macros e the default file handlers e how to assign replacement file handlers e what to do when there is a firewall e API functions e commands accepted by the server e reply codes generated by the server e sample code demonstrating a working FTP server The library FTP SERVER LIB implements the File Transfer Protocol for the server side of a connection FTP uses two TCP connections to transfer a file The FTP server does a passive open on well known port 21 and then listens for a client This is the command connection The server receives commands through this port and sends reply codes The second TCP connection is for the actual data trans
437. tent Type text html r n r n http date str date Then send it to the client by returning CGI SEND straight away CGI SEND tells the HTTP server that the CGI function has put a null terminated string in the http getData buffer and that the server should not call the CGI again until the string has been sent This is the most convenient way of sending relatively small amounts of data at a time It relies on the fact that the CGI is allowed to write to the buffer returned by http_getData Since http getData is used to pass incoming data to the CGI it is important to ensure that the incoming data has been fully processed before writing over that buffer In addition the buffer s length is HTTP MAXBUFFER which limits the size of the string including the null terminator The CGI can return CGI_ SEND for any action code except CGI_ ABORT When the action code is CGI EOF there is no more incoming data so strings can be written back to the client indefinitely the server keeps calling the CGI at CGI_ EOF When the CGI has finished generating all the content it must return CGI_ DONE When the server gets the CGI_ DONE return code it closes the client connection normally and ceases call ing the CGI If the CGI has one more thing to write before it is done it can return CGI_SEND_ DONE which com bines the CGI SEND and CGI_ DONE return codes This can simplify the CGI if it does not have to do much when it first gets the CGI_ E
438. ter structure that was used previously in a call to a retrieval function such as snmp get indexed snmp get or snmp get next RETURN VALUE Returns the maximum permissible object length Result will be garbage if p was NULL LIBRARV MIB LIB SEE ALSO snmp init parms snmp get snmp get next snmp get indexed snmp last int snmp last long snmp last mem snmp last xmem snmp last tvpe snmp last len 416 rabbit com SNMP snmp last mem char snmp last mem snmp parms p DESCRIPTION Return the logical address of the last object retrieved from the MIB tree The object may be of any type however it must NOT have been defined as an xmem object PARAMETERS p Parameter structure that was used previously in a call to a retrieval function such as snmp_get_indexed snmp_get or snmp get next RETURN VALUE If p was NULL or the object is in xmem storage returns NULL Otherwise the logical near ad dress of the object is returned LIBRARY MIB LIB SEE ALSO snmp init parms snmp get snmp get next snmp get indexed snmp last int snmp last long snmp last xmem snmp last tvpe snmp last len TCP IP Manual Vol 2 rabbit com 417 snmp last objectID snmp parms snmp last objectID snmp parms p snmp oid oid DESCRIPTION Copy the last OID object which was retrieved from the MIB tree into oid PARAMETERS p Parameter structure that was used previously in a call to a retrieval function s
439. the first available partition is the first partition on the drive then it will be mounted at mount point A If it is the second partition it will be mounted at B etc Up to four partitions are scanned If none are found or none are FAT12 or FAT 16 partitions then an er ror is returned For FS2 all logical extents will be initialized via the fs_ init function PARAMETERS which The filesystem s to mount This is a bitwise OR of the following constants e SSPEC MOUNT FS FS or FS2 flash filesystem e SSPEC MOUNT FAT FAT filesystem 1st drive You can also pass SSPEC MOUNT ANX to mount all known filesystems 72 rabbit com Server Utility Library sspec automount cont fatstuff Either NULL no info return or must point to a struct of type sspec fatinfo This structure defined in zserver lib consists of the following fields typedef struct dos ctrl ctrl mbr drive drive fat part part 4 sspec fatinfo When calling this function vou should NULL out all these pointers using memset 0 You can then optionally set some of the point ers to valid non NULL values in order to override the defaults supplied bv this function If you set the ct r1 pointer then it is assumed by this function that you have already called the controller initialization function If the pointer is NULL on entry then this function will call the default controller initialization via the DOS_CONTROLLER_INIT macro
440. the functions required to implement a web server more formally known as an HTTP HyperText Transfer Protocol server The browser is formally called an HTTP client You only need to write code specific to your application such as dealing with I Os and the Rabbit peripheral devices and possibly some code to help the HTTP server generate the appropriate responses back to the user s web browser In addition there is a small amount of boilerplate that needs to be written to include and configure the HTTP server and any ancillary libraries such as the TCP IP suite and filesystems 2 1 Designing Your Application Should you decide to web enable your application you probably already have some idea of the format and layout of the web pages that will be presented to the browser Unless the application only returns informa tion and does not allow any updates such as a data logger you will probably need to lay out some forms Forms in web parlance allow the browser s user to fill in some information then submit it to the server The server then performs the requested actions and sends a confirmation back to the browser This is the most common means for implementing control of the server as opposed to merely querying it There are several other things to consider Answers to the following list of questions will determine the pieces of software that need to be gathered into your application and how they link together e Does access to some o
441. the result of a ZHTML page is to check the source of the page in the browser For Internet Explorer the user can choose the View Source menu item Other browsers have equivalent functionality To display some information if the page is being displayed in error mode use error with no parame ter If any variable in the form has an error error will return TRUE Here is an example of its use lt z if error gt Errors are in the submission Please correct them below 222 gt 5 3 6 Securitv Permissions and Authentication To check if a user has authorization for a specific variable call the auth function lt z if auth Sfoo rw Is Vou have read write access to the variable foo 222 gt ro is also a valid second parameter To check if the current page is being displayed as the result of a POST request instead of a GET request call the updating function lt z if updating gt 7iz if lerror gt lt META HTTP EQUIV Refresh CONTENT 0O URL http yoururl com gt lt z gt 222 gt Both auth and updating may be preceded by 1 the not operator TCP IP Manual Vol 2 rabbit com 273 5 4 TCP to Serial Port Configuration Example This section is a step by step description of the sample program ethernet to serial c ltis located in Samples tcpip rabbitweb This sample program can be used to configure a simple Ethernet to serial converter Fo
442. this information is to look at the provided demo program as an example TCP IP Manual Vol 2 rabbit com 377 12 2 Demo Program The sample program SNMP1 C implements an SNMP agent that will run on any Ethernet enabled Rabbit based target The code fragments in this section are from SNMP1 C To see the program in its entirety open up the source code file located at Samples tcpip snmp memmap xmem This is necessary for all SNMP applications It causes inclusion of SNMP LIB and MIB LIB define USE SNMP 1 This must be defined to support trap sending define SNMP_TRAPS Standard DCRTCP network definitions Change to suit your site requirements define TCPCONFIG 1 Set the IP address of the SNMP manager that will receive trap messages define MANAGER IP 10 10 6 178 For this demo only send trap every 5 seconds define SEND TRAPS Rabbit Semiconductor do not change define SNMP_ENTERPRISE 12807 tause U leweejo alg The network definitions TCPCONFIG pertain to the target on which SNMP1 C is running MANAGER IP identifies the SNMP manager to which SNMP traps are sent The configuration macro SNMP_TRAP_ PORT will default to UDP port 162 if it is not defined in the ini tialization code of the application 378 rabbit com SNMP 12 2 1 Creating Managed Objects The variable definitions in the following code fragment are the managed objects that the agent will store in a MIB
443. tion either do not define USE SMTP AUTH or pass empty strings 77 as the parameters to smtp setauth Program Name Samplesttcpipismtpismtp c define TCPCONFIG 1 pick network configuration define FROM myaddress mydomain com define TO myaddress mydomain com define SUBJECT You ve got mail define BODY Visit the Rabbit web site r n SMTP_SERVER identifies the mail server This can be name or IP address define SMTP SERVER mymailserver mydomain com define USE SMTP AUTH memmap xmem use dcertcp lib use smtp lib main secle imie 5 while ifpending IF DEFAULT IF COMING UP tcp tick NULL ifdef USE SMTP AUTH smtp setauth myusername mypassword tendif smtp sendmail TO FROM SUBJECT BODX while smtp mailtick SMTP PENDING continue if smtp status SMTP SUCCESS printf Message sent n else printf Error sending message n TCP IP Manual Vol 2 rabbit com 355 10 4 Configuration Macros The SMTP client is configured by using compiler macros SMTP AUTH FAIL IF NO AUTH Defaults to undefined This macro was introduced in Dynamic C 9 21 If it is defined the login will fail if authentication fails Otherwise the library will fall back on an unauthenticated login if authentication fails Prior to Dynamic C 9 21 the login failed if authentication failed so the macro is restoring that behavior SMTP DEBUG This macro tells the SMTP code to l
444. tion is to use the tcp reserveport function and a smaller number of sockets HTTP MAXURL This macro defines the maximum incoming URL This could be important if someone is allowing GET requests with a large number of parameters HTTP PORT This macro allows the user to override the default port of 80 HTTP IFACE This macro allows the user to override the default listening network interface The default is IF_ANY meaning that the HTTP server s will listen for incoming network connections on all interfaces which are up You can restrict the HTTP servers to a single interface by overriding this macro to the specific interface number for example IF_ETHO 142 rabbit com HTTP Server HTTP TIMEOUT Defines the number of seconds of no activity that can elapse before the HTTP server closes a con nection The default is 16 seconds HTTP USERDATA SIZE This macro causes char userdata to be added to the Ht tpState structure Define your struc ture before the statement use HTTP LIB struct UserStateData char name 50 int floor int model define HTTP USERDATA SIZE sizeof struct UserStateData use http lib In your own CGI function code access it using mystate struct UserStateData http getUserData state USE HTTP DIGEST AUTHENTICATION Set to 1 to enable digest authentication 0 to disable digest authentication Set to 0 by default USE HTTP BASIC AUTHENTICATION Set to 1 to enable basic authenticati
445. to the second HTML file uses the name that was given to humidity admin zhtml when it was entered into the static resource table in humidity c Figure 5 8 Web Page Served EJ Current humidity reading Microsoft Internet Explorer Biel ES f bv RabbitWeb ja Edit View Favorites Tools Help a z ala a g 7 ae k la d St Refresh H Search Favorites Hist Mail This web page is very simple as shown acl orwar op efres ome eari avorites History ail l Address http nowhere org index zhtml ka Go Links in Figure 5 8 but you are free to create more complex web pages probably Current humidity reading containing more variables to monitor HTML editors such as Netscape s Com poser Hotdog Professional and Macro Change the device settings media Dreamweaver can be used to create these web pages The current humidity reading is in percent 50 5 1 2 2 The Configuration Page The second HTML file is known to the server as admin index zhtmi Using error and some conditional i Internet code allows multiple displav options with the same HTML file Again the file is shown in its entiretv for convenience It is broken down on the following pages TCP IP Manual Vol 2 rabbit com 255 File name Samples tcpip rabbitweb pages humidity admin zhtml lt HTML gt lt HEAD gt lt TITLE gt Configure the humidity device lt TITLE gt lt HEAD gt lt BODY gt lt H1l gt Con
446. tp_mailtick 362 rabbit com SMTP Mail Client smtp setserver int smtp setserver char server DESCRIPTION Sets the SMTP server This value overrides SMTP_SERVER and the results of any previous call to smtp setserver ip PARAMETER server Server name string This is copied into the SMTP state structure This name is not resolved to an IP address until you start calling smtp mailtick RETURN VALUE SMTP_OK Server name was set successfully SMTP_NAMETOOLONG The server name was too long SEE ALSO smtp sendmail smtp setserver ip smtp_mailtick smtp setserver ip int smtp setserver ip longword server DESCRIPTION Sets the SMTP server This value overrides the value set by smtp_setserver and is used when the IP address of the mail server is known PARAMETER server Server IP address RETURN VALUE SMTP_OK server IP was set successfully SEE ALSO smtp sendmail smtp setserver smtp mailtick TCP IP Manual Vol 2 rabbit com 363 smtp status int smtp_status void DESCRIPTION Return the status of the last e mail processed RETURN VALUE SMTP SUCCESS e mail sent SMTP_ PENDING e mail not sent yet call smtp_mailtick again SMTP_TIME e mail not sent within SMTP_ TIMEOUT seconds SMTP_UNEXPECTED received an invalid response from SMTP server LIBRARY SMTP LIB 364 rabbit com SMTP Mail Client RABE Tete 11 POP3 CLIENT Post Office Protocol version 3 POP3 is pr
447. tring FROM SNMPv2 TC demos FROM RABBITSEMI SMI rabbitsemiDemoSNMP1 MODULE IDENTITY Look in RABBITSEMI DEMO SNMP1 txt for the details that belong here 235 1 demos 1 demoRWObjects OBJECT IDENTIFIER rabbitsemiDemoSNMP1 1 demoROObjects OBJECT IDENTIFIER rabbitsemiDemoSNMP1 2 386 rabbit com SNMP At this point the correspondence between 12807 3 1 1 and SNMP ENTERPRISE oemExperi ments demos rabbitsemiDemoSNMP1 becomes apparent The remainder of RABBITSEMI DEMO SNMP1 txt contains definitions for the rest of the MIB that will be used in the demo Here are the first two leaf nodes rw int OBJECT TYPE SYNTAX INTEGER 32768 32767 MAX ACCESS read write STATUS Daag Smits DESCRIPTION A read write short integer value demoRWObjects 1 0 rw long OBJECT TYPE SYNTAX INTEGER 200000000 200000000 MAX ACCESS read write STATUS current DESCRIPTION A read write long integer value demoRWObjects 2 0 The OBJECT TYPE macro defines leaf nodes on the MIB tree The SYNTAX line defines the data type of the managed object stored at the leaf node and gives the allowable range of values TCP IP Manual Vol 2 rabbit com 387 The tree diagram for this demo looks like this rabbitsemi 12807 rabbitsemiProducts 1 oemExperiments 3 rabbitsemiChipsets 9 demos 1 rabbitsemiDemoSNMPI 1 demoRWObjects 1 demoROObjects 2 rw int 1 0 ro int 1 0 rw long 2 0 ro long 2 0 rw
448. ty of a CGI will be required Prior to Dynamic C 8 50 writing a robust CGI was the most difficult part of the process Starting with Dynamic C 8 50 there is a new style of CGI writing that simplifies the process and reduces the chances of error The old style CGI is still supported for backwards compatibility 2 3 2 HTTP Block Let us now progress to the HTTP server itself In the diagram this is the block with two circles inside The server is responsible for fielding requests from the outside world Each request is analyzed to determine the resource that is being requested the user who is making the request and whether the user is authorized to obtain that resource If the resource is available the user is known and has the proper permissions then the resource is transmitted back to the browser Following the above steps in more detail we have 1 Analyze the request obtain the resource name Part of the information provided by the browser is a request header that contains a URL Uniform Resource Locator The URL is simply the name of the resource to retrieve URLs typically look like a file name in a Unix style filesystem that is component directory and file names separated by slash characters 2 Obtain the user ID The browser has the option of sending the username and password of its user If it does not do this then the userid is anonymous If this is not good enough then the browser can always try again when it is
449. u have some resource which is say protected for write access but you want any user to be able to retrieve the resource without requiring a user name password NOTE This function is non reentrant It sets a global variable which is accessed by all HTTP server instances For this reason you should call this function once only before starting to call http handler PARAMETER uid The userID to use as the anonymous user This should have been defined us ing sauth adduser Pass 1 to set no anonymous user In this case only resources which are completely free of any access controls will be ac cessible to users who do not provide credentials RETURN VALUE Same as the uid parameter except 1 if uid invalid LIBRARY HTTP LIB SEE ALSO sauth_adduser ftp_set_anonymous sauth_setusermask 224 rabbit com HTTP Server http setauthentication int http setauthentication int auth DESCRIPTION Sets the type of authentication to be used globally by the HTTP server By default this is set to the strongest available type of authentication available in order of weakest to strongest HTTP NO AUTH HTTP BASIC AUTH HTTP DIGEST AUTH This function returns the type of authentication that was actually configured If the type of authentication that you ask for was not compiled in at compile time then the type of authentication will not be changed NOTE this function only sets the default authentication method for resources who h
450. ually at least 1024 bytes If you try exceeding that limit http write will never succeed RETURN VALUE 0 data written or buffered successfully CGI_ MORE data not written try again on next call to the CGI In general the CGI should pass this code CGI_ MORE back to the HTTP server When the server calls the CGI next time it will set the action code to CGI_ CONTINUE which will be a cue to the CGI to try retransmitting the previous data When CGI_ CONTINUE is provided the contents in the http getData buffer will not have been altered LIBRARY HTTP LIB SEE ALSO http_getAction http_skipCGI http_switchCGI http_finishCGI http_abortCGI http_defaultCGI 244 rabbit com HTTP Server shtml addfunction int shtml addfunction char name void fptr DESCRIPTION Adds a CGI SSI exec function for making dynamic web pages to the RAM resource table PARAMETERS name Name of the function e g foo cgi fptr Function pointer to the handler that must take HttpState as an argu ment This function should return an int 0 while still pending 1 when fin ished RETURN VALUE 0 Success 1 Failure no room LIBRARY HTTP LIB SEE ALSO shtml_delfunction TCP IP Manual Vol 2 rabbit com 245 shtml addvariable int shtml addvariable char name void variable word type char format DESCRIPTION This function adds a variable so it can be recognized by shtml_handler PARAMETERS name
451. ubmit ted multiple times RabbitWeb will take the last value given as the true value and ignore all previous ones So to force a default unchecked value you can include a hidden variable before you do the checkbox INPUT field Since you can do ZHTML comparisons with numbers if you give the variable the value 0 or 1 it can be used in the checkbox INPUT tag lt INPUT TYPE hidden NAME lt z varname Scheckbox 0 gt VALUE 0 5 lt INPUT TYPE checkbox NAME lt z varname S checkbox 0 722 VALUE 1 lt z if checkbox 0 1 gt CHECKED lt z gt So if the value of Scheckbox 0 is 1 then the CHECKED attribute will be included and the checkbox will be checked Otherwise it will be blank If it is checked when the form is displayed but you clear the value this still works since the hidden field with a value of 0 will always be sent Since a list of radiobuttons is more likely to be subject to different formatting depending on user taste than something like a pulldown menu there is no automatic way of generating the list The best way to generate a list of radiobuttons is to use a for loop and the count function The following page displays both a checkbox and a list of radiobuttons lt HTML gt lt HEAD gt lt TITLE gt Radio button and checkbox lt TITLE gt lt HEAD gt lt BODY gt lt form action index zhtml method post gt lt INPUT TYPE hidden name checkboxBoolean VALUE 0 gt lt INPU
452. uch as snmp get indexed snmp get or snmp get next oid Pointer to an snmp oid structure to which the result is copied RETURN VALUE NULL if p was NULL or the last object retrieved was not an object ID object p otherwise LIBRARY MIB LIB SEE ALSO snmp init parms snmp get snmp get next snmp get indexed snmp last int snmp last long snmp last mem snmp last xmem 418 rabbit com SNMP snmp last snmp type word snmp last snmp type snmp parms p DESCRIPTION Return the SNMP type of the last object retrieved from the MIB tree Each object has two types The SNMP type indicates the type of object to external entities using SNMP to examine objects on this agent The internal type see snmp last type indicates the memory layout for the object in the MIB tree The same memory layout may be used for different SNMP types and vice versa PARAMETERS p Parameter structure that was used previously in a call to a retrieval function such as snmp_get_indexed snmp_get or snmp get next RETURN VALUE SNMP type of the object The currently supported types are SNMP P INTEGER SNMP P OCTETSTR SNMP P OID SNMP P IPADDRO SNMP P COUNTER SNMP P GAUGE SNMP P TIMETICKS LIBRARV MIB LIB SEE ALSO snmp init parms snmp get snmp get next snmp get indexed snmp last int snmp last long snmp last mem snmp last xmem snmp last tvpe snmp last len TCP IP Manual Vol 2 rabbit com 419 snmp
453. ucture for the given I O stream and return an int The return value should be 0 when the command wishes to be called again on the next console_tick 1 when the command has successfully finished processing or 1 when the command has finished due to an error int hello world ConsoleState state state gt conio gt puts Hello World r n return 1 void main void Initialize TCP IP clients servers and I O prior to using any console functions S6wlz imit CO p tcp reserveport 80 Start a listen queue and disable the 2MSL wait weto imit dae ee inst Oy 64 printf Filesystem not present n iz console imie l premer llonsole clicl moe imitielizel ia fs format 0 64 1 After the file system has been initialized or formatted space must be reserved in the file system for the backup information con backup reserve con backup Save the backup information to the console while 1 COMPOS cick y http handler TCP IP Manual Vol 2 rabbit com 491 492 rabbit com General Purpose Console RABE Tete Index Svmbols E OCHO VAL dalse enee eE E aa Ba best 151 e mail HEXEC emd si et ke e eer i 151 POP3 client eee nnsennenzznnennnnanznznnnna 365 371 include file skieken kanna ba ee keta 151 SMTP Client iii a e ik 353 364 A entries IN CITECIOLY a sccsscssesseesecsesccesseenessuesceesssvenedons 79 ANONYMOUS login LL ens 321 j app
454. ud rate is changed on a serial port then that serial port likely needs to be closed and reopened To handle this and similar situations a callback function can be associated with an arbitrary group of variables web update foo bar baz user _ callback If any variable within a group is changed then the callback function for that group is called The user pro gram through the callback function can then take the proper action based on the new value The above statement means that if any of the variables foo bar or baz are updated then the function user callback will be called to notify the application If variables in more than one group are updated at once each group s callback function will be called in turn with no guarantees on order of calls If a variable is in multiple groups and that is the only variable updated then all update callback functions are called although the order in which they are called is unspecified There is an important restriction on the use of web update for arrays and structures for an array ele ment or structure member registered explicitly that is with its own web statement the callback func tion associated with the array or structure as a whole will not be called when the variable is updated For example consider struct foo2 1 int a int b struct foo2 bar web bar web bar a web_update variables must be explicitly web registered web update bar user_callback fweb update
455. unction Any of the TCP functions can be used however you should not use any functions that may wait for long periods or may change the state or mode of the socket since the HTTP server depends on it being a normal ASCII mode TCP sock et It is recommended that you use the http getSocket macro instead of directly accessing this field substate subsubstate Intended for holding the current state of a state machine for a CGI function That is if a CGI function relinquishes control back to the HTTP server then the values in these variables will be preserved for the next http handler call in which the CGI function will be called again These variables are initialized to 0 before the CGI function is called for the first time Hence the first state of a state machine using substate should be 0 It is recommended that you use the macros http getState and http setState tomanipulate the substate field instead of direct ly accessing it subsubstate is not accessible via these macros but there are better alternatives 138 rabbit com HTTP Server timeout This value can be used by the CGI function to implement an internal time out main timeout This value holds the timeout that is used by the web server The web server checks against this timeout on every call of http handler When the web server changes states it resets main timeout When it has stayed in one state for too long it cancels the current processing for the
456. unctions will require approximately 600 800 bytes of free stack The data buffer for the file to put or to get is always allocated in xram see xalloc TFTP Session A session can be either a single download get or upload put The functions ending with x are versions that use a data structure allocated in extended memory for applications that are constrained in their use of root data memory 346 rabbit com TFTP Client tftp init int tftp init struct tftp state ts DESCRIPTION This function prepares for a TFTP session and is called to complete initialization of the TFTP state structure Before calling this function some fields in the structure tftp state must be set up as follows ts gt state lt 0 for read 1 for write gt ts gt buf addr lt physical address of xmem buffer gt ts gt buf len lt length of physical buffer 0 65535 gt 5 ts gt my_tid lt UDP port number Set 0 for default gt ts gt sock lt address of UDP socket udp Socket or NULL to use DHCP BOOTP socket gt ts gt rem_ip lt IP address of TFTP server host or zero to use default BOOTP hosts ts gt mode lt one of the following constants TFTP MODE NETASCII ASCII text TFTP_MODE OCTET 8 bit binary TFTP MODE MAIL Mail gt strepv ts sfile lt remote filename or mail address gt Note that mail mode can only be used to write mail to the TFTP server and the file name is the e mail address of the recipient The e
457. up to HTTPC HEADER TIMEOUT milliseconds defaults to 5000 if not defined NOTE Note the macro HTTPC HEADER TIMEOUT controls the timeout in milliseconds that httpc skip headers will block while waiting for the headers to complete If not set HTTPC HEADER TIMEOUT defaults to 5000 5 seconds PARAMETER s Pointer to socket structure to use for connection RETURN VALUE Total bytes in headers or lt 0 for error NETERR_INACTIVE_TIMEOUT timed out due to inactivity NETERR REMOTE RESET connection closed before end of headers 310 rabbit com HTTP Client httpc use proxy void httpc use proxy unsigned long ip word port const char far auth DESCRIPTION Configure the HTTP client library to use a proxy server for all new connections Pass OUL for the IP address to switch back to the default behavior of making direct connections PARAMETERS ip port auth RETURN VALUE None EXAMPLE httpc use proxy inet addr 192 168 1 1 80 username password IP address of the proxy server Port number to connect to Basic authentication credentials in username password format to use when connecting Use NULL or an empty string if the proxy server does not re quire authentication TCP IP Manual Vol 2 rabbit com 311 312 rabbit com HTTP Client RABE Tete 7 FTP CLIENT The library FTP_CLIENT LIB implements the File Transfer Protocol FTP for the client side of the connection
458. urce has no particular authentication method require ments This is a bitwise combination of e SERVER AUTH BASIC plaintext userid password e SERVER AUTH DIGEST challenge response protocol e SERVER AUTH PE public key such as SSL TLS mimetvpe An appropriate MIME tvpe to use If NULL then the default table called http tvpes will be consulted RETURN VALUE 20 OK 1 Error For example out of space in rule table increase SSPEC MAXRULES SEE ALSO sspec removerule sspec getMIMEtvpe 66 rabbit com Server Utilitv Librarv sspec adduser int sspec adduser int sspec int userid DESCRIPTION Add to the read permission mask for the given resource The groups that userid is amember of are ORed into the existing permission mask for the resource The write permissions are not modified NOTE This is not used to create new userids For that see sauth adduser Adds a user to the list of users that have access to the given spec entry Up to SSPEC_USERSPERRESOURCE users can be added Any more than that will result in this func tion returning 1 This function is deprecated as of Dynamic C 8 50 Use the more general sspec setpermissions function instead PARAMETERS sspec Spec index userid User index RETURN VALUE 20 Success index of userid added for given spec entry 1 Failure SEE ALSO sspec setuser sspec getusername sspec getuserid sspec removeuser sspec setpermissions TCP IP Manual Vol
459. ure NULL Success form variable option SEE ALSO sspec setfvoptlist sspec getfvoptlistlen TCP IP Manual Vol 2 rabbit com 93 sspec getfvoptlistlen int sspec getfvoptlistlen int form int var DESCRIPTION Gets the length of the options list of the form variable This function is only valid if the form vari able has the option list set PARAMETERS form spec index of the form var Index into the FormVar array of the variable RETURN VALUE 1 Failure gt 0 Success length of the options list SEE ALSO sspec getfvopt sspec setfvoptlist sspec getfvreadonly int sspec getfvreadonly int form int var DESCRIPTION Checks if a form variable is read only PARAMETERS form spec index of the form var Index into the FormVar array of the variable RETURN VALUE 0 Not read only 1 Read only 1 Failure SEE ALSO sspec setfvreadonlv 94 rabbit com Server Utilitv Librarv sspec getfvspec int sspec getfvspec int form int var DESCRIPTION Gets the server spec index of a variable in a form PARAMETERS form server spec index of the form var Index into the array of FormVar structures of the variable RETURN VALUE 1 Failure 20 Success index of the form variable in the resource list SEE ALSO sspec_addfv sspec getlength long sspec getlength int sspec DESCRIPTION Gets the length of the file associated with the specified ServerSpec structure Get the le
460. ure TCP IP Manual Vol 2 rabbit com 49 sauth getusermask int sauth getusermask int userid word groupbits void authdata DESCRIPTION Get the group access bit s and or authorization data for a given user ID PARAMETERS userid User index groupbits Pointer to bitmask that will be set to group s of which this user is a member If NULL this information is not retrieved authdata Pointer to void that is set to arbitrary server data If NULL this informa tion is not retrieved RETURN VALUE 0 OK 1 Failed userid not valid 50 rabbit com Server Utility Library sauth getusername char sauth getusername int userid DESCRIPTION Returns the name of the user a character string from the ServerAuth structure associated with userid PARAMETERS userid The user s id that is the index into the user table RETURN VALUE NULL Failure NULL Success pointer to the user s name string SEE ALSO sspec getusername TCP IP Manual Vol 2 rabbit com 51 sauth getwriteaccess int sauth getwriteaccess int sauth DESCRIPTION Checks whether or not a user has write access to any server s resources This is an in principle test Each resource is individually protected from write access this is not checked In other words this function may return TRUE even when none of the resources are writable to this user PARAMETERS sauth Index into the user table RETURN VALUE 0 User does n
461. user 215 System type 220 Service ready for new user 221 Service closing connection 226 Closing data connection Requested file action successful for example file transfer or file abort 227 Entering Passive Mode h1 h2 h3 h4 p1 p2 230 User logged in proceed 250 Requested file action okay completed 257 PATHNAME created 331 User name okay need password 425 Can t open data connection 450 Requested file action not taken File unavailable e g file busy 452 Requested action not taken Insufficient storage space in system 502 Command not implemented 504 Command not implemented for that parameter 530 Not logged in 550 Requested action not taken File unavailable e g file not found no access The text used for the reply codes may be slightly different than what is shown here It will be context spe cific 344 rabbit com FTP Server RABE Tete 9 TFTP CLIENT TFTP LIB implements the Trivial File Transfer Protocol TFTP This standard protocol internet RFC783 is a lightweight protocol typically used to transfer bootstrap or configuration files from a server to a client host such as a diskless workstation TFTP allows data to be sent in either direction between cli ent and server using UDP as the underlying transport This library fully implements TFTP but as a client only Compared with more capable protocols such as FTP TFTP e has no security or authentication
462. usive Each OID level is simply the binary value of each byte pointed to by bname The number of levels i e bytes is specified by len For example to append 255 6 0 1 make the following call snmp append binary stem p 4 xFF x06 x00 x01 This function is identical to snmp append binary oid except that it uses an snmp parms structure PARAMETERS p Pointer to parameter structure to set If NULL does nothing but return NULL len Number of bvtes in bname bname Pointer to first bvte of OID RETURN VALUE Returns p unless the OID string is too long to fit in the parameter structure in which case NULL is returned If p is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp append oid snmp append parse stem snmp set stem 398 rabbit com SNMP snmp append oid snmp oid snmp append oid snmp oid oid word len char eos DESCRIPTION This function is identical tosnmp_append_stem except that itusesan snmp oid structure See documentation for snmp set stem for an explanation of OID encoding PARAMETERS oid Pointer to snmp oid structure to set If NULL does nothing but return NULL len Length of eos eos Encoded OID string RETURN VALUE Returns oid unless the OID string is too long to fit in the snmp_ oid structure in which case NULL is returned If oid is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO s
463. ust match the string used in the FORM ACTION tag in the HTML code The second parameter identifies the CGI function that will be called when the form is submitted http defaultCGI is a CGI that is provided with the HTTP server It uploads files to a FAT filesystem shows a status page to the browser after the upload and allows the user to click back to the server s home page For a detailed description of the file upload feature see Section 4 6 Finally the FAT filesystem must be readied for use The call to sspec_ automount takes care of everything assuming that a FAT partition already exists on the serial flash How to create the initial file system is discussed in the Dynamic C User s Manual The application now supports uploading files to the FAT but we have yet to give the user any way to actu ally do it That involves changing the HTML page lt HTML gt lt HEAD gt lt TITLE gt Web Variables lt TITLE gt lt HEAD gt lt BODY gt lt H1 gt Web Variables lt H1 gt lt P gt The current value of io state is lt z echo io state gt lt P gt lt z if error io state gt lt P gt Sorry you were not authorized to perform an update lt P gt lt z gt lt FORM ACTION index html METHOD POST gt lt P gt Enter a new value if you dare lt P gt lt INPUT TYPE text NAME io state SIZE 5 VALUE lt z echo Sio state gt gt lt INPUT TVPE submit VALUE Submit gt lt INPUT TYPE reset VALUE Rese
464. utines A table to hold the low level I O routines must be defined as type VSerialspec typedef struct int id unique ID to match with calls to listen open int open serial port routines or int close serial port compatible routines int tick int rdUsed int wrFree 7 int read int write VSerialSpec TCP IP Manual Vol 2 rabbit com 449 For each serial port A B C and D there is a pre defined macro in VSERIAL LIB define VSERIAL PORTA id id serAopen serAclose NULL serArdUsed serAwrFree serAread serAwrite The parameter passed to VSERIAL PORTA is the unique gateway identifier mentioned earlier This value is chosen by the developer when entries are made to the array of type VSerialSpec also known as the spec table Dynamic C 9 21 includes support for serial ports E and F on all Rabbit 3000 based boards 13 1 1 2 Configuration Macros VSERDIAL DEBUG Turns on debug messages VSERIAL NUM GATEWAYS The number of telnet sessions must be defined and must match the number of entries in the spec table 13 1 2 API Functions Dynamic C 7 05 and Later The following functions compose the latest telnet API A sample program demonstrating their use is avail able at Samples tcpip telnet vserial c vserial close int vserial close int id DESCRIPTION Closes the specified gateway This will not only terminate any network activity but will also cl
465. ver does not currently allow arbitrary mount point names like Unix Instead there is an established convention for each filesystem If FS2 is in use then there is a mount point called fs2 If the FAT file system is in use then one or more mount points called A B C etc are created Since Zserver is the resource manager it takes responsibility for mapping the various filesystems and resource types into a single unified API This API not only takes care of the detailed differences between the various filesystem APIs but also allows some functions to be emulated that are not natively supported by the underlying filesystem In addition to the resource storage and filesystem the resource manager needs to be able to associate other data with each resource This other data is divided into two categories which are listed in the blocks on the left of the diagram The two categories are metadata and authorization Metadata consists of two tables the MIME table and the Rule table The authorization data is currently just a single table of userids The reason for the split into two categories is this the metadata is logically associated with individual resources whereas the authorization data is a mapping from external entities users to the unit in which authorization is per formed namely user groups The Rule table has some overlap since it associates groups with individual resource permissions The
466. verflow It is permissible to register an array element without registering the entire array For example int temps 20 web temps 0 will register temps 0 but not temps 1 temps 2 etc The same holds true for structure members struct food 4 int a int b ki struct foo2 bar web bar The above web statement is functionally the same as web bar a web bar b Registering structure members or array elements separately lets you assign separate error checking expres sions to them a topic covered in Section 5 2 2 TCP IP Manual Vol 2 rabbit com 259 It is also possible to have arrays of structures struct foo2 bar 3 web bar Arravs of structures can contain structures that contain arrays struct foo int a int b 2 ki struct foo bar 3 web bar And so on and so on 5 2 1 1 Selection type Variables Defining variables that can take on one of a list of variables is done with the select feature at com pile time int color web color select blue red green The select feature is useful when creating a drop down menu or a set of radio buttons It is similar to an enumerated type In this case the actual variable color is an int and holds one of the values 0 1 or 2 corresponding to the strings blue red and green respectively To specify starting numbers other than zero do the following int color web color select blue 5
467. with their OID number and value Non leaf nodes are printed with their OID fragment suffixed with For simplicity this function recurses LIBRARY MIB LIB TCP IP Manual Vol 2 rabbit com 425 snmp set access snmp parms snmp set access snmp parms p byte rm byte wm DESCRIPTION Set the read and write masks for access control of the next object to be added Read write masks are only applicable if SNMP is used The functions in this library for accessing objects do not ap ply the access masks This remains in effect for all further additions until changed by a new call to snmp set access The rm and wm are bit 8 bit bitmasks A bit n is set if the communities whose access mask have the n th bit set are allowed to access the object in that mode read or write By default bit 0 is set for the PUBLIC community s access mask and bit 1 is set for the PRIVATE community Typ icallv objects are created with rm 3 and wm 2 giving both public and private read access but only private has write access PARAMETERS p Pointer to parameter structure to set If NULL does nothing but return NULL rm Read access mask wm Write access mask RETURN VALUE Returns p unless p is NULL on entry then nothing is done except to return NULL LIBRARY MIB LIB SEE ALSO snmp_init_parms 426 rabbit com SNMP snmp set callback snmp parms snmp set callback snmp parms p snmp callback cb DESCRIPTION
468. xt RETURN VALUE Returns the object length Result will be garbage if p was NULL LIBRARV MIB LIB SEE ALSO snmp init parms snmp get snmp get next snmp get indexed snmp last int snmp last long snmp last mem snmp last xmem snmp last tvpe snmp last maxlen 414 rabbit com SNMP snmp last long long snmp last long snmp parms p DESCRIPTION Return the long integer value of the last object retrieved from the MIB tree The object must be of a long integer type and may be in either xmem or root storage If the object is of any other type including short integer the returned value will be garbage PARAMETERS p Parameter structure that was used previously in a call to a retrieval function such as snmp_get_indexed snmp_get or snmp get next RETURN VALUE Returns the object value Result will be garbage if the object is not a long integer type or if p was NULL LIBRARY MIB LIB SEE ALSO snmp init parms snmp get snmp get next snmp get indexed snmp last int snmp last mem snmp last xmem snmp last tvpe snmp last len TCP IP Manual Vol 2 rabbit com 415 snmp last maxlen word snmp last maxlen snmp parms p DESCRIPTION Return the maximum length of the last object retrieved from the MIB tree The object may be of any type and may be in either xmem or root storage The current length from snmp last len mav be less than or equal to the result from this function PARAMETERS p Parame
469. xternal agents will retransmit the request Otherwise they may give up This function is used when there is a substantial amount of MIB tree processing to be performed locally and it is also desired to prevent asynchronous access to the MIB tree e g to prevent race conditions RETURN VALUE 0 LIBRARY SNMP LIB SEE ALSO snmp start 440 rabbit com SNMP snmp time since longword snmp time since longword epoch DESCRIPTION Return the number of SNMP timeticks elapsed since a specified epoch PARAMETERS epoch The reference epoch This should be a value obtained by a previous call to snmp timeticks RETURN VALUE Number of 1 100 second intervals since epoch This value counts from 0 to 231 1 then wraps around to zero LIBRARY SNMP LIB SEE ALSO snmp timeticks snmp timeticks longword snmp timeticks void DESCRIPTION Return the current SNMP timeticks count RETURN VALUE Number of 1 100 second intervals since the application started This value counts from 0 to el 1 then wraps around to zero LIBRARV SNMP LIB SEE ALSO snmp time since TCP IP Manual Vol 2 rabbit com 441 snmp trap int snmp trap longword ipaddr word c index int trap num word noids word indices DESCRIPTION Send an SNMPviI trap message Traps are unsolicited messages sent to a network management agent for example to inform the agent about an unusual condition Traps are not del
470. y The user anonymous may download the file rabbitA gif but not rabbit gif The user foo with password bar may download rab bitF gif but also rabbitA gif since files owned by the anonymous user are world readable File Name Samples tcpip ftp server c define TCPCONFIG 101 define SSPEC NO STATIC PREGULEC For DC 8 50 ox later memmap xmem tase Teerecj Lalo use ftp server lib ximport samples tcpip http pages rabbitl gif rabbitl gif main ime ile Wieser s Set up the first file and user Tile epee aclkmentile VrabbltA girt weloloslieil_Gpa ic SERVER_FTP user sauth_adduser anonymous SERVER FTP ftp set anonymous user PIO _Seicwisere eS Wiser sspec setuser sspec addxmemfile testi rabbitl gif SERVER FTP user sspec_setuser sspec_addxmemfile test2 rabbitl gif SERVER FTP user Set up the second file and user Tile SSpPe6e E OGbaMentei Le rabbi gir rellorcil GLi SERVER FTP user sauth adduser foo bar SERVER FTP PIO _Seicwseie eS Wiser sspec setuser sspec addxmemfile test3 rabbitl gif SERVER FTP user sspec setuser sspec addxmemfile testa rabbitl gif SERVER FTP user sock_init Sto dmie NUL use default handlers tcp reserveport FTP CMDPORT Port 21 while 1 iEiefo iealelle TCP IP Manual Vol 2 rabbit com 341 Each user may execute the dir or Is command to see a l
471. y is technically part of the epilog Prolog data is lines of input that were provided before the first official part of the multi part data Most HTTP clients will not provide any prolog data Epilog data is lines of data after the last of ficial part Again HTTP clients do not usually generate it It is always safe to ignore prolog and epilog data since it is usually provided only for non MIME compliant servers Data provided when the action is CGI HEADER is a line of header data provided at the start of each part of the multi part data It is safe for the CGI to ignore header lines since the HTTP server also processes the ones that it needs The CGI is given these header lines so that it can extract use ful or customized information if desired The length of the data may be obtained using http getDataLength The CGI is allowed to overwrite data at the returned area provided that it writes no more than HTTP MAXBUFFER bytes NOTE This is implemented as a macro PARAMETER state HTTP state pointer as provided in the first parameter to the CGI function RETURN VALUE Pointer to the first character of data SEE ALSO http_getAction TCP IP Manual Vol 2 rabbit com 205 http getDataLength word http getDataLength HttpState state DESCRIPTION Return the length of data that is available It is only valid to call this if it is valid to call http getData That is if the action code is one of CGI DATA CGI_ P
472. y field or a pull down menu and if the variable should be considered read only This FormVar array is placed ina ServerSpec structure using the function sspec addform ServerSpec entries that represent variables will be added to the FormVar array using sspec_addfv Properties for these FormVar entries for example the integrity checking proper ties can be set with various other functions Hence there is a level of indirection between the variables in the forms and the actual variables themselves This allows the same variable to be included in multiple forms with different ranges for each form and perhaps be read only in one form and modifiable in another 3 1 10 SSpecFileHandle Structure This structure is used internally by Zserver and is only of interest to developers of new filesystems which may be incorporated into Zserver 3 2 Constants Used in Zserver lib The constants in this section are values assigned to the fields of the structures ServerSpec and ServerAuth They are used in the functions described in Section 3 5 some as function parameters and some as return values 3 2 1 ServerSpec Type Field This field describes the resource in the server spec list The possible values are e SSPEC XMEMFILE The data resides in xmem e SSPEC ZMEMFILE The data resides in xmem and is compressed e SSPEC ROOTFILE The data resides in root memory e SSPEC_FSFILE The data resides in an FS2 file e SSPEC_FATFILE The data resides
473. y or not at all i e the agent will only process the request if access to all of the managed objects in the variable binding is granted Read Request commit is always zero for read requests The callback is only invoked once not twice as it is for write requests Write Request When commit is equal to zero the agent is checking the availability of the managed object The callback should return zero to continue or non zero to deny access If at least one callback function denies access no change will be made to any object in the transaction and none of the callbacks will be called with commit equal to true When commit is not equal to zero the callback function should skip checking the availability of the managed object that was done the first time around and just perform the desired side effects associated with the write access The callback s return value will be ignored v Void pointer to a temporary location that may be altered by the callback If the managed object is an integer v points to a longword If it is an OID then v points to a structure of type snmp_ oid Otherwise it points to the first character of a temporary buffer containing the string len Points to the length of the string that is pointed to by v Note that this is used by the SNMP agent to determine the string length maxlen The maximum allowable length of the buffer pointed to by v 380 rabbit com SNMP RETURN VALUE The non zero return valu

Dynamic C TCP/IP Users Manual

Contents

Download Pdf Manuals

Related Search

Related Contents