diff --git a/README.md b/README.md index da62bb1..3f8e9ba 100644 --- a/README.md +++ b/README.md @@ -91,12 +91,6 @@ You should have a working webserver now. ## WRITING CODE FOR THE WEBSERVER ## -See programming.md - -## CHANGE FROM SDK 0.9.3 (and earlier) TO SDK 0.9.4 (and later): ## -Change all occurences of `espconn_sent(connData->conn, (uint8 *)buff, len);` to -`httpdSend(connData, buff, len)` please. The reason for this is that you can't do multiple -espconn_sent calls serially anymore, so httpd needs to buffer the writes now. This is only -needed in your own code; the code that comes with httpd already has this changed. +Please see the README.md of the libesphttpd project for the programming manual. diff --git a/libesphttpd b/libesphttpd index bca6680..ef76587 160000 --- a/libesphttpd +++ b/libesphttpd @@ -1 +1 @@ -Subproject commit bca6680983172609537e5cb9a542a5c63af3d489 +Subproject commit ef76587040b8fde3e36a01dcad889ce44a6ac354 diff --git a/programming.md b/programming.md deleted file mode 100644 index 43a482c..0000000 --- a/programming.md +++ /dev/null @@ -1,112 +0,0 @@ -# Intro to esphttpd developement # - -(Thanks to escardin, who wrote this.) - - -user_main.c and cgi.c provide good examples of setting up the webserver, processing input and output. - -## Setting up httpd ## -You need to define a list of urls and callbacks for those urls for processing input and transforming output. -At minimum, it must end with a NULL url. -The list is processed top to bottom, so it is best if wildcards are handled at the bottom. -Example: -HttpdBuiltInUrl builtInUrls[]={ - {"/", cgiRedirect, "/index.tpl"}, - {"/led.tpl", cgiEspFsTemplate, tplLed}, - {"/index.tpl", cgiEspFsTemplate, tplCounter}, - {"/led.cgi", cgiLed, NULL}, - {"*", cgiEspFsHook, NULL}, //Catch-all cgi function for the filesystem - {NULL, NULL, NULL} -}; - -The contents of each field is explained in URLs, CGI Callback and TPL Callback further down. - -If you plan on using serial logging, you need to include stdout.c & stdout.h and call stdoutInit() before starting the httpd. - -If you plan on serving up any templates or files, you need to call espFsInit. It is recommended to just place the following code unless you know what you're doing: - -// 0x40200000 is the base address for spi flash memory mapping, ESPFS_POS is the position -// where image is written in flash that is defined in Makefile. -#ifdef ESPFS_POS - espFsInit((void*)(0x40200000 + ESPFS_POS)); -#else - espFsInit((void*)(webpages_espfs_start)); -#endif - -You should now call any other initialization routines you may need. - -Now, call httpdInit() with the list of urls you created earlier and the port you wish httpd to listen on. - -## URLs ## -Urls are relative to the url root and must begin with a /, unless they are *. -A * is a wildcard and will match anything from the * onwards. -The * MUST be the last character in the url pattern to be a wildcard! -Examples: -'*' will match: '/', '/stuff', 'things', '/widgets.tpl' -'/stuff*' will match: '/stuff', '/stuff/', '/stuff/widgets.tpl', '/stuff.html' - -## CGI Callback ## -The specified cgi callback is called when the url it is tied to matches. -It is passed a pointer to the connection (HttpdConnData). -It returns one of HTTPD_CGI_MORE, HTTPD_CGI_DONE, HTTPD_CGI_NOTFOUND, HTTPD_CGI_AUTHENTICATED. If one of these is not returned, it will retry this url again (probably infinitely). -HTTPD_CGI_MORE means it has handled the request, but is not done sending data yet. -HTTPD_CGI_DONE means it has handled the request and is done sending data. -HTTPD_CGI_NOTFOUND and HTTPD_CGI_AUTHENTICATED means that it has not handled the request, and the url matching should continue with the next entry. - -## TPL Callback ## -The specified tpl callback is called for every token in the calling tpl file, as well as when the connection is aborted (token will be null). -It is passed a pointer to the connection data (HttpdConnData), a string token, and arguments. -If token is null, assume that the connection has died and it is time to clean up. -A token is the contents between two %. I.e. %ledstate% or %counter%. -It is the responisbility of the callback to write what should replace the token using httpdSend(); -The TPL Callback is only used (so far) if you set the CGI Callback to 'cgiEspFsTemplate'. -The return callback for TPL is not currently used, and should return one of HTTPD_CGI_MORE, HTTPD_CGI_DONE, HTTPD_CGI_NOTFOUND, HTTPD_CGI_AUTHENTICATED, though the use of each value is undefined at this time. - -## USEFUL BUILTIN FUNCTIONS ## - -base64_decode (base64.h): TODO describe how to use this - -captdnsInit (captdns.h): - - Creates a captive dns portal listening on the default ap network - -Serving files: - - espFsInit (espfs.h): Initializes access to the espfs block of flash. See above for basic usage, not recommended to mess around. - - espFsFlags (espfs.h): returns the flags for an opened file - - espFsRead (espfs.h): Read len bytes from file into buffer. Returns actual number of bytes read - - espFsClose (espfs.h): Close the file - - espFsOpen (espfs.h): open a file and return the file handle - -CGI Callbacks - - cgiEspFsHook (httpdespfs.h): attempts to read out the requested file as is (no template processing) - - cgiEspFsTemplate (httpdespfs.h): attempts to read out the requested file, with template processing (using the cgiArg tpl callback) - - cgiRedirect (httpd.h): Redirect to the url specified as a cgiArg (string) - - cgiRedirectToHostname (httpd.h): Redirect to the given http url, if it doesn't match the request url - - cgiRedirectApClientToHostname (httpd.h): Same as cgiRedirectToHostname, but only redirects if in the AP ip range - - authBasic (auth.h): performs http basic auth from the cgiArg callback function - - int cgiArg(HttpdConnData connData, int userIndex,char *userOut,int userOutLength, char *passOut,int passOutLength) - - return 1 if an entry at userIndex was found (with the username and password in userOut and passOut respectively) - - return 0 if no entry at userIndex was found (will cause authBasic to stop processing) - - OTA Firmware Updating - - cgiReadFlash (cgiflash.h): returns the first 512Kbyte of firmware - - cgiGetFirmwareNext (cgiflash.h): Returns which firmware should be uploaded next - - cgiUploadFirmware (cgiflash.h): replace firmware with POSTed firmware, after some basic validation - - cgiRebootFirmware (cgiflash.h): reboot after firmware finishes uploading? - - OTA Wifi Setup - - cgiWiFiScan (cgiwifi.h): Initiate a scan for wifi access points, and return the status/result as JSON - - tplWlan (cgiwifi.h): Template processor for the httpd demo template page - - cgiWiFi (cgiwifi.h): not implemented? - - cgiWiFiConnect (cgiwifi.h): Connect to the specified essid using the passwd provided - - cgiWiFiSetMode (cgiwifi.h): Set the esp8266 wifi mode (AP, Station, AP+Station) and reboot - - cgiWiFiConnStatus (cgiwifi.h): Return the station connection status as JSON - -Working with HTTP - - httpdRedirect (httpd.h): issue a 302 redirect to the given url - - httpdUrlDecode (httpd.h): decodes a percent encoded url - - httpdFindArg (httpd.h): finds the specified argument in the get or post data, and returns the percent decoded version of it - - httpdInit (httpd.h): Starts an http server on the given port for the given urls - - httpdGetMimetype (httpd.h): returns the mimetype based on the url extension - - httpdStartResponse (httpd.h): start http response (must be called first, and only once) - - httpdHeader (httpd.h): sends a particular http response header - - httpdEndHeaders (httpd.h): completes sending headers (no more headers may be sent) - - httpdGetHeader (httpd.h): retrieves a specific request header - - httpdSend (httpd.h): add data to be sent to the user, returns 1 for success, 0 for out of memory