Modify interface to query parameters. Close fhessel#62. Close fhessel#63

Author: fhessel

examples/Parameter-Validation/Parameter-Validation.ino

@@ -1,4 +1,3 @@
-#include <Arduino.h>
 /**
  * Example for the ESP32 HTTP(S) Webserver
  *
@@ -115,13 +114,13 @@ void setup() {
   // This node will turn an LED on or of. It has two parameters:
   // 1) The ID of the LED (0..LEDCOUNT)
   // 2) The new state (0..1)
-  // For more information on URL parameters in general, see the Parameters example.
+  // For more information on path parameters in general, see the Parameters example.
   ResourceNode * nodeSwitch = new ResourceNode("/led/*/*", "POST", &handleSwitch);
 
   // We want to use parameter validation. The ResourceNode class provides the method
-  // addURLParamValidator() for that. This method takes two parameters:
+  // addPathParamValidator() for that. This method takes two parameters:
   // 1) The index of the parameter that you want to validate, so for the first wildcard
-  //    in the URL pattern that has been specified above, it's 0, and for the second
+  //    in the route pattern that has been specified above, it's 0, and for the second
   //    parameter it's 1.
   // 2) A function pointer that takes an std::string as parameter and returns a bool.
   //    That bool should be true if the parameter is considered valid.
@@ -138,14 +137,14 @@ void setup() {
 
   // First we will take care of the LED ID. This ID should be...
   // ... an unsigned integer ...
-  nodeSwitch->addURLParamValidator(0, &validateUnsignedInteger);
+  nodeSwitch->addPathParamValidator(0, &validateUnsignedInteger);
   // ... and within the range of known IDs.
   // We can treat the parameter safely as integer in this validator, as all validators
   // are executed in order and validateUnsignedInteger has been run before.
-  nodeSwitch->addURLParamValidator(0, &validateLEDID);
+  nodeSwitch->addPathParamValidator(0, &validateLEDID);
 
   // The second parameter should either be 0 or 1. We use our custom validateLEDState() validator for this:
-  nodeSwitch->addURLParamValidator(1, &validateLEDState);
+  nodeSwitch->addPathParamValidator(1, &validateLEDState);
 
   // Not found node
   ResourceNode * node404 = new ResourceNode("", "GET", &handle404);
@@ -232,13 +231,13 @@ void handleSwitch(HTTPRequest * req, HTTPResponse * res) {
   ResourceParameters * params = req->getParams();
 
   // Get the LED that is requested.
-  // Note that we can use the parameter directly without further validation, as we
+  // Note that we can call stoi safely without further validation, as we
   // defined that is has to be an unsigned integer and must not be >LEDCOUNT-1
-  LED * led = &myLEDs[params->getUrlParameterInt(0)];
+  LED * led = &myLEDs[std::stoi(params->getPathParameter(0))];
 
   // Set the state of the LED. The value of the parameter can only be "0" or "1" here,
   // otherwise the server would not have called the handler.
-  led->setOn(params->getUrlParameter(1)!="0");
+  led->setOn(params->getPathParameter(1)!="0");
 
   // Redirect the user to the main page
   res->setStatusCode(303);
@@ -257,7 +256,7 @@ bool validateLEDState(std::string s) {
 // This function is a validator for the first parameter of the POST /led route.
 // We did check before that the parameter is an integer, now we check its range.
 bool validateLEDID(std::string s) {
-  uint32_t id = parseUInt(s);
+  uint32_t id = std::stoul(s);
   return id < LEDCOUNT;
 }
 

examples/Parameters/Parameters.ino

@@ -53,7 +53,8 @@ HTTPSServer secureServer = HTTPSServer(&cert);
 // We declare some handler functions (definition at the end of the file)
 void handleRoot(HTTPRequest * req, HTTPResponse * res);
 void handleSVG(HTTPRequest * req, HTTPResponse * res);
-void handleURLParam(HTTPRequest * req, HTTPResponse * res);
+void handleQueryDemo(HTTPRequest * req, HTTPResponse * res);
+void handlePathParam(HTTPRequest * req, HTTPResponse * res);
 void handle404(HTTPRequest * req, HTTPResponse * res);
 
 void setup() {
@@ -72,27 +73,31 @@ void setup() {
 
   // For every resource available on the server, we need to create a ResourceNode
   // The ResourceNode links URL and HTTP method to a handler function
-  ResourceNode * nodeRoot     = new ResourceNode("/", "GET", &handleRoot);
-  ResourceNode * nodeSVG      = new ResourceNode("/images/awesome.svg", "GET", &handleSVG);
-  ResourceNode * node404      = new ResourceNode("", "GET", &handle404);
+  ResourceNode * nodeRoot      = new ResourceNode("/", "GET", &handleRoot);
+  ResourceNode * nodeSVG       = new ResourceNode("/images/awesome.svg", "GET", &handleSVG);
+  ResourceNode * nodeQueryDemo = new ResourceNode("/queryparams", "GET", &handleQueryDemo);
+  ResourceNode * node404       = new ResourceNode("", "GET", &handle404);
 
-  // URL params
+  // Path parameters
   // If you want (for example) to return a specific instance of an object type by its ID
   // you can use URLs like /led/1, led/2, ... - And you do not need to register one Resource
-  // Node per ID, but you can use wildcards in the URL definition. The following function
-  // has to wildcards, and will match for example to /urlparam/foo/bar, where "foo" and "bar"
+  // Node per ID, but you can use wildcards in the route definition. The following route
+  // has two wildcards, and will match for example to /urlparam/foo/bar, where "foo" and "bar"
   // are accessible parameters in the handler function.
   // Note: The wildcards can only be used between slashes at the moment (so /urlparam* would
   // not work).
-  ResourceNode * nodeURLParam = new ResourceNode("/urlparam/*/*", "GET", &handleURLParam);
+  ResourceNode * nodeURLParam = new ResourceNode("/urlparam/*/*", "GET", &handlePathParam);
 
   // Add the root node to the server
   secureServer.registerNode(nodeRoot);
 
   // Add the SVG image
   secureServer.registerNode(nodeSVG);
 
-  // Add the URL param node
+  // Query parameter demo
+  secureServer.registerNode(nodeQueryDemo);
+
+  // Add the path parameter
   // Note: The order of nodes may become important here. If you have one node for "/led" (e.g. list of LEDs)
   // and one node for /led/* (LED details), you should register the non-parameterized version first. The server
   // follows a first-match policy. If you would register the details node first, a call to /led/ will be targetted
@@ -126,9 +131,11 @@ void handleRoot(HTTPRequest * req, HTTPResponse * res) {
   res->println("<!DOCTYPE html>");
   res->println("<html>");
   res->println("<head><title>Hello World!</title></head>");
+  res->println("<style>.info{font-style:italic}</style>");
   res->println("<body>");
 
-  res->println("<h1>GET parameters</h1>");
+  res->println("<h1>Query Parameters</h1>");
+  res->println("<p class=\"info\">The parameters after the question mark in your URL.</p>");
 
   // Show a form to select a color to colorize the faces
   // We pass the selection as get parameter "shades" to this very same page,
@@ -158,8 +165,8 @@ void handleRoot(HTTPRequest * req, HTTPResponse * res) {
     // Depending on the selection we show the images in a specific color shade
     // Default is dark gray.
     int r = 63, g = 63, b = 63;
-    if (params->isRequestParameterSet(paramName)) {
-      std::string paramVal = params->getRequestParameter(paramName);
+    std::string paramVal;
+    if (params->getQueryParameter(paramName, paramVal)) {
       if (paramVal == "red" || paramVal == "magenta" || paramVal == "yellow" || paramVal == "rainbow") {
         r = 128 + random(0, 128);
       }
@@ -178,19 +185,21 @@ void handleRoot(HTTPRequest * req, HTTPResponse * res) {
 
     res->print("\" alt=\"Awesome!\" />");
   }
+  res->println("<p>You'll find another demo <a href=\"/queryparams?a=42&b&c=13&a=hello\">here</a>.</p>");
 
-  // Link to the URL parameter demo
-  res->println("<h1>URL parameters</h1>");
+  // Link to the path parameter demo
+  res->println("<h1>Path Parameters</h1>");
+  res->println("<p class=\"info\">The parameters derived from placeholders in your path, like /foo/bar.</p>");
   res->println("<p>You'll find the demo <a href=\"/urlparam/foo/bar\">here</a>.</p>");
 
   res->println("</body>");
   res->println("</html>");
 }
 
-// This callback responds with an SVG image to a GET request. The icon is the awesome face.
+// This callback responds with an SVG image to a GET request. The icon is the "awesome face".
 // (borrowed from https://commons.wikimedia.org/wiki/File:718smiley.svg)
 //
-// If the color request parameter is set (so the URL is like awesome.svg?color=fede58), the
+// If the color query parameter is set (so the URL is like awesome.svg?color=fede58), the
 // background of our awesome face is changed.
 void handleSVG(HTTPRequest * req, HTTPResponse * res) {
   // Get access to the parameters
@@ -205,10 +214,11 @@ void handleSVG(HTTPRequest * req, HTTPResponse * res) {
   // Get request parameter (like awesome.svg?color=ff0000) and validate it
   std::string colorParamName = "color";
 
-  // Check that the parameter is set
-  if (params->isRequestParameterSet(colorParamName)) {
-    // Get the value of the parameter
-    std::string requestColor = params->getRequestParameter(colorParamName);
+  // Check that the parameter is set and retrieve it.
+  // The getQueryParameter function will modify the second parameter, but only if the query
+  // parameter is set.
+  std::string requestColor;
+  if (params->getQueryParameter(colorParamName, requestColor)) {
     // Check for correct length
     if (requestColor.length()==6) {
       bool colorOk = true;
@@ -247,10 +257,58 @@ void handleSVG(HTTPRequest * req, HTTPResponse * res) {
   res->print("</svg>");
 }
 
+// This is a more generic demo for the query parameters. It makes use of the iterator
+// interface to access them, which is useful if you do not know the paramter names in
+// adavance.
+void handleQueryDemo(HTTPRequest * req, HTTPResponse * res) {
+  // A word of warning: In this example, we use the query parameters and directly print
+  // them into the HTML output. We do this to simplify the demo. NEVER do this in a
+  // real application, as it allows cross-site-scripting.
+  res->setHeader("Content-Type", "text/html");
+
+  res->println("<!DOCTYPE html>");
+  res->println("<html>");
+  res->println("<head>");
+  res->println("<title>Query Parameter Demo</title>");
+  res->println("</head>");
+  res->println("<body>");
+  res->println("<p>The following query paramters have been set:</p>");
+  
+  // Start a table to display the parameters
+  res->println("<table style=\"border:1px solid black collapse;\">");
+  res->println("<tr><th>Key</th><th>Value</th></tr>");
+  // Iterate over the parameters. For more information, read about the C++ standard template library, 
+  // especially about vectors and iterators.
+  ResourceParameters *params = req->getParams();
+  for(auto it = params->beginQueryParameters(); it != params->endQueryParameters(); ++it) {
+    res->print("<tr><td>");
+    
+    // The iterator yields std::pairs of std::strings. The first value contains the parameter key
+    res->printStd((*it).first);
+    res->print("</td><td>");
+
+    // and the second value contains the parameter value
+    res->printStd((*it).second);
+    res->println("</td></tr>");
+  }
+  res->println("</table>");
+
+  // You can retrieve the total parameter count from the parameters instance:
+  res->print("<p>There are a total of ");
+  res->print(params->getQueryParameterCount());
+  res->print(" parameters, with ");
+  res->print(params->getQueryParameterCount(true));
+  res->println(" unique keys.</p>");
+
+  res->println("<p>Go <a href=\"/\">back to main page</a>.</p>");
+  res->println("</body>");
+  res->println("</html>");
+}
+
 // This is a simple handler function that will show the content of URL parameters.
 // If you call for example /urlparam/foo/bar, you will get the parameter values
 // "foo" and "bar" provided by the ResourceParameters.
-void handleURLParam(HTTPRequest * req, HTTPResponse * res) {
+void handlePathParam(HTTPRequest * req, HTTPResponse * res) {
   // Get access to the parameters
   ResourceParameters * params = req->getParams();
 
@@ -260,19 +318,26 @@ void handleURLParam(HTTPRequest * req, HTTPResponse * res) {
   // The url pattern is: /urlparam/*/*
   // This will make the content for the first parameter available on index 0,
   // and the second wildcard as index 1.
+  // getPathParameter will - like getQueryParameter - write the value to the second parameter,
+  // and return true, if the index is valid. Otherwise it returns false and leaves the second
+  // parameter as it is.
 
+  std::string parameter1, parameter2;
   // Print the first parameter value
-  res->print("Parameter 1: ");
-  res->printStd(params->getUrlParameter(0));
+  if (params->getPathParameter(0, parameter1)) {
+    res->print("Parameter 1: ");
+    res->printStd(parameter1);
+  }
+
+  res->println();
 
   // Print the second parameter value
-  res->print("\nParameter 2: ");
-  res->printStd(params->getUrlParameter(1));
+  if (params->getPathParameter(1, parameter2)) {
+    res->print("Parameter 2: ");
+    res->printStd(parameter2);
+  }
 
   res->println("\n\nChange the parameters in the URL to see how they get parsed!");
-
-  // Note: If you have objects that are identified by an ID, you may also use
-  // ResourceParameters::getUrlParameterInt(int) for convenience
 }
 
 // For details to this function, see the Static-Page example

examples/REST-API/REST-API.ino

@@ -78,6 +78,16 @@ char contentTypes[][2][32] = {
 #include <HTTPResponse.hpp>
 #include <util.hpp>
 
+// The HTTPS Server comes in a separate namespace. For easier use, include it here.
+using namespace httpsserver;
+
+SSLCert * getCertificate();
+void handleSPIFFS(HTTPRequest * req, HTTPResponse * res);
+void handleGetUptime(HTTPRequest * req, HTTPResponse * res);
+void handleGetEvents(HTTPRequest * req, HTTPResponse * res);
+void handlePostEvent(HTTPRequest * req, HTTPResponse * res);
+void handleDeleteEvent(HTTPRequest * req, HTTPResponse * res);
+
 // We use the following struct to store GPIO events:
 #define MAX_EVENTS 20
 struct {
@@ -91,9 +101,6 @@ struct {
   int state;
 } events[MAX_EVENTS];
 
-// The HTTPS Server comes in a separate namespace. For easier use, include it here.
-using namespace httpsserver;
-
 // We just create a reference to the server here. We cannot call the constructor unless
 // we have initialized the SPIFFS and read or created the certificate
 HTTPSServer * secureServer;
@@ -504,7 +511,7 @@ void handlePostEvent(HTTPRequest * req, HTTPResponse * res) {
 void handleDeleteEvent(HTTPRequest * req, HTTPResponse * res) {
   // Access the parameter from the URL. See Parameters example for more details on this
   ResourceParameters * params = req->getParams();
-  uint16_t eid = params->getUrlParameterInt(0);
+  size_t eid = std::atoi(params->getPathParameter(0).c_str());
 
   if (eid < MAX_EVENTS) {
     // Set the inactive flag

src/HTTPConnection.cpp

@@ -612,8 +612,12 @@ void validationMiddleware(HTTPRequest * req, HTTPResponse * res, std::function<v
   // Iterate over the validators and run them
   std::vector<HTTPValidator*> * validators = node->getValidators();
   for(std::vector<HTTPValidator*>::iterator validator = validators->begin(); valid && validator != validators->end(); ++validator) {
-    std::string param = params->getUrlParameter((*validator)->_idx);
-    valid = ((*validator)->_validatorFunction)(param);
+    std::string param;
+    if (params->getPathParameter((*validator)->_idx, param)) {
+      valid = ((*validator)->_validatorFunction)(param);
+    } else {
+      valid = false;
+    }
   }
 
   if (valid) {

src/HTTPNode.cpp

@@ -11,29 +11,29 @@ namespace httpsserver {
     _validators = new std::vector<HTTPValidator*>();
 
     // Count the parameters
-    _urlParamCount = 0;
+    _pathParamCount = 0;
     size_t idx = 0;
     while((idx = path.find("/*", idx)) != std::string::npos) {
-      _urlParamCount+=1;
+      _pathParamCount+=1;
       // If we don't do this, the same index will be found again... and again... and again...
       idx+=1;
     };
 
     // Check if there are parameters
-    if (_urlParamCount > 0) {
+    if (_pathParamCount > 0) {
       // If there are parameters, store their indices
-      _urlParamIdx = new size_t[_urlParamCount];
-      for(int i = 0; i < _urlParamCount; i++) {
-        _urlParamIdx[i] = path.find("/*", i==0 ? 0 : _urlParamIdx[i-1])+1;
+      _pathParamIdx = new size_t[_pathParamCount];
+      for(int i = 0; i < _pathParamCount; i++) {
+        _pathParamIdx[i] = path.find("/*", i==0 ? 0 : _pathParamIdx[i-1])+1;
       }
     } else {
-      _urlParamIdx = NULL;
+      _pathParamIdx = NULL;
     }
   }
 
   HTTPNode::~HTTPNode() {
-    if (_urlParamIdx != NULL) {
-      delete[] _urlParamIdx;
+    if (_pathParamIdx != NULL) {
+      delete[] _pathParamIdx;
     }
 
     // Delete validator references
@@ -43,23 +43,23 @@ namespace httpsserver {
     delete _validators;
   }
 
-  bool HTTPNode::hasUrlParameter() {
-    return _urlParamCount > 0;
+  bool HTTPNode::hasPathParameter() {
+    return _pathParamCount > 0;
   }
 
   size_t HTTPNode::getParamIdx(uint8_t idx) {
-    if (idx<_urlParamCount) {
-      return _urlParamIdx[idx];
+    if (idx<_pathParamCount) {
+      return _pathParamIdx[idx];
     } else {
       return -1;
     }
   }
 
-  uint8_t HTTPNode::getUrlParamCount() {
-    return _urlParamCount;
+  size_t HTTPNode::getPathParamCount() {
+    return _pathParamCount;
   }
 
-  void HTTPNode::addURLParamValidator(uint8_t paramIdx, const HTTPValidationFunction * validator) {
+  void HTTPNode::addPathParamValidator(size_t paramIdx, const HTTPValidationFunction * validator) {
     _validators->push_back(new HTTPValidator(paramIdx, validator));
   }
 

src/HTTPNode.hpp

@@ -43,8 +43,8 @@ class HTTPNode {
   /** Stores the type of the node (as we have not runtime type information by default) */
   const HTTPNodeType _nodeType;
 
-  bool hasUrlParameter();
-  uint8_t getUrlParamCount();
+  bool hasPathParameter();
+  size_t getPathParamCount();
   size_t getParamIdx(uint8_t);
 
   std::vector<HTTPValidator*> * getValidators();
@@ -58,11 +58,11 @@ class HTTPNode {
    * 
    * @see ValidatorFunctions.hpp if you need some predefined templates for functions
    */
-  void addURLParamValidator(uint8_t paramIdx, const HTTPValidationFunction * validator);
+  void addPathParamValidator(size_t paramIdx, const HTTPValidationFunction * validator);
 
 private:
-  uint8_t _urlParamCount;
-  size_t * _urlParamIdx;
+  size_t _pathParamCount;
+  size_t * _pathParamIdx;
   std::vector<HTTPValidator*> * _validators;
 };
 

src/ResourceParameters.cpp

@@ -10,66 +10,157 @@ ResourceParameters::~ResourceParameters() {
 
 }
 
-bool ResourceParameters::isRequestParameterSet(std::string const &name) {
-  for(auto reqParam = _reqParams.begin(); reqParam != _reqParams.end(); ++reqParam) {
-    if ((*reqParam).first.compare(name)==0) {
+/**
+ * @brief Checks whether a specific HTTPS query parameter is set.
+ * 
+ * Query parameters are key-value pairs that are appended to the URI after a question mark.
+ * 
+ * If the key exists (either as a value-less parameter or with a value), the function returns true.
+ * 
+ * @param name The parameter to check
+ * @return true iff the parameter exists
+ */
+bool ResourceParameters::isQueryParameterSet(std::string const &name) {
+  for(auto queryParam = _queryParams.begin(); queryParam != _queryParams.end(); ++queryParam) {
+    if ((*queryParam).first.compare(name)==0) {
       return true;
     }
   }
   return false;
 }
 
-std::string ResourceParameters::getRequestParameter(std::string const &name) {
-  for(auto reqParam = _reqParams.begin(); reqParam != _reqParams.end(); ++reqParam) {
-    if ((*reqParam).first.compare(name)==0) {
-      return (*reqParam).second;
+/**
+ * @brief Returns an HTTP query parameter.
+ * 
+ * Query parameters are key-value pairs that are appended to the URI after a question mark.
+ * 
+ * The name parameter specifies the name of the query parameter to retrieve. If it is set,
+ * the value is written to the value parameter and true is returned. If the parameter does
+ * not exist, value is left unchanged and false is returned. If the parameter is used
+ * without a value, an empty string is written to value and true is returned.
+ * 
+ * @param name The name of the parameter to retrieve. If the parameter exists multiple times,
+ * the first occurence is used for the value. Use beginQueryParameters() to retrieve all values.
+ * @param value The target to write the value to, if the parameter exists.
+ * @return true iff the parameter exists and the corresponding value has been written.
+ */
+bool ResourceParameters::getQueryParameter(std::string const &name, std::string &value) {
+  for(auto queryParam = _queryParams.begin(); queryParam != _queryParams.end(); ++queryParam) {
+    if ((*queryParam).first.compare(name)==0) {
+      value=(*queryParam).second;
+      return true;
     }
   }
-  return "";
+  return false;
+}
+
+/**
+ * @brief Returns the number of query parameters.
+ * 
+ * Query parameters are key-value pairs that are appended to the URI after a question mark.
+ * 
+ * @param unique If true, return the number of unique keys (using the same key multiple times
+ * is counted only once). False by default, as checking for uniqueness is not efficient.
+ * @return Number of query parameters
+ */
+size_t ResourceParameters::getQueryParameterCount(bool unique) {
+  if (!unique) {
+    return _queryParams.size();
+  }
+  size_t count = 0;
+  for(auto a = _queryParams.begin(); a != _queryParams.end(); ++a) {
+    bool exists = false;
+    for(auto b = _queryParams.begin(); !exists && b != a; ++b) {
+      exists = (*a).first.compare((*b).first)==0;
+    }
+    count += exists ? 0 : 1;
+  }
+  return count;
 }
 
-uint16_t ResourceParameters::getRequestParameterInt(std::string const &name) {
-  return parseInt(getRequestParameter(name));
+/**
+ * @brief Provides iterator access to the query parameters
+ * 
+ * Query parameters are key-value pairs that are appended to the URI after a question mark.
+ * 
+ * If you want just a specific parameter, have a look at getQueryParameter()
+ * 
+ * The iterator will yield pairs of std::string, of which the first value specifies the
+ * query parameter key and the second value corresponds to the query parameters value.
+ * If the entry is value-less, the second value will be the empty string.
+ * 
+ * If the same key is used multiple times in the query, the iterator will yield it multiple
+ * times, once for each occurence with the specific value.
+ * 
+ * @return Iterator over std::pairs of std::strings that represent (key, value) pairs
+ */
+std::vector<std::pair<std::string,std::string>>::iterator ResourceParameters::beginQueryParameters() {
+  return _queryParams.begin();
+}
+
+/**
+ * @brief Counterpart to beginQueryParameters() for iterating over query parameters
+ */
+std::vector<std::pair<std::string,std::string>>::iterator ResourceParameters::endQueryParameters() {
+  return _queryParams.end();
 }
 
-void ResourceParameters::setRequestParameter(std::string const &name, std::string const &value) {
+void ResourceParameters::setQueryParameter(std::string const &name, std::string const &value) {
   std::pair<std::string, std::string> param;
   param.first = name;
   param.second = value;
-  _reqParams.push_back(param);
+  _queryParams.push_back(param);
 }
 
 /**
- * Returns an URL parameter as string.
+ * @brief Checks for the existence of a path parameter and returns it as string.
  *
- * URL parameters are defined by resource nodes like object/?/property
- *
- * The parameter idx defines the index of the parameter, starting with 0.
+ * Path parameters are defined by an asterisk as placeholder when specifying the path of
+ * the ResourceNode and addressed by an index starting at 0 for the first parameter.
+ * 
+ * For values of idx that have no matching placeholder, value is left unchanged and the
+ * method will return false.
+ * 
+ * @param idx Defines the index of the parameter to return, starting with 0.
+ * @param value The value is written into this parameter.
+ * @return true iff the value could be written.
  */
-std::string ResourceParameters::getUrlParameter(uint8_t idx) {
-  return _urlParams.at(idx);
+bool ResourceParameters::getPathParameter(size_t const idx, std::string &value) {
+  if (idx < _pathParams.size()) {
+    value = _pathParams.at(idx);
+    return true;
+  }
+  return false;
 }
 
 /**
- * Returns an URL parameter as int.
+ * @brief Directly returns a path parameter
  *
- * URL parameters are defined by resource nodes like object/?/property
- *
- * The parameter idx defines the index of the parameter, starting with 0.
+ * Path parameters are defined by an asterisk as placeholder when specifying the path of
+ * the ResourceNode and addressed by an index starting at 0 for the first parameter.
+ * 
+ * This method will return the parameter specified by the index. The caller is responsible
+ * to assure that the index exists. Otherwise, an empty string will be returned.
+ * 
+ * @param idx Defines the index of the parameter to return, starting with 0.
+ * @return the value of the placeholder
  */
-uint16_t ResourceParameters::getUrlParameterInt(uint8_t idx) {
-  return parseInt(getUrlParameter(idx));
+std::string ResourceParameters::getPathParameter(size_t const idx) {
+  if (idx < _pathParams.size()) {
+    return _pathParams.at(idx);
+  }
+  return "";
 }
 
-void ResourceParameters::resetUrlParameters() {
-  _urlParams.clear();
+void ResourceParameters::resetPathParameters() {
+  _pathParams.clear();
 }
 
-void ResourceParameters::setUrlParameter(uint8_t idx, std::string const &val) {
-  if(idx>=_urlParams.capacity()) {
-    _urlParams.resize(idx + 1);
+void ResourceParameters::setPathParameter(size_t idx, std::string const &val) {
+  if(idx>=_pathParams.capacity()) {
+    _pathParams.resize(idx + 1);
   }
-  _urlParams.at(idx) = val;
+  _pathParams.at(idx) = val;
 }
 
 } /* namespace httpsserver */

src/ResourceParameters.hpp

@@ -14,30 +14,44 @@
 
 namespace httpsserver {
 
-struct requestparam_t {std::string name; std::string value;};
+class ResourceResolver;
 
 /**
- * \brief Class used to handle access to the URL parameters
+ * @brief The ResourceParameters provide access to the parameters passed in the URI.
+ * 
+ * There are two types of parameters: Path parameters and query parameters.
+ * 
+ * Path parameters are the values that fill the asterisk placeholders in the route
+ * definition of a ResourceNode.
+ * 
+ * Query parameters are the key-value pairs after a question mark which can be added
+ * to each request, either by specifying them manually or as result of submitting an
+ * HTML form with a GET as method property.
  */
 class ResourceParameters {
 public:
   ResourceParameters();
   virtual ~ResourceParameters();
 
-  bool isRequestParameterSet(std::string const &name);
-  std::string getRequestParameter(std::string const &name);
-  uint16_t getRequestParameterInt(std::string const &name);
-  void setRequestParameter(std::string const &name, std::string const &value);
+  bool isQueryParameterSet(std::string const &name);
+  bool getQueryParameter(std::string const &name, std::string &value);
+  std::vector<std::pair<std::string,std::string>>::iterator beginQueryParameters();
+  std::vector<std::pair<std::string,std::string>>::iterator endQueryParameters();
+  size_t getQueryParameterCount(bool unique=false);
+  bool getPathParameter(size_t const idx, std::string &value);
+  std::string getPathParameter(size_t const idx);
 
-  std::string getUrlParameter(uint8_t idx);
-  uint16_t getUrlParameterInt(uint8_t idx);
-  void resetUrlParameters();
-  void setUrlParameterCount(uint8_t idx);
-  void setUrlParameter(uint8_t idx, std::string const &val);
+protected:
+  friend class ResourceResolver;
+  void setQueryParameter(std::string const &name, std::string const &value);
+  void resetPathParameters();
+  void setPathParameter(size_t idx, std::string const &val);
 
 private:
-  std::vector<std::string> _urlParams;
-  std::vector<std::pair<std::string, std::string>> _reqParams;
+  /** Parameters in the path of the URL, the actual values for asterisk placeholders */
+  std::vector<std::string> _pathParams;
+  /** HTTP Query parameters, as key-value pairs */
+  std::vector<std::pair<std::string, std::string>> _queryParams;
 };
 
 } /* namespace httpsserver */

src/ResourceResolver.cpp

@@ -62,7 +62,7 @@ void ResourceResolver::resolveNode(const std::string &method, const std::string
       }
 
       // Now we finally have name and value.
-      params->setRequestParameter(name, value);
+      params->setQueryParameter(name, value);
 
       // Update reqparamIdx
       reqparamIdx = nextparamIdx;
@@ -73,7 +73,7 @@ void ResourceResolver::resolveNode(const std::string &method, const std::string
 
   // Check whether a resource matches
   for(std::vector<HTTPNode*>::iterator node = _nodes->begin(); node != _nodes->end(); ++node) {
-    params->resetUrlParameters();
+    params->resetPathParameters();
     if ((*node)->_nodeType==nodeType) {
       if (
         // For handler functions, check the method declared with the node
@@ -82,7 +82,7 @@ void ResourceResolver::resolveNode(const std::string &method, const std::string
         ((*node)->_nodeType==WEBSOCKET && method=="GET")
       ) {
         const std::string nodepath = ((*node)->_path);
-        if (!((*node)->hasUrlParameter())) {
+        if (!((*node)->hasPathParameter())) {
           HTTPS_LOGD("Testing simple match on %s", nodepath.c_str());
 
           // Simple matching, the node does not contain any resource parameters
@@ -98,7 +98,7 @@ void ResourceResolver::resolveNode(const std::string &method, const std::string
           bool didMatch = true;
           size_t urlIdx = 0; // Pointer how far the input url is processed
           size_t nodeIdx = 0; // Pointer how far the node url is processed
-          for (int pIdx = 0; didMatch && pIdx < (*node)->getUrlParamCount(); pIdx++) {
+          for (int pIdx = 0; didMatch && pIdx < (*node)->getPathParamCount(); pIdx++) {
             size_t pOffset = (*node)->getParamIdx(pIdx);
 
             // First step: Check static part
@@ -115,15 +115,15 @@ void ResourceResolver::resolveNode(const std::string &method, const std::string
               // Second step: Grab the parameter value
               if (nodeIdx == nodepath.length()) {
                 // Easy case: parse until end of string
-                params->setUrlParameter(pIdx, urlDecode(resourceName.substr(urlIdx)));
+                params->setPathParameter(pIdx, urlDecode(resourceName.substr(urlIdx)));
               } else {
                 // parse until first char after the placeholder
                 char terminatorChar = nodepath[nodeIdx];
                 size_t terminatorPosition = resourceName.find(terminatorChar, urlIdx);
                 if (terminatorPosition != std::string::npos) {
                   // We actually found the terminator
                   size_t dynamicLength = terminatorPosition-urlIdx;
-                  params->setUrlParameter(pIdx, urlDecode(resourceName.substr(urlIdx, dynamicLength)));
+                  params->setPathParameter(pIdx, urlDecode(resourceName.substr(urlIdx, dynamicLength)));
                   urlIdx = urlIdx + dynamicLength;
                 } else {
                   // We did not find the terminator
@@ -164,7 +164,7 @@ void ResourceResolver::resolveNode(const std::string &method, const std::string
 
   // If the resource did not match, configure the default resource
   if (!resolvedResource.didMatch() && _defaultNode != NULL) {
-    params->resetUrlParameters();
+    params->resetPathParameters();
     resolvedResource.setMatchingNode(_defaultNode);
   }