| Line | Branch | Exec | Source |
|---|---|---|---|
| 1 | // | ||
| 2 | // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com) | ||
| 3 | // Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com) | ||
| 4 | // | ||
| 5 | // Distributed under the Boost Software License, Version 1.0. (See accompanying | ||
| 6 | // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | ||
| 7 | // | ||
| 8 | // Official repository: https://github.com/boostorg/url | ||
| 9 | // | ||
| 10 | |||
| 11 | #ifndef BOOST_URL_ENCODING_OPTS_HPP | ||
| 12 | #define BOOST_URL_ENCODING_OPTS_HPP | ||
| 13 | |||
| 14 | #include <boost/url/detail/config.hpp> | ||
| 15 | |||
| 16 | namespace boost { | ||
| 17 | namespace urls { | ||
| 18 | |||
| 19 | /** Percent-encoding options | ||
| 20 | |||
| 21 | These options are used to customize | ||
| 22 | the behavior of algorithms which use | ||
| 23 | percent escapes, such as encoding | ||
| 24 | or decoding. | ||
| 25 | |||
| 26 | @see | ||
| 27 | @ref encode, | ||
| 28 | @ref encoded_size, | ||
| 29 | @ref pct_string_view. | ||
| 30 | */ | ||
| 31 | struct encoding_opts | ||
| 32 | { | ||
| 33 | /** True if spaces encode to and from plus signs | ||
| 34 | |||
| 35 | Although not prescribed by RFC 3986, | ||
| 36 | many applications decode plus signs | ||
| 37 | in URL queries as spaces. In particular, | ||
| 38 | the form-urlencoded Media Type in HTML | ||
| 39 | for submitting forms uses this convention. | ||
| 40 | |||
| 41 | This option controls whether | ||
| 42 | the PLUS character ("+") is used to | ||
| 43 | represent the SP character (" ") when | ||
| 44 | encoding or decoding. | ||
| 45 | |||
| 46 | When this option is `true`, both the | ||
| 47 | encoded SP ("%20") and the PLUS | ||
| 48 | character ("+") represent a space (" ") | ||
| 49 | when decoding. To represent a plus sign, | ||
| 50 | its encoded form ("%2B") is used. | ||
| 51 | |||
| 52 | The @ref encode and @ref encoded_size functions | ||
| 53 | will encode spaces as plus signs when | ||
| 54 | this option is `true`, regardless of the | ||
| 55 | allowed character set. They will also | ||
| 56 | encode plus signs as "%2B" when this | ||
| 57 | option is `true`, regardless of the | ||
| 58 | allowed character set. | ||
| 59 | |||
| 60 | Note that when a URL is normalized, | ||
| 61 | all unreserved percent-encoded characters are | ||
| 62 | replaced with their unreserved equivalents. | ||
| 63 | However, normalizing the URL query maintains | ||
| 64 | the decoded and encoded "&=+" as they are | ||
| 65 | because they might have different meanings. | ||
| 66 | |||
| 67 | This behavior is not optional because | ||
| 68 | normalization can only mitigate false | ||
| 69 | negatives, but it should eliminate | ||
| 70 | false positives. | ||
| 71 | Making it optional would allow | ||
| 72 | a false positive because there's | ||
| 73 | at least one very relevant schema (HTTP) | ||
| 74 | where a decoded or encoded "&=+" has different | ||
| 75 | meanings and represents different resources. | ||
| 76 | |||
| 77 | The same considerations apply to URL comparison | ||
| 78 | algorithms in the library, as they treat URLs | ||
| 79 | as if they were normalized. | ||
| 80 | |||
| 81 | @par Specification | ||
| 82 | @li <a href="https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1"> | ||
| 83 | application/x-www-form-urlencoded (w3.org)</a> | ||
| 84 | @li <a href="https://datatracker.ietf.org/doc/html/rfc1866#section-8.2.1"> | ||
| 85 | The form-urlencoded Media Type (RFC 1866)</a> | ||
| 86 | @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.2"> | ||
| 87 | Section 6.2.2.2. Percent-Encoding Normalization (RFC 3986)</a> | ||
| 88 | */ | ||
| 89 | bool space_as_plus = false; | ||
| 90 | |||
| 91 | /** True if hexadecimal digits are emitted as lower case | ||
| 92 | |||
| 93 | By default, percent-encoding algorithms | ||
| 94 | emit hexadecimal digits A through F as | ||
| 95 | uppercase letters. When this option is | ||
| 96 | `true`, lowercase letters are used. | ||
| 97 | */ | ||
| 98 | bool lower_case = false; | ||
| 99 | |||
| 100 | /** True if nulls are not allowed | ||
| 101 | |||
| 102 | Normally all possible character values | ||
| 103 | (from 0 to 255) are allowed, with reserved | ||
| 104 | characters being replaced with escapes | ||
| 105 | upon encoding. When this option is true, | ||
| 106 | attempting to decode a null will result | ||
| 107 | in an error. | ||
| 108 | */ | ||
| 109 | bool disallow_null = false; | ||
| 110 | |||
| 111 | /** Constructs an `encoding_opts` object with the specified options. | ||
| 112 | |||
| 113 | @param space_as_plus If true, spaces will be encoded as plus signs. | ||
| 114 | @param lower_case If true, hexadecimal digits will be emitted as lower case. | ||
| 115 | @param disallow_null If true, null characters will not be allowed. | ||
| 116 | */ | ||
| 117 | BOOST_CXX14_CONSTEXPR | ||
| 118 | inline | ||
| 119 | 8025 | encoding_opts( | |
| 120 | bool const space_as_plus = false, | ||
| 121 | bool const lower_case = false, | ||
| 122 | bool const disallow_null = false) noexcept | ||
| 123 | 8025 | : space_as_plus(space_as_plus) | |
| 124 | 8025 | , lower_case(lower_case) | |
| 125 | 8025 | , disallow_null(disallow_null) {} | |
| 126 | }; | ||
| 127 | |||
| 128 | } // urls | ||
| 129 | } // boost | ||
| 130 | |||
| 131 | #endif | ||
| 132 |