boost/mysql
2
0
Fork 0
mirror of https://github.com/boostorg/mysql.git synced 2026-02-17 01:42:17 +00:00
Code Issues Projects Releases Wiki Activity

Reviewed doxygen docs (connection & params)

Browse Source
This commit is contained in:
ruben
2020-04-07 15:20:46 +01:00
parent dfd556d5d0
commit da2e13848a
6 changed files with 105 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
TODO.txt
View File

@@ -1,3 +1,9 @@
Docs
Home page
Examples
Make undocumented enum values show
Autogen
Read the docs
Multiresultset
Text protocol
Binary protocol (stored procedures)

1
include/boost/mysql/collation.hpp
View File

@@ -7,6 +7,7 @@ namespace boost {
namespace mysql {
/**
* \ingroup connparams
* \brief A character set and a collation.
* \details Names and ids for this enum correspond to the "Collation" and "Id"
* fields returned by MySQL "SHOW COLLATION" statement.

32
include/boost/mysql/connection.hpp
View File

@@ -2,18 +2,26 @@
#define MYSQL_ASIO_CONNECTION_HPP
#include "boost/mysql/detail/protocol/channel.hpp"
#include "boost/mysql/detail/network_algorithms/handshake.hpp"
#include "boost/mysql/detail/protocol/protocol_types.hpp"
#include "boost/mysql/detail/network_algorithms/handshake.hpp"
#include "boost/mysql/detail/auxiliar/async_result_macro.hpp"
#include "boost/mysql/error.hpp"
#include "boost/mysql/resultset.hpp"
#include "boost/mysql/prepared_statement.hpp"
#include "boost/mysql/connection_params.hpp"
#include <boost/asio/ip/tcp.hpp>
/**
* \defgroup connection Connection
* \brief Classes and functions related to establishing
* connections with the MySQL server.
*/
namespace boost {
namespace mysql {
/**
* \ingroup connection
* \brief A connection to a MySQL server.
* \details
* This is the basic object to instantiate to use the MySQL-Asio library.
@@ -89,17 +97,17 @@ public:
* until the operation completes, as no copy is made by the library.
*/
template <typename CompletionToken>
BOOST_ASIO_INITFN_RESULT_TYPE(CompletionToken, handshake_signature)
BOOST_MYSQL_INITFN_RESULT_TYPE(CompletionToken, handshake_signature)
async_handshake(const connection_params& params, CompletionToken&& token, error_info* info = nullptr);
/**
* \brief Executes a SQL text query (sync with error code version).
* \detail Does not perform the actual retrieval of the data; use the various
* \details Does not perform the actual retrieval of the data; use the various
* fetch functions within resultset to achieve that.
* \see resultset
*
* Note that query_string may contain any valid SQL, not just SELECT statements.
* If your query does not return any data, then the resultset will be empty
* (\see resultset for more details).
* If your query does not return any data, then the resultset will be empty.
*
* \warning After query() has returned, you should read the entire resultset
* before calling any function that involves communication with the server over this
@@ -116,7 +124,7 @@ public:
/// Executes a SQL text query (async version).
template <typename CompletionToken>
BOOST_ASIO_INITFN_RESULT_TYPE(CompletionToken, query_signature)
BOOST_MYSQL_INITFN_RESULT_TYPE(CompletionToken, query_signature)
async_query(std::string_view query_string, CompletionToken&& token, error_info* info=nullptr);
/**
@@ -140,16 +148,22 @@ public:
/// Prepares a statement (async version).
template <typename CompletionToken>
BOOST_ASIO_INITFN_RESULT_TYPE(CompletionToken, prepare_statement_signature)
BOOST_MYSQL_INITFN_RESULT_TYPE(CompletionToken, prepare_statement_signature)
async_prepare_statement(std::string_view statement, CompletionToken&& token, error_info* info=nullptr);
};
/// A connection to MySQL over TCP.
/**
* \ingroup connection
* \brief A connection to MySQL over a TCP socket.
*/
using tcp_connection = connection<boost::asio::ip::tcp::socket>;
// TODO: UNIX socket connection
/// The default TCP port for the MySQL protocol.
/**
* \ingroup connection
* \brief The default TCP port for the MySQL protocol.
*/
constexpr unsigned short default_port = 3306;
} // mysql

21
include/boost/mysql/connection_params.hpp
View File

@@ -4,10 +4,19 @@
#include <string_view>
#include "boost/mysql/collation.hpp"
/**
* \defgroup connparams Connection parameters
* \ingroup connection
* \brief Parameters for estabilishing the connection to the MySQL server.
*/
namespace boost {
namespace mysql {
/// Determines whether to use TLS for the connection or not.
/**
* \ingroup connparams
* \brief Determines whether to use TLS for the connection or not.
*/
enum class ssl_mode
{
disable, ///< Never use TLS
@@ -16,8 +25,9 @@ enum class ssl_mode
};
/**
* \ingroup connparams
* \brief Connection options regarding TLS.
* \details At the moment, contains only the \ref ssl_mode, which
* \details At the moment, contains only the ssl_mode, which
* indicates whether to use TLS on the connection or not.
*/
class ssl_options
@@ -27,7 +37,7 @@ public:
/**
* \brief Default and initialization constructor.
* \details By default, SSL is enabled for the connection
* if the server supports is (\ref ssl_mode::enable).
* if the server supports is (ssl_mode::enable).
*/
explicit ssl_options(ssl_mode mode=ssl_mode::enable) noexcept:
mode_(mode) {}
@@ -38,6 +48,7 @@ public:
/**
* \ingroup connparams
* \brief Parameters defining how to authenticate to a MySQL server.
*/
class connection_params
@@ -95,8 +106,8 @@ public:
void set_ssl(const ssl_options& value) noexcept { ssl_ = value; }
};
}
}
} // mysql
} // boost

13
include/boost/mysql/detail/auxiliar/async_result_macro.hpp Normal file
View File

@@ -0,0 +1,13 @@
#ifndef INCLUDE_BOOST_MYSQL_DETAIL_AUXILIAR_ASYNC_RESULT_MACRO_HPP_
#define INCLUDE_BOOST_MYSQL_DETAIL_AUXILIAR_ASYNC_RESULT_MACRO_HPP_
#include <boost/asio/async_result.hpp>
#ifdef BOOST_MYSQL_DOXYGEN
#define BOOST_MYSQL_INITFN_RESULT_TYPE(ct, sig) DEDUCED
#else
#define BOOST_MYSQL_INITFN_RESULT_TYPE(ct, sig) \
BOOST_ASIO_INITFN_RESULT_TYPE(ct, sig)
#endif
#endif /* INCLUDE_BOOST_MYSQL_DETAIL_AUXILIAR_ASYNC_RESULT_MACRO_HPP_ */

61
include/boost/mysql/error.hpp
View File

@@ -4,33 +4,54 @@
#include <boost/system/error_code.hpp>
#include <string>
/**
* \defgroup error Error handling
* \brief Classes and functions used in error handling.
*/
namespace boost {
namespace mysql {
/// MySQL-specific error codes.
/**
* \ingroup error
* \brief MySQL-specific error codes.
* \details Some error codes are defined by the client library, and others
* are returned from the server. For the latter, the numeric value and
* string descriptions match the ones described in the MySQL documentation.
* Only the first ones are documented here. For the latter, see
* https://dev.mysql.com/doc/refman/8.0/en/server-error-reference.html
*/
enum class errc : int
{
// OK
ok = 0,
ok = 0, ///< No error.
// Server returned errors
#include "boost/mysql/impl/server_error_enum.hpp"
// Protocol errors
incomplete_message = 0x10000,
extra_bytes,
sequence_number_mismatch,
server_unsupported,
protocol_value_error,
unknown_auth_plugin,
auth_plugin_requires_ssl,
wrong_num_params
incomplete_message = 0x10000, ///< An incomplete message was received from the server.
extra_bytes, ///< Unexpected extra bytes at the end of a message were received.
sequence_number_mismatch, ///< A sequence number mismatched happened.
server_unsupported, ///< The server does not support the minimum required capabilities to establish the connection.
protocol_value_error, ///< An unexpected value was found in a server-received message.
unknown_auth_plugin, ///< The user employs an authentication plugin not known to this library.
auth_plugin_requires_ssl, ///< The authentication plugin requires the connection to use SSL.
wrong_num_params ///< The number of parameters passed to the prepared statement does not match the number of actual parameters.
};
/// An alias for boost::system error codes.
/**
* \ingroup error
* \brief An alias for boost::system error codes.
*/
using error_code = boost::system::error_code;
/// Additional information about error conditions
/**
* \ingroup error
* \brief Additional information about error conditions
* \details Contains an error message describing what happened. Not all error
* conditions are able to generate this extended information - those that
* can't have an empty error message.
*/
class error_info
{
std::string msg_;
@@ -51,12 +72,22 @@ public:
void clear() noexcept { msg_.clear(); }
};
/// Compare two error infos.
/**
* \relates error_info
* \brief Compare two error_info objects.
*/
inline bool operator==(const error_info& lhs, const error_info& rhs) noexcept { return lhs.message() == rhs.message(); }
/// Compare two error infos.
/**
* \relates error_info
* \brief Compare two error_info objects.
*/
inline bool operator!=(const error_info& lhs, const error_info& rhs) noexcept { return !(lhs==rhs); }
/**
* \relates error_info
* \brief Streams an error_info.
*/
inline std::ostream& operator<<(std::ostream& os, const error_info& v) { return os << v.message(); }
} // mysql