libpqxx  7.6.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 #include "pqxx/compiler-public.hxx"
17 #include "pqxx/internal/compiler-internal-pre.hxx"
18 
19 #include <cstdint>
20 
21 #if __has_include(<filesystem>)
22 # include <filesystem>
23 #endif
24 
25 #if defined(PQXX_HAVE_RANGES) && __has_include(<ranges>)
26 # include <ranges>
27 #endif
28 
29 #if defined(PQXX_HAVE_SPAN) && __has_include(<span>)
30 # include <span>
31 #endif
32 
33 #include "pqxx/dbtransaction.hxx"
34 
35 
36 namespace pqxx
37 {
51 class PQXX_LIBEXPORT blob
52 {
53 public:
55 
59  [[nodiscard]] static oid create(dbtransaction &, oid = 0);
60 
62  static void remove(dbtransaction &, oid);
63 
65  [[nodiscard]] static blob open_r(dbtransaction &, oid);
66  // Open blob for writing. Any attempt to read from it will fail.
67  [[nodiscard]] static blob open_w(dbtransaction &, oid);
68  // Open blob for reading and/or writing.
69  [[nodiscard]] static blob open_rw(dbtransaction &, oid);
70 
72 
74  blob() = default;
75 
77  blob(blob &&);
79  blob &operator=(blob &&);
80 
81  blob(blob const &) = delete;
82  blob &operator=(blob const &) = delete;
83  ~blob();
84 
86 
92  static constexpr std::size_t chunk_limit = 0x7fffffff;
93 
95 
103  std::size_t read(std::basic_string<std::byte> &buf, std::size_t size);
104 
105 #if defined(PQXX_HAVE_SPAN)
106 
112  template<std::size_t extent = std::dynamic_extent>
113  std::span<std::byte> read(std::span<std::byte, extent> buf)
114  {
115  return buf.subspan(0, raw_read(std::data(buf), std::size(buf)));
116  }
117 #endif // PQXX_HAVE_SPAN
118 
119 #if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
120 
126  template<binary DATA> std::span<std::byte> read(DATA &buf)
127  {
128  return std::span<std::byte>{
129  std::data(buf), raw_read(std::data(buf), std::size(buf))};
130  }
131 #else // PQXX_HAVE_CONCEPTS && PQXX_HAVE_SPAN
132 
145  template<typename ALLOC>
146  std::basic_string_view<std::byte> read(std::vector<std::byte, ALLOC> &buf)
147  {
148  return std::basic_string_view<std::byte>{
149  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  std::int64_t seek_abs(std::int64_t offset = 0);
218 
219  std::int64_t seek_rel(std::int64_t offset = 0);
221 
222  std::int64_t seek_end(std::int64_t offset = 0);
223 
225 
228  static oid from_buf(
229  dbtransaction &tx, std::basic_string_view<std::byte> data, oid id = 0);
230 
232 
234  static void append_from_buf(
235  dbtransaction &tx, std::basic_string_view<std::byte> data, oid id);
236 
238  static oid from_file(dbtransaction &, char const path[]);
239 
240 #if __has_include(<filesystem>)
241  static oid from_file(dbtransaction &tx, std::filesystem::path const &path)
243  {
244  return from_file(tx, path.c_str());
245  }
246 #endif
247 
249 
252  static oid from_file(dbtransaction &, char const path[], oid);
253 
254 #if __has_include(<filesystem>)
255 
259  static oid
260  from_file(dbtransaction &tx, std::filesystem::path const &path, oid id)
261  {
262  return from_file(tx, path.c_str(), id);
263  }
264 #endif
265 
267 
270  static void to_buf(
271  dbtransaction &, oid, std::basic_string<std::byte> &,
272  std::size_t max_size);
273 
275 
281  static std::size_t append_to_buf(
282  dbtransaction &tx, oid id, std::int64_t offset,
283  std::basic_string<std::byte> &buf, std::size_t append_max);
284 
286  static void to_file(dbtransaction &, oid, char const path[]);
287 
288 #if __has_include(<filesystem>)
289  static void
291  to_file(dbtransaction &tx, oid id, std::filesystem::path const &path)
292  {
293  to_file(tx, id, path.c_str());
294  }
295 #endif
296 
298 
309  void close();
310 
311 private:
312  PQXX_PRIVATE blob(connection &conn, int fd) noexcept :
313  m_conn{&conn}, m_fd{fd}
314  {}
315  static PQXX_PRIVATE blob open_internal(dbtransaction &, oid, int);
316  static PQXX_PRIVATE pqxx::internal::pq::PGconn *
317  raw_conn(pqxx::connection *) noexcept;
318  static PQXX_PRIVATE pqxx::internal::pq::PGconn *
319  raw_conn(pqxx::dbtransaction const &) noexcept;
320  static PQXX_PRIVATE std::string errmsg(connection const *);
321  static PQXX_PRIVATE std::string errmsg(dbtransaction const &tx)
322  {
323  return errmsg(&tx.conn());
324  }
325  PQXX_PRIVATE std::string errmsg() const { return errmsg(m_conn); }
326  PQXX_PRIVATE std::int64_t seek(std::int64_t offset, int whence);
327  std::size_t raw_read(std::byte buf[], std::size_t size);
328  void raw_write(std::byte const buf[], std::size_t size);
329 
330  connection *m_conn = nullptr;
331  int m_fd = -1;
332 };
333 } // namespace pqxx
334 #endif
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:25
void write(DATA const &data)
Write data to large object, at the current position.
Definition: blob.hxx:197
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:146
Connection to a database.
Definition: connection.hxx:180
connection & conn() const
The connection in which this transaction lives.
Definition: transaction_base.hxx:524
Abstract transaction base class: bracket transactions on the database.
Definition: dbtransaction.hxx:52
Definition: blob.hxx:51
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:336