/** Copyright 2022 Haiku, Inc. All rights reserved.* Distributed under the terms of the MIT License.** Authors:* Niels Sascha Reedijk, niels.reedijk@gmail.com** Corresponds to:* headers/private/netservices2/HttpTime.h hrev?????* src/kits/network/libnetservices2/HttpTime.cpp hrev?????*/#if __cplusplus >= 201703Lnamespace BPrivate {namespace Network {/*!\file HttpTime.h\ingroup netservices\brief Provides tools to parse and format HTTP dates.The HTTP protocols prescribe that each HTTP response should have a \c Date header field with atimestamp the response was generated. Optionally, there are other fields that may have atimestamp in them, such as \c Set-Cookie or \c If-Modified-Since.According to section 3.3 of RFC 2616, the standard date format is the format described byRFC 1123, which updates the previous RFC 822. However, a proper implementation of a HTTP parsermay also want to support the RFC 850 format (which was obsoleted by RFC 1036) and the oldC-library standard date formatting of \c asctime().Examples:<table><tr><td>RFC1123 / RFC822</td><td>Sun, 06 Nov 1994 08:49:37 GMT</td></tr><tr><td>RFC850</td><td>Sunday, 06-Nov-94 08:49:37 GMT</td></tr><tr><td>asctime</td><td>Sun Nov 6 08:49:37 1994</td></tr></table>The tools in this module will make it easer to parse and format dates according to thosestandards. When parsing theYou can use \ref parse_http_time() to parse a string that contains a HTTP timestamp. You canuse \ref format_http_time() to format the HTTP time according to the prescribed format. If youwant slightly more information about parsing, or if you want to hold an intermediaterepresentation of the timestamp, have a look at the \ref BPrivate::Network::BHttpTime class.Note that when parsing a timestamp string, the tools are slightly more permissive than thestandards. For example, if the RFC 1123 timestamp does not have the GMT timezone indicator atthe end, it will still be accepted. Likewise, there is support for RFC 850 timestamps with a4-digit year format. When formatting a \ref BPrivate::BDateTime to a string, it will always useprescribed representation.\since Haiku R1*//*!\enum BHttpTimeFormat\brief Describes the three time formats supported by the HTTP RFC.*//*!\class BHttpTime::InvalidInput\ingroup netservices\brief Error that indicates that a string cannot be parsed as a valid HTTP timestamp.\since Haiku R1*//*!\var BString BHttpTime::InvalidInput::input\brief Copy of the original timestamp that could not be parsed.\since Haiku R1*//*!\fn BHttpTime::InvalidInput::InvalidInput(const char *origin, BString input)\brief Constructor that sets the \a origin and the invalid \a input.\since Haiku R1*//*!\class BHttpTime\ingroup netservices\brief Utility class that can parse and format HTTP Date strings.See the description of the module in \ref HttpTime.h for more information about HTTPtimestamps.Note that for quick conversions of a \ref BDateTime into a \ref BString and vice versa, you canalso use the \ref format_http_time() and \ref parse_http_time() utilities.\since Haiku R1*//*!\fn BHttpTime::BHttpTime() noexcept\brief Constructs a new object and sets the timestamp to the current time.\since Haiku R1*//*!\fn BHttpTime::BHttpTime(BDateTime date)\brief Constructs a new object and sets the timestamp to \a date.\param date A valid \ref BDateTime object for the desired timestamp.\exception BHttpTime::InvalidInput The \a date does not contain a valid timestamp.\since Haiku R1*//*!\fn BHttpTime::BHttpTime(const BString &dateString)\brief Constructs a new object and parses the timestamp from \a dateString.\param dateString A string that contains a valid HTTP timestamp. The \a dateString must notcontain any characters, other than the timestamp. It is up to the caller to sanitize anyinput, including trimming whitespace at the beginning and end of the string.\exception BHttpTime::InvalidInput The \a dateString cannot be parsed as a valid timestamp.\since Haiku R1*//*!\fn void BHttpTime::SetTo(BDateTime date)\brief Set the current timestamp to \a date.\param date A valid \ref BDateTime object for the desired timestamp.\exception BHttpTime::InvalidInput The \a date does not contain a valid timestamp.\since Haiku R1*//*!\fn void BPrivate::Network::BHttpTime::SetTo(const BString &string)\brief Set the current timestamp by parsing \a string.\param string A string that contains a valid HTTP timestamp. The \a dateString must notcontain any characters, other than the timestamp. It is up to the caller to sanitize anyinput, including trimming whitespace at the beginning and end of the string.\exception BHttpTime::InvalidInput The \a dateString cannot be parsed as a valid timestamp.\since Haiku R1*//*!\fn BDateTime BPrivate::Network::BHttpTime::DateTime() const noexcept\brief Get the current timestamp.\return A valid \ref BDateTime object that contains the timestamp that this object is currentlyset to.\since Haiku R1*//*!\fn BHttpTimeFormat BHttpTime::DateTimeFormat() const noexcept\brief Get the format that the current timestamp parsed from.If the timestamp was parsed from a string, this method supplies a bit of information about whatformat the original string was in. Note that for both the RFC 1132 and RFC 850 formats, theparsing is slightly less strict than the RFC prescribes. This may mean that if you parse anon-canonical string, and then format it back using the same format specifier, the two stringsmay differ in content.If the timestamp was set by setting it to a \ref BDateTime object, then this will always return\c BHttpTimeFormat::RFC1123.\return The \ref BHttpTimeFormat that describes the format the input string was in, or\c BHttpTimeFormat::RFC1123 if the timestamp was set by a \ref BDateTime.\since Haiku R1*//*!\fn BString BHttpTime::ToString(BHttpTimeFormat outputFormat=BHttpTimeFormat::RFC1123) const\brief Formats the timestamp to a string.\param outputFormat The requested outputformat. The default is the recommended RFC 1123 format.\return A string that contains the formatted timestamp.\exception std::bad_alloc In the future this method may throw this exception when the memoryfor the output string cannot be allocated.\since Haiku R1*//*!\fn BString format_http_time(BDateTime timestamp,BHttpTimeFormat outputFormat=BHttpTimeFormat::RFC1123)\brief Format the \a timestamp into a string according to the \a outputFormat.See the description of the module in \ref HttpTime.h for more information about HTTPtimestamps.\param timestamp A valid \ref BDateTime object for the desired timestamp.\param outputFormat The requested outputformat. The default is the recommended RFC 1123 format.\return A string that contains the formatted timestamp.\exception BHttpTime::InvalidInput The \a date does not contain a valid timestamp.\exception std::bad_alloc In the future this method may throw this exception when the memoryfor the output string cannot be allocated.\see \ref BHttpTime \ref parse_http_time()\since Haiku R1*//*!\fn BDateTime parse_http_time(const BString &string)\brief Parse a \a string that contains a timestamp and return a \ref BDateTime object.See the description of the module in \ref HttpTime.h for more information about HTTPtimestamps.\param string A string that contains a valid HTTP timestamp. The \a dateString must notcontain any characters, other than the timestamp. It is up to the caller to sanitize anyinput, including trimming whitespace at the beginning and end of the string.\exception BHttpTime::InvalidInput The \a string cannot be parsed as a valid timestamp.\see \ref BHttpTime \ref format_http_time()\since Haiku R1*/} // namespace BPrivate} // namespace Network#endif