add documentation, fix STL includes, remove deprecated HTTP parser methods

changelog.md

@@ -1,4 +1,7 @@
 HEAD
+- BREAKING UTILITY CHANGE: Deprecated methods `http::parser::parse_headers`,
+  `http::response::parse_complete`, and `http::request::parse_complete` have
+  been removed.
 - Security: Disabled SSLv3 in example servers.
 - Improvement: Message payload logging now prints text for text messages rather
   than binary.

websocketpp/http/impl/parser.hpp

@@ -112,28 +112,6 @@ inline bool parser::parse_parameter_list(std::string const & in,
     return (it == in.begin());
 }
 
-inline bool parser::parse_headers(std::istream & s) {
-    std::string header;
-    std::string::size_type end;
-
-    // get headers
-    while (std::getline(s, header) && header != "\r") {
-        if (header[header.size()-1] != '\r') {
-            continue; // ignore malformed header lines?
-        } else {
-            header.erase(header.end()-1);
-        }
-
-        end = header.find(header_separator,0);
-
-        if (end != std::string::npos) {
-            append_header(header.substr(0,end),header.substr(end+2));
-        }
-    }
-
-    return true;
-}
-
 inline void parser::process_header(std::string::iterator begin,
     std::string::iterator end)
 {

websocketpp/http/impl/request.hpp

@@ -29,7 +29,6 @@
 #define HTTP_PARSER_REQUEST_IMPL_HPP
 
 #include <algorithm>
-#include <istream>
 #include <sstream>
 #include <string>
 
@@ -39,33 +38,6 @@ namespace websocketpp {
 namespace http {
 namespace parser {
 
-inline bool request::parse_complete(std::istream & s) {
-    std::string req;
-
-    // get status line
-    std::getline(s, req);
-
-    if (req[req.size()-1] == '\r') {
-        req.erase(req.end()-1);
-
-        std::stringstream ss(req);
-        std::string val;
-
-        ss >> val;
-        set_method(val);
-
-        ss >> val;
-        set_uri(val);
-
-        ss >> val;
-        set_version(val);
-    } else {
-        return false;
-    }
-
-    return parse_headers(s);
-}
-
 inline size_t request::consume(char const * buf, size_t len) {
     if (m_ready) {return 0;}
 

websocketpp/http/impl/response.hpp

@@ -172,34 +172,6 @@ inline size_t response::consume(std::istream & s) {
     return total;
 }
 
-inline bool response::parse_complete(std::istream & s) {
-    // parse a complete header (ie \r\n\r\n MUST be in the input stream)
-    std::string line;
-
-    // get status line
-    std::getline(s, line);
-
-    if (line[line.size()-1] == '\r') {
-        line.erase(line.end()-1);
-
-        std::stringstream   ss(line);
-        std::string         str_val;
-        int                 int_val;
-        char                char_val[256];
-
-        ss >> str_val;
-        set_version(str_val);
-
-        ss >> int_val;
-        ss.getline(char_val,256);
-        set_status(status_code::value(int_val),std::string(char_val));
-    } else {
-        return false;
-    }
-
-    return parse_headers(s);
-}
-
 inline std::string response::raw() const {
     // TODO: validation. Make sure all required fields have been set?
 

websocketpp/http/parser.hpp

@@ -29,7 +29,6 @@
 #define HTTP_PARSER_HPP
 
 #include <algorithm>
-#include <istream>
 #include <map>
 #include <string>
 #include <utility>
@@ -500,14 +499,6 @@ public:
     bool parse_parameter_list(std::string const & in, parameter_list & out)
         const;
 protected:
-    /// Parse headers from an istream
-    /**
-     * @deprecated Use process_header instead.
-     *
-     * @param [in] s The istream to extract headers from.
-     */
-    bool parse_headers(std::istream & s);
-
     /// Process a header line
     /**
      * @todo Update this method to be exception free.

websocketpp/http/request.hpp

@@ -28,7 +28,6 @@
 #ifndef HTTP_PARSER_REQUEST_HPP
 #define HTTP_PARSER_REQUEST_HPP
 
-#include <istream>
 #include <string>
 
 #include <websocketpp/common/memory.hpp>
@@ -57,9 +56,6 @@ public:
       : m_buf(lib::make_shared<std::string>())
       , m_ready(false) {}
 
-    /// DEPRECATED parse a complete header (\r\n\r\n MUST be in the istream)
-    bool parse_complete(std::istream & s);
-
     /// Process bytes in the input buffer
     /**
      * Process up to len bytes from input buffer buf. Returns the number of

websocketpp/http/response.hpp

@@ -28,6 +28,9 @@
 #ifndef HTTP_PARSER_RESPONSE_HPP
 #define HTTP_PARSER_RESPONSE_HPP
 
+#include <iostream>
+#include <string>
+
 #include <websocketpp/http/parser.hpp>
 
 namespace websocketpp {
@@ -84,6 +87,26 @@ public:
      */
     size_t consume(char const * buf, size_t len);
 
+    /// Process bytes in the input buffer (istream version)
+    /**
+     * Process bytes from istream s. Returns the number of bytes processed. 
+     * Bytes left unprocessed means bytes left over after the final header
+     * delimiters.
+     *
+     * Consume is a streaming processor. It may be called multiple times on one
+     * response and the full headers need not be available before processing can
+     * begin. If the end of the response was reached during this call to consume
+     * the ready flag will be set. Further calls to consume once ready will be
+     * ignored.
+     *
+     * Consume will throw an http::exception in the case of an error. Typical
+     * error reasons include malformed responses, incomplete responses, and max
+     * header size being reached.
+     *
+     * @param buf Pointer to byte buffer
+     * @param len Size of byte buffer
+     * @return Number of bytes processed.
+     */
     size_t consume(std::istream & s);
 
     /// Returns true if the response is ready.
@@ -99,9 +122,6 @@ public:
         return (m_state == BODY || m_state == DONE);
     }
 
-    /// DEPRECATED parse a complete response from a pre-delimited istream
-    bool parse_complete(std::istream& s);
-
     /// Returns the full raw response
     std::string raw() const;