netservices: add BHttpHeader class and BHttpHeaderMap skeleton

Change-Id: I36a7c757a6909604d749355ecb1a9d42d05d7306
2021-12-17 17:40:15 +00:00
parent 892cbe10b6
commit 34522da9e3
9 changed files with 754 additions and 38 deletions
@@ -0,0 +1,332 @@
+/*
+ * Copyright 2021 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Niels Sascha Reedijk, [email protected]
+ *
+ * Corresponds to:
+ *		headers/private/netservices2/HttpHeaders.h			hrev?????
+ *		src/kits/network/libnetservices2/HttpHeaders.cpp	hrev?????
+ */
+
+
+#if __cplusplus >= 201703L
+
+
+/*!
+	\file HttpHeaders.h
+	\ingroup netservices
+	\brief Provides the BHttpHeader and BHttpHeaderMap classes.
+*/
+
+namespace BPrivate {
+
+namespace Network {
+
+
+/*!
+	\class BHttpHeader
+	\ingroup netservices
+	\brief Represent a HTTP header name and value pair.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\class BHttpHeader::InvalidInput
+	\ingroup netservices
+	\brief Error that represents when a string input contains characters that are incompatible with
+		the HTTP specification.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\var BString BHttpHeader::InvalidInput::input
+	\brief The input that contains the invalid contents.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpHeader::InvalidInput::InvalidInput(const char *origin, BString input)
+	\brief Constructor that sets the \a origin and the invalid \a input.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn virtual BString BHttpHeader::InvalidInput::DebugMessage() const override
+	\brief Retrieve a debug message that contains all info in this error.
+
+	The output will be along the lines of:
+	\code
+	[Origin] Invalid format or unsupported characters in input    [input]
+	\endcode
+
+	\exception std::bad_alloc In the future this method may throw this
+		exception when the memory for the debug message cannot be allocated.
+
+	\return A \ref BString object that contains the debug message.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn virtual const char* BHttpHeader::InvalidInput::Message() const noexcept override
+	\brief Get a pointer to the message describing the error.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\class BHttpHeader::EmptyHeader
+	\ingroup netservices
+	\brief Error that is raised when the HTTP header has an empty name or value when it is
+		serialized to and from text.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpHeader::EmptyHeader::EmptyHeader(const char *origin)
+	\copydoc BError::BError()
+*/
+
+
+/*!
+	\fn virtual const char* BHttpHeader::EmptyHeader::Message() const noexcept override
+	\brief Get a pointer to the message describing the error.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\class BHttpHeader::HeaderName
+	\ingroup netservices
+	\brief Representation of a HTTP header name.
+
+	As per the HTTP specification, header fields have a name. There are limitations to which
+	characters are supported. As per the specification, header field names are case insensitive.
+	This means that the \c content-encoding is equal to \c Content-Encoding or even
+	\c COnTenT-ENcOdING.
+
+	This particular object can be empty. Headers with empty names can still be used in the
+	\ref BHttpHeaderMap object, though as soon as you try to serialize them to a string, the
+	\ref BHttpHeader::EmptyHeader exception will be raised.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn bool BHttpHeader::HeaderName::IsEmpty() const noexcept
+	\brief Check if the header name has a value set.
+
+	\retval true This object is empty, meaning it is set to an empty string.
+	\retval false This object has a valid header name.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpHeader::HeaderName::operator BString() const
+	\brief Return a copy of the header name as a string.
+
+	\return The header name as a \ref BString object.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpHeader::HeaderName::operator std::string_view() const
+	\brief Return a \c std::string_view over the header name.
+
+	\return A \c std::string_view object over the header name.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn bool BHttpHeader::HeaderName::operator==(const BString &other) const noexcept
+	\brief Compare the header name to a string.
+
+	\param other The \c other string to compare it to.
+
+	The comparison is case-insensitive. So if this header name is set to \c Content-Encoding,
+	comparing it to \c content-encoding will return \c true.
+
+	\retval true The current header name is equal to the \a other name.
+	\retval false The current header name is different from the \a other name.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn bool BHttpHeader::HeaderName::operator==(const std::string_view other) const noexcept
+	\copydoc BHttpHeader::HeaderName::operator==(const BString &other) const noexcept
+*/
+
+
+/*!
+	\fn BHttpHeader::BHttpHeader()
+	\brief Construct an empty HTTP Header Field.
+
+	The name and the value of the field will both be empty.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpHeader::BHttpHeader(BHttpHeader &&other) noexcept
+	\brief Move constructor.
+
+	The name and value from the \a other header object will be moved to this object. The \a other
+	object will be empty, meaning it no longer has a name or value.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpHeader::BHttpHeader(const BHttpHeader &other)
+	\brief Copy constructor.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpHeader::BHttpHeader(std::string_view name, std::string_view value)
+	\brief Constructor to create a header from a \a name and a \a value.
+
+	The parameters are checked whether they only contain characters that are allowed by the HTTP
+	specification.
+
+	\param name The name of the header field.
+	\param value The value of the header field.
+
+	\exception BHttpHeader::InvalidInput This error indicates that the \a name or the \a value
+		contains invalid characters.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpHeader::~BHttpHeader() noexcept
+	\brief Destructor.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn bool BHttpHeader::IsEmpty() noexcept
+	\brief Check if the name or the value are empty.
+
+	A header is considered empty when it does not have a name or a value, or neither of them. An
+	empty header cannot be serialized to a string.
+
+	\retval true The name or value are empty.
+	\retval false The name and value contain valid data.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn const HeaderName& BHttpHeader::Name() noexcept
+	\brief Get the header name.
+
+	\return A reference to the header name object.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn std::string_view BHttpHeader::Value() noexcept
+	\brief Get the header value.
+
+	\return A \c std::string_view to the header value.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpHeader& BHttpHeader::operator=(BHttpHeader &&other) noexcept
+	\brief Move assignment operator.
+
+	Moves the name and value from the \a other header to this object. The \a other object will be
+	empty.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn BHttpHeader& BHttpHeader::operator=(const BHttpHeader &other)
+	\brief Copy assignment operator.
+
+	Make a new header object with a copy of the name and value of the \a other header.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn void BHttpHeader::SetName(std::string_view name)
+	\brief Set the name of the header to a \a name.
+
+	\param name A header name with characters supported by the HTTP specification.
+
+	\exception BHttpHeader::InvalidInput This error indicates that the \a name contains invalid
+		characters.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn void BHttpHeader::SetValue(std::string_view value)
+	\brief Set the value of the header to a \a value.
+
+	\param value A header value with characters supported by the HTTP specification.
+
+	\exception BHttpHeader::InvalidInput This error indicates that the \a value contains invalid
+		characters.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\class BHttpHeaderMap
+	\ingroup netservices
+	\brief Represent set of HTTP headers.
+
+	\since Haiku R1
+*/
+
+
+} // namespace Network
+
+} // namespace BPrivate
+
+#endif