diff --git a/http/CHTTPProtocol.h b/http/CHTTPProtocol.h index 19979ed1..7c6fd000 100644 --- a/http/CHTTPProtocol.h +++ b/http/CHTTPProtocol.h @@ -10,88 +10,162 @@ class IInputStream; class IOutputStream; +//! HTTP request type +/*! +This class encapsulates an HTTP request. +*/ class CHTTPRequest { -public: +private: typedef std::list > CHeaderList; - typedef std::map CHeaderMap; +public: + //! Iterator on headers + /*! + An iterator on the headers. Each element is a std::pair; first is + the header name as a CString, second is the header value as a CString. + */ typedef CHeaderList::const_iterator const_iterator; CHTTPRequest(); ~CHTTPRequest(); - // manipulators + //! @name manipulators + //@{ - // add a header by name. replaces existing header, if any. - // headers are sent in the order they're inserted. replacing - // a header does not change its original position in the order. + //! Insert header + /*! + Add a header by name replacing the existing header, if any. + Headers are sent in the order they're inserted. Replacing + a header does not change its original position in the order. + */ void insertHeader(const CString& name, const CString& value); - // append a header. equivalent to insertHeader() if the header - // doesn't exist, otherwise it appends a comma and the value to - // the existing header. + //! Append header + /*! + Append a header. Equivalent to insertHeader() if the header + doesn't exist, otherwise it appends a comma and the value to + the existing header. + */ void appendHeader(const CString& name, const CString& value); - // remove a header by name. does nothing if no such header. + //! Remove header + /*! + Remove a header by name. Does nothing if the header doesn't exist. + */ void eraseHeader(const CString& name); - // accessors + //@} + //! @name accessors + //@{ - // returns true iff the header exists + //! Check header existence + /*! + Returns true iff the header exists. + */ bool isHeader(const CString& name) const; - // get a header by name. returns the empty string if no such header. + //! Get header + /*! + Get a header by name. Returns the empty string if the header + doesn't exist. + */ CString getHeader(const CString& name) const; - // get iterator over all headers in the order they were added + // headers are iterated in the order they were added. + //! Get beginning header iterator const_iterator begin() const { return m_headers.begin(); } + //! Get ending header iterator const_iterator end() const { return m_headers.end(); } + //@} + public: // note -- these members are public for convenience + //! The HTTP method CString m_method; + //! The HTTP URI CString m_uri; + //! The HTTP major version number SInt32 m_majorVersion; + //! The HTTP minor version number SInt32 m_minorVersion; + //! The HTTP body, after transfer decoding CString m_body; private: + typedef std::map CHeaderMap; + CHeaderList m_headers; CHeaderMap m_headerByName; }; +//! HTTP reply type +/*! +This class encapsulates an HTTP reply. +*/ class CHTTPReply { public: + //! Header list + /*! + The type of the reply header list. Each pair is the header name + and value, respectively for first and second. + */ typedef std::vector > CHeaderList; + // note -- these members are public for convenience + //! The HTTP major version number SInt32 m_majorVersion; + //! The HTTP minor version number SInt32 m_minorVersion; + //! The HTTP status code SInt32 m_status; + //! The HTTP reason phrase CString m_reason; + //! The HTTP method CString m_method; - + //! The HTTP headers CHeaderList m_headers; - + //! The HTTP body CString m_body; }; +//! HTTP protocol utilities +/*! +This class provides utility functions for HTTP. +*/ class CHTTPProtocol { public: - // read and parse an HTTP request. result is returned in a - // CHTTPRequest which the client must delete. throws an - // XHTTP if there was a parse error. throws an XIO exception - // if there was a read error. if maxSize is greater than - // zero and the request is larger than maxSize bytes then - // throws XHTTP(413). + //! Multipart form parts + /*! + Each element is the contents of a multipart form part indexed by + it's name. + */ + typedef std::map CFormParts; + + //! Read HTTP request + /*! + Read and parse an HTTP request. The result is returned in a + CHTTPRequest which the client must delete. Throws an + XHTTP if there was a parse error. Throws an XIO exception + if there was a read error. If \c maxSize is greater than + zero and the request is larger than \c maxSize bytes then + throws XHTTP(413) (request entity too large). + */ static CHTTPRequest* readRequest(IInputStream*, UInt32 maxSize = 0); - // send an HTTP reply on the stream + //! Send HTTP response + /*! + Send an HTTP reply. The Content-Length and Date headers are set + automatically. + */ static void reply(IOutputStream*, CHTTPReply&); - // parse a multipart/form-data body into its parts. returns true - // iff the entire body was correctly parsed. + //! Parse multipart form data + /*! + Parse a multipart/form-data body into its parts. Returns true + iff the entire body was correctly parsed. + */ // FIXME -- name/value pairs insufficient to save part headers - typedef std::map CFormParts; static bool parseFormData(const CHTTPRequest&, CFormParts& parts); diff --git a/http/XHTTP.cpp b/http/XHTTP.cpp index b6535d9f..690cb4f8 100644 --- a/http/XHTTP.cpp +++ b/http/XHTTP.cpp @@ -101,9 +101,9 @@ XHTTP::getReason(SInt32 status) // XHTTPAllow // -XHTTPAllow::XHTTPAllow(const CString& allowed) : +XHTTPAllow::XHTTPAllow(const CString& allowedMethods) : XHTTP(405), - m_allowed(allowed) + m_allowed(allowedMethods) { // do nothing } diff --git a/http/XHTTP.h b/http/XHTTP.h index e098a713..384881b6 100644 --- a/http/XHTTP.h +++ b/http/XHTTP.h @@ -6,17 +6,37 @@ class CHTTPReply; +//! Generic HTTP exception class XHTTP : public XBase { public: + /*! + Use the HTTP \c statusCode as the failure reason. + */ XHTTP(SInt32 statusCode); + /*! + Use the HTTP \c statusCode as the failure reason. Use \c reasonPhrase + as the human readable reason for the failure. + */ XHTTP(SInt32 statusCode, const CString& reasonPhrase); ~XHTTP(); + //@{ + //! @name accessors + + //! Get the HTTP status code SInt32 getStatus() const; + + //! Get the reason phrase CString getReason() const; + //! Modify reply for error + /*! + Override to modify an HTTP reply to further describe the error. + */ virtual void addHeaders(CHTTPReply&) const; + //@} + protected: virtual CString getWhat() const throw(); @@ -30,6 +50,10 @@ private: class XHTTPAllow : public XHTTP { public: + /*! + \c allowedMethods is added as an `Allow' header to a reply in + addHeaders(). + */ XHTTPAllow(const CString& allowedMethods); ~XHTTPAllow();