libpqxx  7.7.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-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 #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 
37 namespace pqxx
38 {
52 class PQXX_LIBEXPORT blob
53 {
54 public:
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)
108 
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)
122 
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
133 
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)
154 
173  template<binary DATA> void write(DATA const &data)
174  {
175  raw_write(std::data(data), std::size(data));
176  }
177 #else
178 
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)
248 
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)
266 
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)
303 
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 
328 private:
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
Abstract transaction base class: bracket transactions on the database.
Definition: dbtransaction.hxx:53
void write(DATA const &data)
Write data large object, at the current position.
Definition: blob.hxx:197
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:26
Connection to a database.
Definition: connection.hxx:185
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
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:346
Definition: blob.hxx:52
constexpr connection & conn() const noexcept
The connection in which this transaction lives.
Definition: transaction_base.hxx:527