libpqxx  7.9.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-2024, 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 // C++20: Assume support.
27 #if __has_include(<ranges>)
28 # include <ranges>
29 #endif
30 
31 // C++20: Assume support.
32 #if __has_include(<span>)
33 # include <span>
34 #endif
35 
36 #include "pqxx/dbtransaction.hxx"
37 
38 
39 namespace pqxx
40 {
54 class PQXX_LIBEXPORT blob
55 {
56 public:
58 
62  [[nodiscard]] static oid create(dbtransaction &, oid = 0);
63 
65  static void remove(dbtransaction &, oid);
66 
68  [[nodiscard]] static blob open_r(dbtransaction &, oid);
69  // Open blob for writing. Any attempt to read from it will fail.
70  [[nodiscard]] static blob open_w(dbtransaction &, oid);
71  // Open blob for reading and/or writing.
72  [[nodiscard]] static blob open_rw(dbtransaction &, oid);
73 
75 
78  blob() = default;
79 
81  blob(blob &&);
83  blob &operator=(blob &&);
84 
85  blob(blob const &) = delete;
86  blob &operator=(blob const &) = delete;
87  ~blob();
88 
90 
96  static constexpr std::size_t chunk_limit = 0x7fffffff;
97 
99 
107  std::size_t read(bytes &buf, std::size_t size);
108 
109 #if defined(PQXX_HAVE_SPAN)
111 
116  template<std::size_t extent = std::dynamic_extent>
117  std::span<std::byte> read(std::span<std::byte, extent> buf)
118  {
119  return buf.subspan(0, raw_read(std::data(buf), std::size(buf)));
120  }
121 #endif // PQXX_HAVE_SPAN
122 
123 #if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
125 
130  template<binary DATA> std::span<std::byte> read(DATA &buf)
131  {
132  return {std::data(buf), raw_read(std::data(buf), std::size(buf))};
133  }
134 #else // PQXX_HAVE_CONCEPTS && PQXX_HAVE_SPAN
136 
148  template<typename ALLOC> bytes_view read(std::vector<std::byte, ALLOC> &buf)
149  {
150  return {std::data(buf), raw_read(std::data(buf), std::size(buf))};
151  }
152 #endif // PQXX_HAVE_CONCEPTS && PQXX_HAVE_SPAN
153 
154 #if defined(PQXX_HAVE_CONCEPTS)
156 
174  template<binary DATA> void write(DATA const &data)
175  {
176  raw_write(std::data(data), std::size(data));
177  }
178 #else
180 
198  template<typename DATA> void write(DATA const &data)
199  {
200  raw_write(std::data(data), std::size(data));
201  }
202 #endif
203 
205 
211  void resize(std::int64_t size);
212 
214  [[nodiscard]] std::int64_t tell() const;
215 
217 
218  std::int64_t seek_abs(std::int64_t offset = 0);
220 
224  std::int64_t seek_rel(std::int64_t offset = 0);
226 
230  std::int64_t seek_end(std::int64_t offset = 0);
231 
233 
236  static oid from_buf(dbtransaction &tx, bytes_view data, oid id = 0);
237 
239 
241  static void append_from_buf(dbtransaction &tx, bytes_view data, oid id);
242 
244  [[nodiscard]] static oid from_file(dbtransaction &, char const path[]);
245 
246 #if defined(PQXX_HAVE_PATH) && !defined(_WIN32)
248 
251  [[nodiscard]] static oid
252  from_file(dbtransaction &tx, std::filesystem::path const &path)
253  {
254  return from_file(tx, path.c_str());
255  }
256 #endif
257 
259 
262  static oid from_file(dbtransaction &, char const path[], oid);
263 
264 #if defined(PQXX_HAVE_PATH) && !defined(_WIN32)
266 
272  static oid
273  from_file(dbtransaction &tx, std::filesystem::path const &path, oid id)
274  {
275  return from_file(tx, path.c_str(), id);
276  }
277 #endif
278 
280 
283  static void to_buf(dbtransaction &, oid, bytes &, std::size_t max_size);
284 
286 
292  static std::size_t append_to_buf(
293  dbtransaction &tx, oid id, std::int64_t offset, bytes &buf,
294  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 
325 private:
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:33
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:492
std::conditional< has_generic_bytes_char_traits, std::basic_string< std::byte >, std::basic_string< std::byte, byte_char_traits > >::type bytes
Type alias for a container containing bytes.
Definition: util.hxx:373
std::conditional< has_generic_bytes_char_traits, std::basic_string_view< std::byte >, std::basic_string_view< std::byte, byte_char_traits > >::type bytes_view
Type alias for a view of bytes.
Definition: util.hxx:383
Definition: blob.hxx:55
void write(DATA const &data)
Write data large object, at the current position.
Definition: blob.hxx:198
blob(blob const &)=delete
blob()=default
You can default-construct a blob, but it won't do anything useful.
blob & operator=(blob const &)=delete
bytes_view read(std::vector< std::byte, ALLOC > &buf)
Read up to std::size(buf) bytes from the object.
Definition: blob.hxx:148
Connection to a database.
Definition: connection.hxx:233
Abstract transaction base class: bracket transactions on the database.
Definition: dbtransaction.hxx:54