1/* 2 * Copyright 2022 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Niels Sascha Reedijk, niels.reedijk@gmail.com 7 * 8 * Corresponds to: 9 * headers/private/netservices2/HttpTime.h hrev????? 10 * src/kits/network/libnetservices2/HttpTime.cpp hrev????? 11 */ 12 13 14#if __cplusplus >= 201703L 15 16 17namespace BPrivate { 18 19namespace Network { 20 21 22/*! 23 \file HttpTime.h 24 \ingroup netservices 25 \brief Provides tools to parse and format HTTP dates. 26 27 The HTTP protocols prescribe that each HTTP response should have a \c Date header field with a 28 timestamp the response was generated. Optionally, there are other fields that may have a 29 timestamp in them, such as \c Set-Cookie or \c If-Modified-Since. 30 31 According to section 3.3 of RFC 2616, the standard date format is the format described by 32 RFC 1123, which updates the previous RFC 822. However, a proper implementation of a HTTP parser 33 may also want to support the RFC 850 format (which was obsoleted by RFC 1036) and the old 34 C-library standard date formatting of \c asctime(). 35 36 Examples: 37 <table> 38 <tr><td>RFC1123 / RFC822</td><td>Sun, 06 Nov 1994 08:49:37 GMT</td></tr> 39 <tr><td>RFC850</td><td>Sunday, 06-Nov-94 08:49:37 GMT</td></tr> 40 <tr><td>asctime</td><td>Sun Nov 6 08:49:37 1994</td></tr> 41 </table> 42 43 The tools in this module will make it easer to parse and format dates according to those 44 standards. When parsing the 45 46 You can use \ref parse_http_time() to parse a string that contains a HTTP timestamp. You can 47 use \ref format_http_time() to format the HTTP time according to the prescribed format. If you 48 want slightly more information about parsing, or if you want to hold an intermediate 49 representation of the timestamp, have a look at the \ref BPrivate::Network::BHttpTime class. 50 51 Note that when parsing a timestamp string, the tools are slightly more permissive than the 52 standards. For example, if the RFC 1123 timestamp does not have the GMT timezone indicator at 53 the end, it will still be accepted. Likewise, there is support for RFC 850 timestamps with a 54 4-digit year format. When formatting a \ref BPrivate::BDateTime to a string, it will always use 55 prescribed representation. 56 57 \since Haiku R1 58*/ 59 60 61/*! 62 \enum BHttpTimeFormat 63 \brief Describes the three time formats supported by the HTTP RFC. 64*/ 65 66 67/*! 68 \class BHttpTime::InvalidInput 69 \ingroup netservices 70 \brief Error that indicates that a string cannot be parsed as a valid HTTP timestamp. 71 72 \since Haiku R1 73*/ 74 75 76/*! 77 \var BString BHttpTime::InvalidInput::input 78 \brief Copy of the original timestamp that could not be parsed. 79 80 \since Haiku R1 81*/ 82 83 84/*! 85 \fn BHttpTime::InvalidInput::InvalidInput(const char *origin, BString input) 86 \brief Constructor that sets the \a origin and the invalid \a input. 87 88 \since Haiku R1 89*/ 90 91 92/*! 93 \class BHttpTime 94 \ingroup netservices 95 \brief Utility class that can parse and format HTTP Date strings. 96 97 See the description of the module in \ref HttpTime.h for more information about HTTP 98 timestamps. 99 100 Note that for quick conversions of a \ref BDateTime into a \ref BString and vice versa, you can 101 also use the \ref format_http_time() and \ref parse_http_time() utilities. 102 103 \since Haiku R1 104*/ 105 106 107/*! 108 \fn BHttpTime::BHttpTime() noexcept 109 \brief Constructs a new object and sets the timestamp to the current time. 110 111 \since Haiku R1 112*/ 113 114 115/*! 116 \fn BHttpTime::BHttpTime(BDateTime date) 117 \brief Constructs a new object and sets the timestamp to \a date. 118 119 \param date A valid \ref BDateTime object for the desired timestamp. 120 121 \exception BHttpTime::InvalidInput The \a date does not contain a valid timestamp. 122 123 \since Haiku R1 124*/ 125 126 127/*! 128 \fn BHttpTime::BHttpTime(const BString &dateString) 129 \brief Constructs a new object and parses the timestamp from \a dateString. 130 131 \param dateString A string that contains a valid HTTP timestamp. The \a dateString must not 132 contain any characters, other than the timestamp. It is up to the caller to sanitize any 133 input, including trimming whitespace at the beginning and end of the string. 134 135 \exception BHttpTime::InvalidInput The \a dateString cannot be parsed as a valid timestamp. 136 137 \since Haiku R1 138*/ 139 140 141/*! 142 \fn void BHttpTime::SetTo(BDateTime date) 143 \brief Set the current timestamp to \a date. 144 145 \param date A valid \ref BDateTime object for the desired timestamp. 146 147 \exception BHttpTime::InvalidInput The \a date does not contain a valid timestamp. 148 149 \since Haiku R1 150*/ 151 152 153/*! 154 \fn void BPrivate::Network::BHttpTime::SetTo(const BString &string) 155 \brief Set the current timestamp by parsing \a string. 156 157 \param string A string that contains a valid HTTP timestamp. The \a dateString must not 158 contain any characters, other than the timestamp. It is up to the caller to sanitize any 159 input, including trimming whitespace at the beginning and end of the string. 160 161 \exception BHttpTime::InvalidInput The \a dateString cannot be parsed as a valid timestamp. 162 163 \since Haiku R1 164*/ 165 166 167/*! 168 \fn BDateTime BPrivate::Network::BHttpTime::DateTime() const noexcept 169 \brief Get the current timestamp. 170 171 \return A valid \ref BDateTime object that contains the timestamp that this object is currently 172 set to. 173 174 \since Haiku R1 175*/ 176 177 178/*! 179 \fn BHttpTimeFormat BHttpTime::DateTimeFormat() const noexcept 180 \brief Get the format that the current timestamp parsed from. 181 182 If the timestamp was parsed from a string, this method supplies a bit of information about what 183 format the original string was in. Note that for both the RFC 1132 and RFC 850 formats, the 184 parsing is slightly less strict than the RFC prescribes. This may mean that if you parse a 185 non-canonical string, and then format it back using the same format specifier, the two strings 186 may differ in content. 187 188 If the timestamp was set by setting it to a \ref BDateTime object, then this will always return 189 \c BHttpTimeFormat::RFC1123. 190 191 \return The \ref BHttpTimeFormat that describes the format the input string was in, or 192 \c BHttpTimeFormat::RFC1123 if the timestamp was set by a \ref BDateTime. 193 194 \since Haiku R1 195*/ 196 197 198/*! 199 \fn BString BHttpTime::ToString(BHttpTimeFormat outputFormat=BHttpTimeFormat::RFC1123) const 200 \brief Formats the timestamp to a string. 201 202 \param outputFormat The requested outputformat. The default is the recommended RFC 1123 format. 203 204 \return A string that contains the formatted timestamp. 205 206 \exception std::bad_alloc In the future this method may throw this exception when the memory 207 for the output string cannot be allocated. 208 209 \since Haiku R1 210*/ 211 212 213/*! 214 \fn BString format_http_time(BDateTime timestamp, 215 BHttpTimeFormat outputFormat=BHttpTimeFormat::RFC1123) 216 \brief Format the \a timestamp into a string according to the \a outputFormat. 217 218 See the description of the module in \ref HttpTime.h for more information about HTTP 219 timestamps. 220 221 \param timestamp A valid \ref BDateTime object for the desired timestamp. 222 \param outputFormat The requested outputformat. The default is the recommended RFC 1123 format. 223 224 \return A string that contains the formatted timestamp. 225 226 \exception BHttpTime::InvalidInput The \a date does not contain a valid timestamp. 227 \exception std::bad_alloc In the future this method may throw this exception when the memory 228 for the output string cannot be allocated. 229 230 \see \ref BHttpTime \ref parse_http_time() 231 232 \since Haiku R1 233*/ 234 235 236/*! 237 \fn BDateTime parse_http_time(const BString &string) 238 \brief Parse a \a string that contains a timestamp and return a \ref BDateTime object. 239 240 See the description of the module in \ref HttpTime.h for more information about HTTP 241 timestamps. 242 243 \param string A string that contains a valid HTTP timestamp. The \a dateString must not 244 contain any characters, other than the timestamp. It is up to the caller to sanitize any 245 input, including trimming whitespace at the beginning and end of the string. 246 247 \exception BHttpTime::InvalidInput The \a string cannot be parsed as a valid timestamp. 248 249 \see \ref BHttpTime \ref format_http_time() 250 251 \since Haiku R1 252*/ 253 254 255} // namespace BPrivate 256 257} // namespace Network 258 259#endif 260