MySQL Connector/C++
MySQL connector library for C and C++ applications
Loading...
Searching...
No Matches
settings.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2015, 2022, Oracle and/or its affiliates.
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License, version 2.0, as
6 * published by the Free Software Foundation.
7 *
8 * This program is also distributed with certain software (including
9 * but not limited to OpenSSL) that is licensed under separate terms,
10 * as designated in a particular file or component or in included license
11 * documentation. The authors of MySQL hereby grant you an
12 * additional permission to link the program and your derivative works
13 * with the separately licensed software that they have included with
14 * MySQL.
15 *
16 * Without limiting anything contained in the foregoing, this file,
17 * which is part of MySQL Connector/C++, is also subject to the
18 * Universal FOSS Exception, version 1.0, a copy of which can be found at
19 * http://oss.oracle.com/licenses/universal-foss-exception.
20 *
21 * This program is distributed in the hope that it will be useful, but
22 * WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
24 * See the GNU General Public License, version 2.0, for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with this program; if not, write to the Free Software Foundation, Inc.,
28 * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
29 */
30
31#ifndef MYSQLX_DEVAPI_SETTINGS_H
32#define MYSQLX_DEVAPI_SETTINGS_H
33
39#include "common.h"
40#include "detail/settings.h"
41
42
43namespace mysqlx {
44MYSQLX_ABI_BEGIN(2,0)
45
46
47/*
48 TODO: Cross-references to session options inside Doxygen docs do not work.
49*/
50
51
63{
64#define SESS_OPT_ENUM_any(X,N) X = N,
65#define SESS_OPT_ENUM_bool(X,N) X = N,
66#define SESS_OPT_ENUM_num(X,N) X = N,
67#define SESS_OPT_ENUM_str(X,N) X = N,
68#define SESS_OPT_ENUM_bool(X,N) X = N,
69
70public:
71
72 enum Enum {
73 SESSION_OPTION_LIST(SESS_OPT_ENUM)
74 LAST
75 };
76
77 SessionOption(Enum opt)
78 : m_opt(opt)
79 {}
80
82 {}
83
84 bool operator==(const SessionOption &other) const
85 {
86 return m_opt == other.m_opt;
87 }
88
89 bool operator==(Enum opt) const
90 {
91 return m_opt == opt;
92 }
93
94 bool operator!=(Enum opt) const
95 {
96 return m_opt != opt;
97 }
98
99 operator int()
100 {
101 return m_opt;
102 }
103
104protected:
105 int m_opt = LAST;
106};
107
108
114 : protected SessionOption
115{
116
117#define CLIENT_OPT_ENUM_any(X,N) X = -N,
118#define CLIENT_OPT_ENUM_bool(X,N) X = -N,
119#define CLIENT_OPT_ENUM_num(X,N) X = -N,
120#define CLIENT_OPT_ENUM_str(X,N) X = -N,
121
122
123public:
124
125 using SessionEnum = SessionOption::Enum;
126
127 enum Enum {
128 CLIENT_OPTION_LIST(CLIENT_OPT_ENUM)
129 };
130
132 {}
133
135 : SessionOption(opt)
136 {}
137
138 ClientOption(Enum opt)
139 {
140 m_opt = opt;
141 }
142
143 ClientOption(SessionEnum opt)
144 : SessionOption(opt)
145 {}
146
147 bool operator==(Enum opt) const
148 {
149 return m_opt == opt;
150 }
151
152 bool operator==(SessionEnum opt) const
153 {
154 return SessionOption::operator==(opt);
155 }
156
157 bool operator!=(Enum opt) const
158 {
159 return m_opt != opt;
160 }
161
162 bool operator!=(SessionEnum opt) const
163 {
164 return SessionOption::operator!=(opt);
165 }
166
167 inline operator int()
168 {
169 return SessionOption::operator int();
170 }
171
172};
173
174
176// Note: Doxygen gets confused here and renders docs incorrectly.
177
178inline
179std::string OptionName(ClientOption opt)
180{
181#define CLT_OPT_NAME_any(X,N) case ClientOption::X: return #X;
182#define CLT_OPT_NAME_bool(X,N) CLT_OPT_NAME_any(X,N)
183#define CLT_OPT_NAME_num(X,N) CLT_OPT_NAME_any(X,N)
184#define CLT_OPT_NAME_str(X,N) CLT_OPT_NAME_any(X,N)
185
186#define SESS_OPT_NAME_any(X,N) case SessionOption::X: return #X;
187#define SESS_OPT_NAME_bool(X,N) SESS_OPT_NAME_any(X,N)
188#define SESS_OPT_NAME_num(X,N) SESS_OPT_NAME_any(X,N)
189#define SESS_OPT_NAME_str(X,N) SESS_OPT_NAME_any(X,N)
190#define SESS_OPT_NAME_bool(X,N) SESS_OPT_NAME_any(X,N)
191
192
193 switch (opt)
194 {
195 CLIENT_OPTION_LIST(CLT_OPT_NAME)
196 SESSION_OPTION_LIST(SESS_OPT_NAME)
197
198 default:
199 throw_error("Unexpected Option"); return "";
200 };
201}
202
204
205
206inline std::string ClientOptionName(ClientOption opt)
207{
208 return OptionName(opt);
209}
210
211inline std::string SessionOptionName(SessionOption opt)
212{
213 return OptionName(opt);
214}
215
216
222enum_class SSLMode
223{
224#define SSL_ENUM(X,N) X = N,
225
226 SSL_MODE_LIST(SSL_ENUM)
227};
228
229
231
232inline
233std::string SSLModeName(SSLMode m)
234{
235#define MODE_NAME(X,N) case SSLMode::X: return #X;
236
237 switch (m)
238 {
239 SSL_MODE_LIST(MODE_NAME)
240 default:
241 {
242 std::ostringstream buf;
243 buf << "<UKNOWN (" << unsigned(m) << ")>" << std::ends;
244 return buf.str();
245 }
246 };
247}
248
250
251
257enum_class AuthMethod
258{
259#define AUTH_ENUM(X,N) X=N,
261 AUTH_METHOD_LIST(AUTH_ENUM)
262};
263
264
266
267inline
268std::string AuthMethodName(AuthMethod m)
269{
270#define AUTH_NAME(X,N) case AuthMethod::X: return #X;
271
272 switch (m)
273 {
274 AUTH_METHOD_LIST(AUTH_NAME)
275 default:
276 {
277 std::ostringstream buf;
278 buf << "<UKNOWN (" << unsigned(m) << ")>" << std::ends;
279 return buf.str();
280 }
281 };
282}
283
285
291enum_class CompressionMode
292{
293#define COMPRESSION_ENUM(X,N) X = N,
294
295 COMPRESSION_MODE_LIST(COMPRESSION_ENUM)
296};
297
299
300inline
301std::string CompressionModeName(CompressionMode m)
302{
303#define COMPRESSION_NAME(X,N) case CompressionMode::X: return #X;
304
305 switch (m)
306 {
307 COMPRESSION_MODE_LIST(COMPRESSION_NAME)
308 default:
309 {
310 std::ostringstream buf;
311 buf << "<UKNOWN (" << unsigned(m) << ")>" << std::ends;
312 return buf.str();
313 }
314 };
315}
316
318
319
320namespace internal {
321
322
323/*
324 Encapsulate public enumerations in the Settings_traits class to be used
325 by Settings_detail<> template.
326*/
327
328struct Settings_traits
329{
330 using Options = mysqlx::SessionOption;
331 using COptions = mysqlx::ClientOption;
332 using SSLMode = mysqlx::SSLMode;
333 using AuthMethod = mysqlx::AuthMethod;
334 using CompressionMode = mysqlx::CompressionMode;
335
336 static std::string get_mode_name(SSLMode mode)
337 {
338 return SSLModeName(mode);
339 }
340
341 static std::string get_option_name(COptions opt)
342 {
343 return ClientOptionName(opt);
344 }
345
346 static std::string get_auth_name(AuthMethod m)
347 {
348 return AuthMethodName(m);
349 }
350};
351
352
353template<>
354PUBLIC_API
355void
356internal::Settings_detail<internal::Settings_traits>::
357do_set(session_opt_list_t &&opts);
358
359
360template<typename Option, typename base_iterator>
361class iterator
362{
363 base_iterator m_it;
364 std::pair<Option, mysqlx::Value> m_pair;
365
366public:
367 using iterator_category = std::input_iterator_tag;
368 using value_type = std::pair<Option, mysqlx::Value>;
369
370 iterator(const base_iterator &init) : m_it(init) {}
371
372 iterator(const iterator &init) : m_it(init.m_it) {}
373
374 std::pair<Option, mysqlx::Value> &operator*() {
375 auto &el = *m_it;
376 m_pair.first = static_cast<typename Option::Enum>(el.first);
377 m_pair.second = el.second;
378 return m_pair;
379 }
380
381 std::pair<ClientOption, mysqlx::Value>* operator->()
382 {
383 return &operator*();
384 }
385
386 iterator& operator++()
387 {
388 ++m_it;
389 return *this;
390 }
391
392 iterator& operator--()
393 {
394 --m_it;
395 return *this;
396 }
397
398 bool operator !=(const iterator &other)
399 {
400 return m_it != other.m_it;
401 }
402
403};
404
405
406} // internal namespace
407
408
409class Client;
410class Session;
411
447class SessionSettings
448 : private internal::Settings_detail<internal::Settings_traits>
449{
450 using Value = mysqlx::Value;
451
452public:
453
518 SessionSettings(const string &uri)
519 {
520 try {
521 Settings_detail::set_from_uri(uri);
522 }
523 CATCH_AND_WRAP
524 }
525
526
535 const std::string &host, unsigned port,
536 const string &user,
537 const char *pwd = NULL,
538 const string &db = string()
539 )
540 {
541 set(
542 SessionOption::HOST, host,
543 SessionOption::PORT, port,
544 SessionOption::USER, user
545 );
546
547 if (pwd)
548 set(SessionOption::PWD, std::string(pwd));
549
550 if (!db.empty())
551 set(SessionOption::DB, db);
552 }
553
555 const std::string &host, unsigned port,
556 const string &user,
557 const std::string &pwd,
558 const string &db = string()
559 )
560 : SessionSettings(host, port, user, pwd.c_str(), db)
561 {}
562
571 const std::string &host,
572 const string &user,
573 const char *pwd = NULL,
574 const string &db = string()
575 )
576 : SessionSettings(host, DEFAULT_MYSQLX_PORT, user, pwd, db)
577 {}
578
580 const std::string &host,
581 const string &user,
582 const std::string &pwd,
583 const string &db = string()
584 )
585 : SessionSettings(host, DEFAULT_MYSQLX_PORT, user, pwd, db)
586 {}
587
596 unsigned port,
597 const string &user,
598 const char *pwd = NULL,
599 const string &db = string()
600 )
601 : SessionSettings("localhost", port, user, pwd, db)
602 {}
603
605 unsigned port,
606 const string &user,
607 const std::string &pwd,
608 const string &db = string()
609 )
610 : SessionSettings("localhost", port, user, pwd.c_str(), db)
611 {}
612
613 /*
614 Templates below are here to take care of the optional password
615 parameter of type const char* (which can be either 3-rd or 4-th in
616 the parameter list). Without these templates passing
617 NULL as password is ambiguous because NULL is defined as 0,
618 which has type int, and then it could be treated as port value.
619 */
620
621 template <
622 typename HOST,
623 typename PORT,
624 typename USER,
625 typename... T,
626 typename std::enable_if<
627 std::is_constructible<SessionSettings, HOST, PORT, USER, const char*, T...>::value
628 >::type* = nullptr
629 >
630 SessionSettings(HOST h, PORT p, USER u, long, T... args)
631 : SessionSettings(h, p, u, nullptr, args...)
632 {}
633
634
635 template <
636 typename PORT,
637 typename USER,
638 typename... T,
639 typename std::enable_if<
640 std::is_constructible<SessionSettings, PORT, USER, const char*, T...>::value
641 >::type* = nullptr
642 >
643 SessionSettings(PORT p, USER u, long, T... args)
644 : SessionSettings(p, u, nullptr, args...)
645 {}
646
647
667 template <typename... R>
668 SessionSettings(SessionOption::Enum opt, R&&...rest)
669 {
670 try {
671 // set<true> means that only SessionOption can be used
672 Settings_detail::set<true>(opt, std::forward<R>(rest)...);
673 }
674 CATCH_AND_WRAP
675 }
676
677 /*
678 Return an iterator pointing to the first element of the SessionSettings.
679 */
680 using iterator = internal::iterator<SessionOption, Settings_detail::iterator>;
681
682 iterator begin()
683 {
684 try {
685 return Settings_detail::begin();
686 }
687 CATCH_AND_WRAP
688 }
689
690 /*
691 Return an iterator pointing to the last element of the SessionSettings.
692 */
693
694 iterator end()
695 {
696 try {
697 return Settings_detail::end();
698 }
699 CATCH_AND_WRAP
700 }
701
702
712 Value find(SessionOption opt)
713 {
714 try {
715 return Settings_detail::get(opt);
716 }
717 CATCH_AND_WRAP
718 }
719
735 template<typename... R>
736 void set(SessionOption opt, R&&... rest)
737 {
738 try {
739 // set<true> means that only SessionOption can be used
740 Settings_detail::set<true>(opt, std::forward<R>(rest)...);
741 }
742 CATCH_AND_WRAP
743 }
744
749 void clear()
750 {
751 try {
752 Settings_detail::clear();
753 }
754 CATCH_AND_WRAP
755 }
756
764 void erase(SessionOption opt)
765 {
766 try {
767 Settings_detail::erase(static_cast<int>(opt));
768 }
769 CATCH_AND_WRAP
770 }
771
772
777 bool has_option(SessionOption opt)
778 {
779 try {
780 return Settings_detail::has_option(opt);
781 }
782 CATCH_AND_WRAP
783 }
784
785private:
786
787 friend Client;
788 friend Session;
789};
790
791
802class ClientSettings
803 : private internal::Settings_detail<internal::Settings_traits>
804{
805
806public:
807
808 using Base = internal::Settings_detail<internal::Settings_traits>;
809 using Value = mysqlx::Value;
810
811 /*
812 Return an iterator pointing to the first element of the SessionSettings.
813 */
814
815 using iterator = internal::iterator<ClientOption, Settings_detail::iterator>;
816
817 iterator begin()
818 {
819 try {
820 return Settings_detail::begin();
821 }
822 CATCH_AND_WRAP
823 }
824
825 /*
826 Return an iterator pointing to the last element of the SessionSettings.
827 */
828
829 iterator end()
830 {
831 try {
832 return Settings_detail::end();
833 }
834 CATCH_AND_WRAP
835 }
836
843 ClientSettings(const string &uri)
844 {
845 try {
846 Settings_detail::set_from_uri(uri);
847 }
848 CATCH_AND_WRAP
849 }
850
857 ClientSettings(const string &uri, ClientSettings &opts)
858 {
859 try {
860 Settings_detail::set_from_uri(uri);
861 Settings_detail::set_client_opts(opts);
862 }
863 CATCH_AND_WRAP
864 }
865
899 ClientSettings(const string &uri, const DbDoc &options)
900 {
901 try {
902 Settings_detail::set_from_uri(uri);
903 std::stringstream str_opts;
904 str_opts << options;
905 Settings_detail::set_client_opts(str_opts.str());
906 }
907 CATCH_AND_WRAP
908 }
909
943 ClientSettings(const string &uri, const char *options)
944 {
945 try {
946 Settings_detail::set_from_uri(uri);
947 Settings_detail::set_client_opts(options);
948 }
949 CATCH_AND_WRAP
950 }
951
976 template<typename...R>
977 ClientSettings(const string &uri, mysqlx::ClientOption opt, R... rest)
978 try
979 : ClientSettings(uri)
980 {
981 // set<false> means that both SessionOption and ClientOption can be used
982 Settings_detail::set<false>(opt, std::forward<R>(rest)...);
983 }
984 CATCH_AND_WRAP
985
986
987 template <typename... R>
988 ClientSettings(mysqlx::ClientOption opt, R&&...rest)
989 {
990 try {
991 // set<false> means that both SessionOption and ClientOption can be used
992 Settings_detail::set<false>(opt, std::forward<R>(rest)...);
993 }
994 CATCH_AND_WRAP
995 }
996
1004 Value find(mysqlx::ClientOption opt)
1005 {
1006 try {
1007 return Settings_detail::get(opt);
1008 }
1009 CATCH_AND_WRAP
1010 }
1011
1028 template<typename OPT, typename... R>
1029 void set(OPT opt, R&&... rest)
1030 {
1031 try {
1032 // set<false> means that both SessionOption and ClientOption can be used
1033 Settings_detail::set<false>(opt, std::forward<R>(rest)...);
1034 }
1035 CATCH_AND_WRAP
1036 }
1037
1038
1043 void clear()
1044 {
1045 try {
1046 Settings_detail::clear();
1047 }
1048 CATCH_AND_WRAP
1049 }
1050
1055 void erase(mysqlx::ClientOption opt)
1056 {
1057 try {
1058 Settings_detail::erase(static_cast<int>(opt));
1059 }
1060 CATCH_AND_WRAP
1061 }
1062
1063
1069 {
1070 try {
1071 return Settings_detail::has_option(opt);
1072 }
1073 CATCH_AND_WRAP
1074 }
1075
1080 bool has_option(SessionOption::Enum opt)
1081 {
1082 try {
1083 return Settings_detail::has_option(opt);
1084 }
1085 CATCH_AND_WRAP
1086 }
1087
1088private:
1089 friend Client;
1090 friend Session;
1091};
1092
1093
1094MYSQLX_ABI_END(2,0)
1095} // mysqlx
1096
1097#endif
Client creation options.
Definition: settings.h:115
Enum
Definition: settings.h:127
void set(OPT opt, R &&... rest)
Set client and session options.
Definition: settings.h:1026
bool has_option(ClientOption::Enum opt)
Check if option opt was defined.
Definition: settings.h:1065
void erase(mysqlx::ClientOption opt)
Remove the given option opt.
Definition: settings.h:1052
Value find(mysqlx::ClientOption opt)
Find the specified option opt and returns its Value.
Definition: settings.h:1001
ClientSettings(const string &uri)
Create client settings from a connection string.
Definition: settings.h:840
void clear()
Clear all settings specified so far.
Definition: settings.h:1040
Session creation options.
Definition: settings.h:63
Enum
Definition: settings.h:72
bool has_option(SessionOption opt)
Check if option opt was defined.
Definition: settings.h:774
Value find(SessionOption opt)
Find the specified option opt and returns its Value.
Definition: settings.h:709
SessionSettings(const string &uri)
Create session settings from a connection string.
Definition: settings.h:515
void erase(SessionOption opt)
Remove all settings for the given option opt.
Definition: settings.h:761
void set(SessionOption opt, R &&... rest)
Set session options.
Definition: settings.h:733
void clear()
Clear all settings specified so far.
Definition: settings.h:746
Value object can store value of scalar type, string, array or document.
Definition: document.h:228
SSLMode
Modes to be used with SSL_MODE option .
Definition: settings.h:223