From 3a43986d9e4a716aebeeb0514646fa0b902c2ca8 Mon Sep 17 00:00:00 2001 From: Peter Thorson Date: Sun, 9 Jun 2013 14:58:32 -0500 Subject: [PATCH] add documentation & normalize code style --- websocketpp/common/functional.hpp | 2 +- websocketpp/connection.hpp | 14 +-- websocketpp/http/impl/parser.hpp | 142 ++++++++++++++++++++++++------ websocketpp/http/impl/request.hpp | 9 +- 4 files changed, 129 insertions(+), 38 deletions(-) diff --git a/websocketpp/common/functional.hpp b/websocketpp/common/functional.hpp index 1261ad685d..682df600ed 100644 --- a/websocketpp/common/functional.hpp +++ b/websocketpp/common/functional.hpp @@ -54,7 +54,7 @@ namespace lib { using boost::bind; using boost::ref; namespace placeholders { - // TODO: there has got to be a better way than this + /// \todo this feels hacky, is there a better way? using ::_1; using ::_2; } diff --git a/websocketpp/connection.hpp b/websocketpp/connection.hpp index b2c6ee0677..5d63337356 100644 --- a/websocketpp/connection.hpp +++ b/websocketpp/connection.hpp @@ -399,7 +399,7 @@ public: * and then added * * Errors are returned via an exception - * TODO: make exception system_error rather than error_code + * \todo make exception system_error rather than error_code * * This method invokes the m_write_lock mutex * @@ -871,7 +871,7 @@ public: /// Checks if there are frames in the send queue and if there are sends one /** - * TODO: unit tests + * \todo unit tests * * This method locks the m_write_lock mutex */ @@ -879,7 +879,7 @@ public: /// Process the results of a frame write operation and start the next write /** - * TODO: unit tests + * \todo unit tests * * This method locks the m_write_lock mutex * @@ -1011,7 +1011,7 @@ private: * * Must be called while holding m_write_lock * - * TODO: unit tests + * \todo unit tests * * @param msg The message to push */ @@ -1024,7 +1024,7 @@ private: * * Must be called while holding m_write_lock * - * TODO: unit tests + * \todo unit tests * * @return the message_ptr at the front of the queue */ @@ -1097,8 +1097,8 @@ private: timer_ptr m_handshake_timer; timer_ptr m_ping_timer; - // TODO: this is not memory efficient. this value is not used after the - // handshake. + /// \todo this is not memory efficient. this value is not used after the + /// handshake. std::string m_handshake_buffer; /// Pointer to the processor object for this connection diff --git a/websocketpp/http/impl/parser.hpp b/websocketpp/http/impl/parser.hpp index ad9c3aba56..c34ae83176 100644 --- a/websocketpp/http/impl/parser.hpp +++ b/websocketpp/http/impl/parser.hpp @@ -35,8 +35,16 @@ namespace websocketpp { namespace http { namespace parser { -inline bool parser::parse_parameter_list(const std::string& in, - parameter_list& out) const +/// Extract an HTTP parameter list from a string. +/** + * @param [in] in The input string. + * + * @param [out] out The parameter list to store extracted parameters in. + * + * @return Whether or not the input was a valid parameter list. + */ +inline bool parser::parse_parameter_list(std::string const & in, + parameter_list & out) const { if (in.size() == 0) { return false; @@ -47,33 +55,48 @@ inline bool parser::parse_parameter_list(const std::string& in, return (it == in.begin()); } -inline bool parser::get_header_as_plist(const std::string& key, - parameter_list& out) const +/// Extract an HTTP parameter list from a parser header. +/** + * If the header requested doesn't exist or exists and is empty the parameter + * list is valid (but empty). + * + * @param [in] key The name/key of the HTTP header to use as input. + * + * @param [out] out The parameter list to store extracted parameters in. + * + * @return Whether or not the input was a valid parameter list. + */ +inline bool parser::get_header_as_plist(std::string const & key, + parameter_list & out) const { header_list::const_iterator it = m_headers.find(key); - // If this header doesn't exist it is valid - if (it == m_headers.end()) { - return false; - } - - // If this header exists but is empty it is valid - if (it->second.size() == 0) { + if (it == m_headers.end() || it->second.size() == 0) { return false; } return this->parse_parameter_list(it->second,out); } -inline void parser::set_version(const std::string& version) { - // TODO: validation? - - // first four chars == HTTP/ - +/// Set HTTP parser Version +/** + * \todo Does this method need any validation? + * + * @param [in] version The value to set the HTTP version to. + */ +inline void parser::set_version(std::string const & version) { m_version = version; } - -inline const std::string& parser::get_header(const std::string& key) const { + +/// Get the value of an HTTP header +/** + * \todo Make this method case insensitive. + * + * @param [in] key The name/key of the header to get. + * + * @return The value associated with the given HTTP header key. + */ +inline std::string const & parser::get_header(std::string const & key) const { header_list::const_iterator h = m_headers.find(key); if (h == m_headers.end()) { @@ -82,15 +105,28 @@ inline const std::string& parser::get_header(const std::string& key) const { return h->second; } } - -inline void parser::append_header(const std::string &key,const std::string - &val) + +/// Append a value to an existing HTTP header +/** + * This method will set the value of the HTTP header `key` with the indicated + * value. If a header with the name `key` already exists, `val` will be appended + * to the existing value. + * + * \todo Make this method case insensitive. + * \todo Should there be any restrictions on which keys are allowed to be set? + * \todo Exception free varient + * + * @param [in] key The name/key of the header to append to. + * + * @param [in] val The value to append. + */ +inline void parser::append_header(std::string const & key, std::string const & + val) { if (std::find_if(key.begin(),key.end(),is_not_token_char) != key.end()) { throw exception("Invalid header name",status_code::bad_request); } - // TODO: prevent use of reserved headers? if (this->get_header(key) == "") { m_headers[key] = val; } else { @@ -98,29 +134,63 @@ inline void parser::append_header(const std::string &key,const std::string } } -inline void parser::replace_header(const std::string &key,const std::string - &val) +/// Set a value for an HTTP header, replacing an existing value +/** + * This method will set the value of the HTTP header `key` with the indicated + * value. If a header with the name `key` already exists, `val` will replace the + * existing value. + * + * \todo Make this method case insensitive. + * \todo Should there be any restrictions on which keys are allowed to be set? + * \todo Exception free varient + * + * @param [in] key The name/key of the header to append to. + * + * @param [in] val The value to append. + */ +inline void parser::replace_header(std::string const & key, std::string const & + val) { m_headers[key] = val; } -inline void parser::remove_header(const std::string &key) { +/// Remove a header from the parser +/** + * Removes the header entirely from the parser. This is different than setting + * the value of the header to blank. + * + * \todo Make this method case insensitive. + * + * @param [in] key The name/key of the header to remove. + */ +inline void parser::remove_header(std::string const & key) { m_headers.erase(key); } -inline void parser::set_body(const std::string& value) { +/// Set HTTP body +/** + * Sets the body of the HTTP object and fills in the appropriate content length + * header + * + * @param [in] value The value to set the body to. + */ +inline void parser::set_body(std::string const & value) { if (value.size() == 0) { remove_header("Content-Length"); m_body = ""; return; } - std::stringstream foo; - foo << value.size(); - replace_header("Content-Length", foo.str()); + std::stringstream len; + len << value.size(); + replace_header("Content-Length", len.str()); m_body = value; } +/// Parse headers from an istream +/** + * @param [in] s The istream to extract headers from. + */ inline bool parser::parse_headers(std::istream& s) { std::string header; std::string::size_type end; @@ -143,6 +213,13 @@ inline bool parser::parse_headers(std::istream& s) { return true; } +/// Generate and return the HTTP headers as a string +/** + * Each headers will be followed by the \r\n sequence including the last one. + * A second \r\n sequence (blank header) is not appended by this method + * + * @return The HTTP headers as a string. + */ inline std::string parser::raw_headers() const { std::stringstream raw; @@ -154,6 +231,13 @@ inline std::string parser::raw_headers() const { return raw.str(); } +/// Process a header +/** + * + * \todo Update this method to be exception free. + * + * @param [in] s The istream to extract headers from. + */ inline void parser::process_header(std::string::iterator begin, std::string::iterator end) { diff --git a/websocketpp/http/impl/request.hpp b/websocketpp/http/impl/request.hpp index 4032ed304a..587445791b 100644 --- a/websocketpp/http/impl/request.hpp +++ b/websocketpp/http/impl/request.hpp @@ -148,7 +148,14 @@ inline void request::set_method(const std::string& method) { m_method = method; } - + +/// Set HTTP body +/** + * Sets the body of the HTTP object and fills in the appropriate content length + * header + * + * @param value The value to set the body to. + */ inline void request::set_uri(const std::string& uri) { // TODO: validation? m_uri = uri;