libpqxx 7.8.1
blob.hxx
1/* Binary Large Objects interface.
2 *
3 * Read or write large objects, stored in their own storage on the server.
4 *
5 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/largeobject instead.
6 *
7 * Copyright (c) 2000-2023, Jeroen T. Vermeulen.
8 *
9 * See COPYING for copyright license. If you did not receive a file called
10 * COPYING with this source code, please notify the distributor of this
11 * mistake, or contact the author.
12 */
13#ifndef PQXX_H_BLOB
14#define PQXX_H_BLOB
15
16#if !defined(PQXX_HEADER_PRE)
17# error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
18#endif
19
20#include <cstdint>
21
22#if defined(PQXX_HAVE_PATH)
23# include <filesystem>
24#endif
25
26#if defined(PQXX_HAVE_RANGES) && __has_include(<ranges>)
27# include <ranges>
28#endif
29
30#if defined(PQXX_HAVE_SPAN) && __has_include(<span>)
31# include <span>
32#endif
33
34#include "pqxx/dbtransaction.hxx"
35
36
37namespace pqxx
38{
52class PQXX_LIBEXPORT blob
53{
54public:
56
60 [[nodiscard]] static oid create(dbtransaction &, oid = 0);
61
63 static void remove(dbtransaction &, oid);
64
66 [[nodiscard]] static blob open_r(dbtransaction &, oid);
67 // Open blob for writing. Any attempt to read from it will fail.
68 [[nodiscard]] static blob open_w(dbtransaction &, oid);
69 // Open blob for reading and/or writing.
70 [[nodiscard]] static blob open_rw(dbtransaction &, oid);
71
73
76 blob() = default;
77
79 blob(blob &&);
81 blob &operator=(blob &&);
82
83 blob(blob const &) = delete;
84 blob &operator=(blob const &) = delete;
85 ~blob();
86
88
94 static constexpr std::size_t chunk_limit = 0x7fffffff;
95
97
105 std::size_t read(std::basic_string<std::byte> &buf, std::size_t size);
106
107#if defined(PQXX_HAVE_SPAN)
109
114 template<std::size_t extent = std::dynamic_extent>
115 std::span<std::byte> read(std::span<std::byte, extent> buf)
116 {
117 return buf.subspan(0, raw_read(std::data(buf), std::size(buf)));
118 }
119#endif // PQXX_HAVE_SPAN
120
121#if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
123
128 template<binary DATA> std::span<std::byte> read(DATA &buf)
129 {
130 return {std::data(buf), raw_read(std::data(buf), std::size(buf))};
131 }
132#else // PQXX_HAVE_CONCEPTS && PQXX_HAVE_SPAN
134
146 template<typename ALLOC>
147 std::basic_string_view<std::byte> read(std::vector<std::byte, ALLOC> &buf)
148 {
149 return {std::data(buf), raw_read(std::data(buf), std::size(buf))};
150 }
151#endif // PQXX_HAVE_CONCEPTS && PQXX_HAVE_SPAN
152
153#if defined(PQXX_HAVE_CONCEPTS)
155
173 template<binary DATA> void write(DATA const &data)
174 {
175 raw_write(std::data(data), std::size(data));
176 }
177#else
179
197 template<typename DATA> void write(DATA const &data)
198 {
199 raw_write(std::data(data), std::size(data));
200 }
201#endif
202
204
210 void resize(std::int64_t size);
211
213 [[nodiscard]] std::int64_t tell() const;
214
216
217 std::int64_t seek_abs(std::int64_t offset = 0);
219
223 std::int64_t seek_rel(std::int64_t offset = 0);
225
229 std::int64_t seek_end(std::int64_t offset = 0);
230
232
235 static oid from_buf(
236 dbtransaction &tx, std::basic_string_view<std::byte> data, oid id = 0);
237
239
241 static void append_from_buf(
242 dbtransaction &tx, std::basic_string_view<std::byte> data, oid id);
243
245 [[nodiscard]] static oid from_file(dbtransaction &, char const path[]);
246
247#if defined(PQXX_HAVE_PATH) && !defined(_WIN32)
249
252 [[nodiscard]] static oid
253 from_file(dbtransaction &tx, std::filesystem::path const &path)
254 {
255 return from_file(tx, path.c_str());
256 }
257#endif
258
260
263 static oid from_file(dbtransaction &, char const path[], oid);
264
265#if defined(PQXX_HAVE_PATH) && !defined(_WIN32)
267
273 static oid
274 from_file(dbtransaction &tx, std::filesystem::path const &path, oid id)
275 {
276 return from_file(tx, path.c_str(), id);
277 }
278#endif
279
281
284 static void to_buf(
285 dbtransaction &, oid, std::basic_string<std::byte> &,
286 std::size_t max_size);
287
289
295 static std::size_t append_to_buf(
296 dbtransaction &tx, oid id, std::int64_t offset,
297 std::basic_string<std::byte> &buf, std::size_t append_max);
298
300 static void to_file(dbtransaction &, oid, char const path[]);
301
302#if defined(PQXX_HAVE_PATH) && !defined(_WIN32)
304
307 static void
308 to_file(dbtransaction &tx, oid id, std::filesystem::path const &path)
309 {
310 to_file(tx, id, path.c_str());
311 }
312#endif
313
315
326 void close();
327
328private:
329 PQXX_PRIVATE blob(connection &conn, int fd) noexcept :
330 m_conn{&conn}, m_fd{fd}
331 {}
332 static PQXX_PRIVATE blob open_internal(dbtransaction &, oid, int);
333 static PQXX_PRIVATE pqxx::internal::pq::PGconn *
334 raw_conn(pqxx::connection *) noexcept;
335 static PQXX_PRIVATE pqxx::internal::pq::PGconn *
336 raw_conn(pqxx::dbtransaction const &) noexcept;
337 static PQXX_PRIVATE std::string errmsg(connection const *);
338 static PQXX_PRIVATE std::string errmsg(dbtransaction const &tx)
339 {
340 return errmsg(&tx.conn());
341 }
342 PQXX_PRIVATE std::string errmsg() const { return errmsg(m_conn); }
343 PQXX_PRIVATE std::int64_t seek(std::int64_t offset, int whence);
344 std::size_t raw_read(std::byte buf[], std::size_t size);
345 void raw_write(std::byte const buf[], std::size_t size);
346
347 connection *m_conn = nullptr;
348 int m_fd = -1;
349};
350} // namespace pqxx
351#endif
The home of all libpqxx classes, functions, templates, etc.
Definition array.hxx:33
Definition blob.hxx:53
void write(DATA const &data)
Write data large object, at the current position.
Definition blob.hxx:197
blob(blob const &)=delete
blob()=default
You can default-construct a blob, but it won't do anything useful.
std::basic_string_view< std::byte > read(std::vector< std::byte, ALLOC > &buf)
Read up to std::size(buf) bytes from the object.
Definition blob.hxx:147
blob & operator=(blob const &)=delete
Connection to a database.
Definition connection.hxx:253
Abstract transaction base class: bracket transactions on the database.
Definition dbtransaction.hxx:54