boost/mysql/escape_string.hpp

0001 //
0002 // Copyright (c) 2019-2024 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007
0008 #ifndef BOOST_MYSQL_ESCAPE_STRING_HPP
0009 #define BOOST_MYSQL_ESCAPE_STRING_HPP
0010
0011 #include <boost/mysql/error_code.hpp>
0012 #include <boost/mysql/string_view.hpp>
0013
0014 #include <boost/mysql/detail/escape_string.hpp>
0015 #include <boost/mysql/detail/output_string.hpp>
0016
0017 #include <boost/config.hpp>
0018
0019 namespace boost {
0020 namespace mysql {
0021
0022 struct format_options;
0023
0024 /**
0025  * \brief (EXPERIMENTAL) Identifies the context which a string is being escaped for.
0026  */
0027 enum class quoting_context : char
0028 {
0029     /// The string is surrounded by double quotes.
0030     double_quote = '"',
0031
0032     /// The string is surrounded by single quotes.
0033     single_quote = '\'',
0034
0035     /// The string is surrounded by backticks.
0036     backtick = '`',
0037 };
0038
0039 /**
0040  * \brief (EXPERIMENTAL) Escapes a string, making it safe for query composition.
0041  * \details
0042  * Given a string `input`, computes a string with special characters
0043  * escaped, and places it in `output`. This function is a low-level building
0044  * block for composing client-side queries with runtime string values without
0045  * incurring in SQL injection vulnerabilities.
0046  * If you can, prefer using higher-level functions like \ref format_sql.
0047  * \n
0048  * Escaping rules are different depending on the context a string is
0049  * being used in. `quot_ctx` identifies where the string will appear in
0050  * a query. Possible values are: \n
0051  * \li \ref quoting_context::double_quote : the string is surrounded by
0052  *     double quotes. For example:
0053  *     \code "SELECT * FROM employee WHERE company = \"<runtime_value>\"" \endcode
0054  * \li \ref quoting_context::single_quote : the string is surrounded by
0055  *     single quotes. For example:
0056  *     \code "SELECT * FROM employee WHERE company = '<runtime_value>'" \endcode
0057  * \li \ref quoting_context::backtick : the string is surrounded by
0058  *     backticks. This may happen when escaping identifiers. For example:
0059  *     \code "SELECT `<runtime_column>` FROM employee" \endcode
0060  * \n
0061  * By default, MySQL treats backslash characters as escapes in string values
0062  * (for instance, the string `"\n"` is treated as a newline). This behavior is
0063  * enabled by default, but can be disabled by enabling the
0064  * <a
0065  *    href="https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_no_backslash_escapes">`NO_BACKSLASH_ESCAPES`</a>
0066  * SQL mode. When enabled, backslashes no longer have a special meaning, which changes
0067  * the escaping rules. `opts.backslash_escapes` should be set to `true` if backslashes represent
0068  * escapes (i.e. `NO_BACKSLASH_ESCAPES` is not enabled), and `false` otherwise.
0069  * \n
0070  * MySQL can be configured to treat double-quoted strings as identifiers instead of values.
0071  * This is enabled by activating the
0072  * <a href="https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_ansi_quotes">`ANSI_QUOTES`</a> or
0073  * <a href="https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_ansi">`ANSI`</a> SQL modes.
0074  * Servers don't report whether this mode is enabled to clients.
0075  * This SQL mode is not directly supported by this function.
0076  * \n
0077  * `opts.charset` should identify the connection's character set (as given by the
0078  * `character_set_client` session variable). The character set is used to iterate
0079  * over the input string. It must be an ASCII-compatible character set (like \ref utf8mb4_charset).
0080  * All character sets allowed by `character_set_client` satisfy this requirement.
0081  * \n
0082  * You can use \ref any_connection::format_opts to retrieve an `opts` value suitable for your connection.
0083  * \n
0084  * \par Exception safety
0085  * Basic guarantee. Memory allocations may throw.
0086  *
0087  * \par Complexity
0088  * Linear in `input.size()`.
0089  *
0090  * \par Errors
0091  * \ref client_errc::invalid_encoding if `input` contains a string
0092  *      that is not valid according to `opts.charset`.
0093  */
0094 template <BOOST_MYSQL_OUTPUT_STRING OutputString>
0095 BOOST_ATTRIBUTE_NODISCARD error_code
0096 escape_string(string_view input, const format_options& opts, quoting_context quot_ctx, OutputString& output)
0097 {
0098     output.clear();
0099     return detail::escape_string(
0100         input,
0101         opts,
0102         static_cast<char>(quot_ctx),
0103         detail::output_string_ref::create(output)
0104     );
0105 }
0106
0107 }  // namespace mysql
0108 }  // namespace boost
0109
0110 #endif