libpqxx 7.7.0
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-2022, 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#include <cstdint>
17
18#if defined(PQXX_HAVE_PATH)
19# include <filesystem>
20#endif
21
22#if defined(PQXX_HAVE_RANGES) && __has_include(<ranges>)
23# include <ranges>
24#endif
25
26#if defined(PQXX_HAVE_SPAN) && __has_include(<span>)
27# include <span>
28#endif
29
30#include "pqxx/dbtransaction.hxx"
31
32
33namespace pqxx
34{
48class PQXX_LIBEXPORT blob
49{
50public:
52
56 [[nodiscard]] static oid create(dbtransaction &, oid = 0);
57
59 static void remove(dbtransaction &, oid);
60
62 [[nodiscard]] static blob open_r(dbtransaction &, oid);
63 // Open blob for writing. Any attempt to read from it will fail.
64 [[nodiscard]] static blob open_w(dbtransaction &, oid);
65 // Open blob for reading and/or writing.
66 [[nodiscard]] static blob open_rw(dbtransaction &, oid);
67
69
72 blob() = default;
73
75 blob(blob &&);
77 blob &operator=(blob &&);
78
79 blob(blob const &) = delete;
80 blob &operator=(blob const &) = delete;
81 ~blob();
82
83 // C++20: constinit.
85
91 static constexpr std::size_t chunk_limit = 0x7fffffff;
92
94
102 std::size_t read(std::basic_string<std::byte> &buf, std::size_t size);
103
104#if defined(PQXX_HAVE_SPAN)
106
111 template<std::size_t extent = std::dynamic_extent>
112 std::span<std::byte> read(std::span<std::byte, extent> buf)
113 {
114 return buf.subspan(0, raw_read(std::data(buf), std::size(buf)));
115 }
116#endif // PQXX_HAVE_SPAN
117
118#if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
120
125 template<binary DATA> std::span<std::byte> read(DATA &buf)
126 {
127 return {std::data(buf), raw_read(std::data(buf), std::size(buf))};
128 }
129#else // PQXX_HAVE_CONCEPTS && PQXX_HAVE_SPAN
131
143 template<typename ALLOC>
144 std::basic_string_view<std::byte> read(std::vector<std::byte, ALLOC> &buf)
145 {
146 return {std::data(buf), raw_read(std::data(buf), std::size(buf))};
147 }
148#endif // PQXX_HAVE_CONCEPTS && PQXX_HAVE_SPAN
149
150#if defined(PQXX_HAVE_CONCEPTS)
152
170 template<binary DATA> void write(DATA const &data)
171 {
172 raw_write(std::data(data), std::size(data));
173 }
174#else
176
194 template<typename DATA> void write(DATA const &data)
195 {
196 raw_write(std::data(data), std::size(data));
197 }
198#endif
199
201
207 void resize(std::int64_t size);
208
210 [[nodiscard]] std::int64_t tell() const;
211
213
214 std::int64_t seek_abs(std::int64_t offset = 0);
216
220 std::int64_t seek_rel(std::int64_t offset = 0);
222
226 std::int64_t seek_end(std::int64_t offset = 0);
227
229
232 static oid from_buf(
233 dbtransaction &tx, std::basic_string_view<std::byte> data, oid id = 0);
234
236
238 static void append_from_buf(
239 dbtransaction &tx, std::basic_string_view<std::byte> data, oid id);
240
242 [[nodiscard]] static oid from_file(dbtransaction &, char const path[]);
243
244#if defined(PQXX_HAVE_PATH) && !defined(_WIN32)
246
249 [[nodiscard]] static oid
250 from_file(dbtransaction &tx, std::filesystem::path const &path)
251 {
252 return from_file(tx, path.c_str());
253 }
254#endif
255
257
260 static oid from_file(dbtransaction &, char const path[], oid);
261
262#if defined(PQXX_HAVE_PATH) && !defined(_WIN32)
264
270 static oid
271 from_file(dbtransaction &tx, std::filesystem::path const &path, oid id)
272 {
273 return from_file(tx, path.c_str(), id);
274 }
275#endif
276
278
281 static void to_buf(
282 dbtransaction &, oid, std::basic_string<std::byte> &,
283 std::size_t max_size);
284
286
292 static std::size_t append_to_buf(
293 dbtransaction &tx, oid id, std::int64_t offset,
294 std::basic_string<std::byte> &buf, std::size_t append_max);
295
297 static void to_file(dbtransaction &, oid, char const path[]);
298
299#if defined(PQXX_HAVE_PATH) && !defined(_WIN32)
301
304 static void
305 to_file(dbtransaction &tx, oid id, std::filesystem::path const &path)
306 {
307 to_file(tx, id, path.c_str());
308 }
309#endif
310
312
323 void close();
324
325private:
326 PQXX_PRIVATE blob(connection &conn, int fd) noexcept :
327 m_conn{&conn}, m_fd{fd}
328 {}
329 static PQXX_PRIVATE blob open_internal(dbtransaction &, oid, int);
330 static PQXX_PRIVATE pqxx::internal::pq::PGconn *
331 raw_conn(pqxx::connection *) noexcept;
332 static PQXX_PRIVATE pqxx::internal::pq::PGconn *
333 raw_conn(pqxx::dbtransaction const &) noexcept;
334 static PQXX_PRIVATE std::string errmsg(connection const *);
335 static PQXX_PRIVATE std::string errmsg(dbtransaction const &tx)
336 {
337 return errmsg(&tx.conn());
338 }
339 PQXX_PRIVATE std::string errmsg() const { return errmsg(m_conn); }
340 PQXX_PRIVATE std::int64_t seek(std::int64_t offset, int whence);
341 std::size_t raw_read(std::byte buf[], std::size_t size);
342 void raw_write(std::byte const buf[], std::size_t size);
343
344 connection *m_conn = nullptr;
345 int m_fd = -1;
346};
347} // namespace pqxx
348#endif
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:23
std::vector< std::string_view > to_buf(char *here, char const *end, TYPE... value)
Convert multiple values to strings inside a single buffer.
Definition: strconv.hxx:343
Definition: blob.hxx:49
void write(DATA const &data)
Write data large object, at the current position.
Definition: blob.hxx:194
blob(blob const &)=delete
blob()=default
You can default-construct a blob, but it won't do anything useful.
static oid from_file(dbtransaction &tx, std::filesystem::path const &path)
Read client-side file and store it server-side as a binary large object.
Definition: blob.hxx:250
static void to_file(dbtransaction &tx, oid id, std::filesystem::path const &path)
Write a binary large object's contents to a client-side file.
Definition: blob.hxx:305
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:144
static oid from_file(dbtransaction &tx, std::filesystem::path const &path, oid id)
Read client-side file and store it server-side as a binary large object.
Definition: blob.hxx:271
blob & operator=(blob const &)=delete
Connection to a database.
Definition: connection.hxx:181
Abstract transaction base class: bracket transactions on the database.
Definition: dbtransaction.hxx:50