1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
|
<!DOCTYPE html>
<html lang="en" data-bs-theme="light">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="shortcut icon" href="../../img/favicon.ico">
<title>Backend API - SOCI (4.1.2)</title>
<link href="../../css/bootstrap.min.css" rel="stylesheet">
<link href="../../css/fontawesome.min.css" rel="stylesheet">
<link href="../../css/brands.min.css" rel="stylesheet">
<link href="../../css/solid.min.css" rel="stylesheet">
<link href="../../css/v4-font-face.min.css" rel="stylesheet">
<link href="../../css/base.css" rel="stylesheet">
<link id="hljs-light" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" >
<link id="hljs-dark" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github-dark.min.css" disabled>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>
</head>
<body>
<div class="navbar fixed-top navbar-expand-lg navbar-dark bg-primary">
<div class="container">
<a class="navbar-brand" href="../..">SOCI (4.1.2)</a>
<!-- Expander button -->
<button type="button" class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#navbar-collapse" aria-controls="navbar-collapse" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<!-- Expanded navigation -->
<div id="navbar-collapse" class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li class="nav-item">
<a href="../.." class="nav-link">Home</a>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Overview</a>
<ul class="dropdown-menu">
<li>
<a href="../../quickstart/" class="dropdown-item">Getting Started</a>
</li>
<li>
<a href="../../installation/" class="dropdown-item">Installation</a>
</li>
<li>
<a href="../../structure/" class="dropdown-item">Library Structure</a>
</li>
<li>
<a href="../../license/" class="dropdown-item">License</a>
</li>
<li>
<a href="../../faq/" class="dropdown-item">FAQ</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">User Guide</a>
<ul class="dropdown-menu">
<li>
<a href="../../connections/" class="dropdown-item">Connections</a>
</li>
<li>
<a href="../../queries/" class="dropdown-item">Queries</a>
</li>
<li>
<a href="../../binding/" class="dropdown-item">Data Binding</a>
</li>
<li>
<a href="../../indicators/" class="dropdown-item">Data Indicators</a>
</li>
<li>
<a href="../../types/" class="dropdown-item">Data Types</a>
</li>
<li>
<a href="../../lobs/" class="dropdown-item">LOBs</a>
</li>
<li>
<a href="../../statements/" class="dropdown-item">Statements</a>
</li>
<li>
<a href="../../transactions/" class="dropdown-item">Transactions</a>
</li>
<li>
<a href="../../procedures/" class="dropdown-item">Procedures</a>
</li>
<li>
<a href="../../errors/" class="dropdown-item">Errors</a>
</li>
<li>
<a href="../../logging/" class="dropdown-item">Logging</a>
</li>
<li>
<a href="../../interfaces/" class="dropdown-item">Interfaces</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Backends</a>
<ul class="dropdown-menu">
<li>
<a href="../../backends/" class="dropdown-item">Features</a>
</li>
<li>
<a href="../../backends/db2/" class="dropdown-item">DB2</a>
</li>
<li>
<a href="../../backends/firebird/" class="dropdown-item">Firebird</a>
</li>
<li>
<a href="../../backends/mysql/" class="dropdown-item">MySQL</a>
</li>
<li>
<a href="../../backends/odbc/" class="dropdown-item">ODBC</a>
</li>
<li>
<a href="../../backends/oracle/" class="dropdown-item">Oracle</a>
</li>
<li>
<a href="../../backends/postgresql/" class="dropdown-item">PostgreSQL</a>
</li>
<li>
<a href="../../backends/sqlite3/" class="dropdown-item">SQLite3</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Miscellaneous</a>
<ul class="dropdown-menu">
<li>
<a href="../../beyond/" class="dropdown-item">Beyond SQL</a>
</li>
<li>
<a href="../../multithreading/" class="dropdown-item">Multi-threading</a>
</li>
<li>
<a href="../../boost/" class="dropdown-item">Boost</a>
</li>
<li>
<a href="../../utilities/" class="dropdown-item">Utilities</a>
</li>
<li>
<a href="../../vagrant/" class="dropdown-item">Vagrant</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle active" aria-current="page" role="button" data-bs-toggle="dropdown" aria-expanded="false">API</a>
<ul class="dropdown-menu">
<li>
<a href="../client/" class="dropdown-item">Client API</a>
</li>
<li>
<a href="./" class="dropdown-item active" aria-current="page">Backend API</a>
</li>
<li class="dropdown-submenu">
<a href="#" class="dropdown-item">Ada</a>
<ul class="dropdown-menu">
<li>
<a href="../../languages/ada/" class="dropdown-item">Ada Bindings</a>
</li>
<li>
<a href="../../languages/ada/concepts/" class="dropdown-item">Ada Concepts</a>
</li>
<li>
<a href="../../languages/ada/idioms/" class="dropdown-item">Ada Idioms</a>
</li>
<li>
<a href="../../languages/ada/reference/" class="dropdown-item">Ada API Reference</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav ms-md-auto">
<li class="nav-item">
<a href="#" class="nav-link" data-bs-toggle="modal" data-bs-target="#mkdocs_search_modal">
<i class="fa fa-search"></i> Search
</a>
</li>
<li class="nav-item">
<a rel="prev" href="../client/" class="nav-link">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
<li class="nav-item">
<a rel="next" href="../../languages/ada/" class="nav-link">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
<li class="nav-item">
<a href="https://github.com/SOCI/soci/edit/master/docs/api/backend.md" class="nav-link"><i class="fa-brands fa-github"></i> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-3"><div class="navbar-expand-md bs-sidebar hidden-print affix" role="complementary">
<div class="navbar-header">
<button type="button" class="navbar-toggler collapsed" data-bs-toggle="collapse" data-bs-target="#toc-collapse" title="Table of Contents">
<span class="fa fa-angle-down"></span>
</button>
</div>
<div id="toc-collapse" class="navbar-collapse collapse card bg-body-tertiary">
<ul class="nav flex-column">
<li class="nav-item" data-bs-level="1"><a href="#backends-reference" class="nav-link">Backends reference</a>
<ul class="nav flex-column">
</ul>
</li>
</ul>
</div>
</div></div>
<div class="col-md-9" role="main">
<h1 id="backends-reference">Backends reference</h1>
<p>This part of the documentation is provided for those who want to write (and contribute!) their
own backends. It is anyway recommendedthat authors of new backend see the code of some existing
backend forhints on how things are really done.</p>
<p>The backend interface is a set of base classes that the actual backendsare supposed to specialize.
The main SOCI interface uses only theinterface and respecting the protocol (for example,
the order of function calls) described here.
Note that both the interface and theprotocol were initially designed with the Oracle database in
mind, which means that whereas it is quite natural with respect to the way Oracle API (OCI) works,
it might impose some implementation burden on otherbackends, where things are done differently
and therefore have to beadjusted, cached, converted, etc.</p>
<p>The interface to the common SOCI interface is defined in the <code>core/soci-backend.h</code> header file.
This file is dissected below.</p>
<p>All names are defined in either <code>soci</code> or <code>soci::details</code> namespace.</p>
<pre><code class="language-cpp">// data types, as seen by the user
enum data_type
{
dt_string, dt_date, dt_double, dt_integer, dt_long_long, dt_unsigned_long_long
};
// data types, as seen by the user
enum db_type
{
db_string,
db_wstring,
db_int8,
db_uint8,
db_int16,
db_uint16,
db_int32,
db_uint32,
db_int64,
db_uint64,
db_double,
db_date,
db_blob,
db_xml
};
// the enum type for indicator variables
enum indicator { i_ok, i_null, i_truncated };
// data types, as used to describe exchange format
enum exchange_type
{
x_char,
x_stdstring,
x_stdwstring,
x_int8,
x_uint8,
x_int16,
x_short = x_int16,
x_uint16,
x_int32,
x_integer = x_int32,
x_uint32,
x_int64,
x_long_long = x_int64,
x_uint64,
x_unsigned_long_long = x_uint64,
x_double,
x_stdtm,
x_statement,
x_rowid,
x_blob,
x_xmltype,
x_longstring
};
struct cstring_descriptor
{
cstring_descriptor(char * str, std::size_t bufSize)
: str_(str), bufSize_(bufSize) {}
char * str_;
std::size_t bufSize_;
};
// actually in error.h:
class soci_error : public std::runtime_error
{
public:
soci_error(std::string const & msg);
};
</code></pre>
<p>The <code>data_type</code> and <code>db_type</code> enumeration type defines all types that form the core type support for SOCI.
The enum itself can be used by clients when dealing with dynamic rowset description.
<code>data_type</code> is deprecated in favor of <code>db_type</code>, so users are encouraged to use the latter.</p>
<p>The <code>indicator</code> enumeration type defines all recognized <em>states</em> of data.
The <code>i_truncated</code> state is provided for the case where the string is retrieved from the database
into the char buffer that is not long enough to hold the whole value.</p>
<p>The <code>exchange_type</code> enumeration type defines all possible types that can be used
with the <code>into</code> and <code>use</code> elements.</p>
<p>The <code>cstring_descriptor</code> is a helper class that allows to store the address of <code>char</code> buffer
together with its size.
The objects of this class are passed to the backend when the <code>x_cstring</code> type is involved.</p>
<p>The <code>soci_error</code> class is an exception type used for database-related (and also usage-related) errors.
The backends should throw exceptions of this or derived type only.</p>
<pre><code class="language-cpp">class standard_into_type_backend
{
public:
standard_into_type_backend() {}
virtual ~standard_into_type_backend() {}
virtual void define_by_pos(int& position, void* data, exchange_type type) = 0;
virtual void pre_fetch() = 0;
virtual void post_fetch(bool gotData, bool calledFromFetch, indicator* ind) = 0;
virtual void clean_up() = 0;
};
</code></pre>
<p>The <code>standard_into_type_back_end</code> class implements the dynamic interactions with the simple
(non-bulk) <code>into</code> elements.
The objects of this class (or, rather, of the derived class implemented by the actual backend)
are created by the <code>statement</code> object when the <code>into</code> element is bound - in terms of lifetime
management, <code>statement</code> is the master of this class.</p>
<ul>
<li><code>define_by_pos</code> - Called when the <code>into</code> element is bound, once and before the statement is executed. The <code>data</code> pointer points to the variable used for <code>into</code> element (or to the <code>cstring_descriptor</code> object, which is artificially created when the plain <code>char</code> buffer is used for data exchange). The <code>position</code> parameter is a "column number", assigned by the library. The backend should increase this parameter, according to the number of fields actually taken (usually 1).</li>
<li><code>pre_fetch</code> - Called before each row is fetched.</li>
<li><code>post_fetch</code> - Called after each row is fetched. The <code>gotData</code> parameter is <code>true</code> if the fetch operation really retrievedsome data and <code>false</code> otherwise; <code>calledFromFetch</code> is <code>true</code> when the call is from the fetch operation and <code>false</code> if it is from the execute operation (this is also the case for simple, one-time queries). In particular, <code>(calledFromFetch && !gotData)</code> indicates that there is an end-of-rowset condition. <code>ind</code> points to the indicator provided by the user, or is <code>NULL</code>, if there is no indicator.</li>
<li><code>clean_up</code> - Called once when the statement is destroyed.</li>
</ul>
<p>The intended use of <code>pre_fetch</code> and <code>post_fetch</code> functions is to manage any internal buffer and/or data conversion foreach value retrieved from the database.
If the given server supportsbinary data transmission and the data format for the given type agreeswith what is used on the client machine, then these two functions neednot do anything; otherwise buffer management and data conversionsshould go there.</p>
<pre><code class="language-cpp">class vector_into_type_backend
{
public:
vector_into_type_backend() {}
virtual ~vector_into_type_backend() {}
virtual void define_by_pos(int& position, void* data, exchange_type type) = 0;
virtual void pre_fetch() = 0;
virtual void post_fetch(bool gotData, indicator* ind) = 0;
virtual void resize(std::size_t sz) = 0;
virtual std::size_t size() = 0;
virtual void clean_up() = 0;
};
</code></pre>
<p>The <code>vector_into_type_back_end</code> has similar structure and purpose as the previous one, but is used for vectors (bulk data retrieval).</p>
<p>The <code>data</code> pointer points to the variable of type <code>std::vector<T>;</code> (and <em>not</em> to its internal buffer), <code>resize</code> is supposed to really resize the user-provided vector and <code>size</code> is supposed to return the current size of this vector.
The important difference with regard to the previous class is that <code>ind</code> points (if not <code>NULL</code>) to the beginning of the <em>array</em> of indicators.
The backend should fill this array according to the actual state of the retrieved data.</p>
<ul>
<li><code>bind_by_pos</code> - Called for each <code>use</code> element, once and before the statement is executed - for those <code>use</code> elements that do not provide explicit names for parameter binding. The meaning of parameters is same as in previous classes.</li>
<li><code>bind_by_name</code> - Called for those <code>use</code> elements that provide the explicit name.</li>
<li><code>pre_use</code> - Called before the data is transmitted to the server (this means before the statement is executed, which can happen many times for the prepared statement). <code>ind</code> points to the indicator provided by the user (or is <code>NULL</code>).</li>
<li><code>post_use</code> - Called after statement execution. <code>gotData</code> and <code>ind</code> have the same meaning as in <code>standard_into_type_back_end::post_fetch</code>, and this can be used by those backends whose respective servers support two-way data exchange (like in/out parameters in stored procedures).</li>
</ul>
<p>The intended use for <code>pre_use</code> and <code>post_use</code> methods is to manage any internal buffers and/or data conversion.
They can be called many times with the same statement.</p>
<pre><code class="language-cpp">class vector_use_type_backend
{
public:
virtual ~vector_use_type_backend() {}
virtual void bind_by_pos(int& position,
void* data, exchange_type type) = 0;
virtual void bind_by_name(std::string const& name,
void* data, exchange_type type) = 0;
virtual void pre_use(indicator const* ind) = 0;
virtual std::size_t size() = 0;
virtual void clean_up() = 0;
};
</code></pre>
<p>Objects of this type (or rather of type derived from this one) are used to implement interactions with user-provided vector (bulk) <code>use</code> elements and are managed by the <code>statement</code> object.
The <code>data</code> pointer points to the whole vector object provided by the user (and <em>not</em> to its internal buffer); <code>ind</code> points to the beginning of the array of indicators (or is <code>NULL</code>).
The meaning of this interface is analogous to those presented above.</p>
<pre><code class="language-cpp">class statement_backend
{
public:
statement_backend() {}
virtual ~statement_backend() {}
virtual void alloc() = 0;
virtual void clean_up() = 0;
virtual void prepare(std::string const& query, statement_type eType) = 0;
enum exec_fetch_result
{
ef_success,
ef_no_data
};
virtual exec_fetch_result execute(int number) = 0;
virtual exec_fetch_result fetch(int number) = 0;
virtual long long get_affected_rows() = 0;
virtual int get_number_of_rows() = 0;
virtual std::string rewrite_for_procedure_call(std::string const& query) = 0;
virtual int prepare_for_describe() = 0;
virtual void describe_column(int colNum,
db_type& dbtype,
std::string& column_name) = 0;
virtual standard_into_type_backend* make_into_type_backend() = 0;
virtual standard_use_type_backend* make_use_type_backend() = 0;
virtual vector_into_type_backend* make_vector_into_type_backend() = 0;
virtual vector_use_type_backend* make_vector_use_type_backend() = 0;
};
</code></pre>
<p>The <code>statement_backend</code> type implements the internals of the <code>statement</code> objects.
The objects of this class are created by the <code>session</code> object.</p>
<ul>
<li><code>alloc</code> - Called once to allocate everything that is needed for the statement to work correctly.</li>
<li><code>clean_up</code> - Supposed to clean up the resources, called once.</li>
<li><code>prepare</code> - Called once with the text of the SQL query. For servers that support explicit query preparation, this is the place to do it.</li>
<li><code>execute</code> - Called to execute the query; if number is zero, the intent is not to exchange data with the user-provided objects (<code>into</code> and <code>use</code> elements); positive values mean the number of rows to exchange (more than 1 is used only for bulk operations).</li>
<li><code>fetch</code> - Called to fetch next bunch of rows; number is positive and determines the requested number of rows (more than 1 is used only for bulk operations).</li>
<li><code>get_affected_rows</code> - Called to determine the actual number of rows affected by data modifying statement.</li>
<li><code>get_number_of_rows</code> - Called to determine the actual number of rows retrieved by the previous call to <code>execute</code> or <code>fetch</code>.</li>
<li><code>rewrite_for_procedure_call</code> - Used when the <code>procedure</code> is used instead of <code>statement</code>, to call the stored procedure. This function should rewrite the SQL query (if necessary) to the form that will allow to execute the given procedure.</li>
<li><code>prepare_for_describe</code> - Called once when the <code>into</code> element is used with the <code>row</code> type, which means that dynamic rowset description should be performed. It is supposed to do whatever is needed to later describe the column properties and should return the number of columns.</li>
<li><code>describe_column</code> - Called once for each column (column numbers - <code>colNum</code> - start from 1), should fill its parameters according to the column properties.</li>
<li><code>make_into_type_backend</code>, <code>make_use_type_backend</code>, <code>make_vector_into_type_backend</code>, <code>make_vector_use_type_backend</code> - Called once for each <code>into</code> or <code>use</code> element, to create the objects of appropriate classes (described above).</li>
</ul>
<p><strong>Notes:</strong></p>
<ol>
<li>Whether the query is executed using the simple one-time syntax or is prepared, the <code>alloc</code>, <code>prepare</code> and <code>execute</code> functions are always called, in this order.</li>
<li>All <code>into</code> and <code>use</code> elements are bound (their <code>define_by_pos</code> or <code>bind_by_pos</code>/<code>bind_by_name</code> functions are called) <em>between</em> statement preparation and execution.</li>
</ol>
<pre><code class="language-cpp">class rowid_backend
{
public:
virtual ~rowid_backend() {}
};
</code></pre>
<p>The <code>rowid_backend</code> class is a hook for the backends to provide their own state for the row identifier. It has no functions, since the only portable interaction with the row identifier object is to use it with <code>into</code> and <code>use</code> elements.</p>
<pre><code class="language-cpp">class blob_backend
{
public:
virtual ~blob_backend() {}
virtual std::size_t get_len() = 0;
virtual std::size_t read(std::size_t offset, char * buf,
std::size_t toRead) = 0;
virtual std::size_t write(std::size_t offset, char const * buf,
std::size_t toWrite) = 0;
virtual std::size_t append(char const * buf, std::size_t toWrite) = 0;
virtual void trim(std::size_t newLen) = 0;
};
</code></pre>
<p>The <code>blob_backend</code> interface provides the entry points for the <code>blob</code> methods.</p>
<pre><code class="language-cpp">class session_backend
{
public:
virtual ~session_backend() {}
virtual void begin() = 0;
virtual void commit() = 0;
virtual void rollback() = 0;
virtual bool get_next_sequence_value(session&, std::string const&, long long&);
virtual bool get_last_insert_id(session&, std::string const&, long long&);
virtual std::string get_backend_name() const = 0;
virtual statement_backend * make_statement_backend() = 0;
virtual rowid_backend * make_rowid_backend() = 0;
virtual blob_backend * make_blob_backend() = 0;
};
</code></pre>
<p>The object of the class derived from <code>session_backend</code> implements the internals of the <code>session</code> object.</p>
<ul>
<li><code>begin</code>, <code>commit</code>, <code>rollback</code> - Forward-called when the same functions of <code>session</code> are called by user.</li>
<li><code>get_next_sequence_value</code>, <code>get_last_insert_id</code> - Called to retrieve sequences or auto-generated values and every backend should define at least one of them to allow the code using auto-generated values to work.</li>
<li><code>make_statement_backend</code>, <code>make_rowid_backend</code>, <code>make_blob_backend</code> - Called to create respective implementations for the <code>statement</code>, <code>rowid</code> and <code>blob</code> classes.</li>
</ul>
<pre><code class="language-cpp">struct backend_factory
{
virtual ~backend_factory() {}
virtual details::session_backend * make_session(
std::string const& connectString) const = 0;
};
</code></pre>
<p>The <code>backend_factory</code> is a base class for backend-provided factory class that is able to create valid sessions. The <code>connectString</code> parameter passed to <code>make_session</code> is provided here by the <code>session</code> constructor and contains only the backend-related parameters, without the backend name (if the dynamic backend loading is used).</p>
<p>The actual backend factory object is supposed to be provided by the backend implementation and declared in its header file. In addition to this, the <code>factory_ABC</code> function with the "C" calling convention and returning the pointer to concrete factory object should be provided, where <code>ABC</code> is the backend name.</p>
<p>The following example is taken from <code>soci-postgresql.h</code>, which declares entities of the PostgreSQL backend:</p>
<pre><code class="language-cpp">struct postgresql_backend_factory : backend_factory
{
virtual postgresql_session_backend* make_session(
std::string const& connectString) const;
};
extern postgresql_backend_factory const postgresql;
extern "C"
{
// for dynamic backend loading
backend_factory const * factory_postgresql();
} // extern "C"
</code></pre>
<p>With the above declarations, it is enough to pass the <code>postgresql</code> factory name to the constructor of the <code>session</code> object, which will use this factory to create concrete implementations for any other objects that are needed, with the help of appropriate <code>make_XYZ</code> functions. Alternatively, the <code>factory_postgresql</code> function will be called automatically by the backend loader if the backend name is provided at run-time instead.</p>
<p>Note that the backend source code is placed in the <code>backends/*name*</code> directory (for example, <code>backends/oracle</code>) and the test driver is in <code>backends/*name*/test</code>. There is also <code>backends/empty</code> directory provided as a skeleton for development of new backends and their tests. It is recommended that all backends respect naming conventions by just appending their name to the base-class names. The backend name used for the global factory object should clearly identify the given database engine, like <code>oracle</code>, <code>postgresql</code>, <code>mysql</code>, and so on.</p></div>
</div>
</div>
<footer class="col-md-12">
<hr>
<p>Copyright © 2017-2025 <a href="https://soci.sourceforge.net/people.html">SOCI Team</a>.</p>
<p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</p>
</footer>
<script src="../../js/bootstrap.bundle.min.js"></script>
<script>
var base_url = "../..",
shortcuts = {"help": 191, "next": 78, "previous": 80, "search": 83};
</script>
<script src="../../js/base.js"></script>
<script src="../../search/main.js"></script>
<div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="searchModalLabel" aria-hidden="true">
<div class="modal-dialog modal-lg">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="searchModalLabel">Search</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<p>From here you can search these documents. Enter your search terms below.</p>
<form>
<div class="form-group">
<input type="search" class="form-control" placeholder="Search..." id="mkdocs-search-query" title="Type search term here">
</div>
</form>
<div id="mkdocs-search-results" data-no-results-text="No results found"></div>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div><div class="modal" id="mkdocs_keyboard_modal" tabindex="-1" role="dialog" aria-labelledby="keyboardModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<table class="table">
<thead>
<tr>
<th style="width: 20%;">Keys</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td class="help shortcut"><kbd>?</kbd></td>
<td>Open this help</td>
</tr>
<tr>
<td class="next shortcut"><kbd>n</kbd></td>
<td>Next page</td>
</tr>
<tr>
<td class="prev shortcut"><kbd>p</kbd></td>
<td>Previous page</td>
</tr>
<tr>
<td class="search shortcut"><kbd>s</kbd></td>
<td>Search</td>
</tr>
</tbody>
</table>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div>
</body>
</html>
|
