blob.hxx

/* Binary Large Objects interface.
 *
 * Read or write large objects, stored in their own storage on the server.
 *
 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/largeobject instead.
 *
 * Copyright (c) 2000-2023, Jeroen T. Vermeulen.
 *
 * See COPYING for copyright license.  If you did not receive a file called
 * COPYING with this source code, please notify the distributor of this
 * mistake, or contact the author.
 */
#ifndef PQXX_H_BLOB
#define PQXX_H_BLOB
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include <cstdint>
 
#if defined(PQXX_HAVE_PATH)
#  include <filesystem>
#endif
 
#if defined(PQXX_HAVE_RANGES) && __has_include(<ranges>)
#  include <ranges>
#endif
 
#if defined(PQXX_HAVE_SPAN) && __has_include(<span>)
#  include <span>
#endif
 
#include "pqxx/dbtransaction.hxx"
 
 
namespace pqxx
{
class PQXX_LIBEXPORT blob
{
public:
 
  [[nodiscard]] static oid create(dbtransaction &, oid = 0);
 
  static void remove(dbtransaction &, oid);
 
  [[nodiscard]] static blob open_r(dbtransaction &, oid);
  // Open blob for writing.  Any attempt to read from it will fail.
  [[nodiscard]] static blob open_w(dbtransaction &, oid);
  // Open blob for reading and/or writing.
  [[nodiscard]] static blob open_rw(dbtransaction &, oid);
 
 
  blob() = default;
 
  blob(blob &&);
  blob &operator=(blob &&);
 
  blob(blob const &) = delete;
  blob &operator=(blob const &) = delete;
  ~blob();
 
 
  static constexpr std::size_t chunk_limit = 0x7fffffff;
 
 
  std::size_t read(std::basic_string<std::byte> &buf, std::size_t size);
 
#if defined(PQXX_HAVE_SPAN)
 
  template<std::size_t extent = std::dynamic_extent>
  std::span<std::byte> read(std::span<std::byte, extent> buf)
  {
    return buf.subspan(0, raw_read(std::data(buf), std::size(buf)));
  }
#endif // PQXX_HAVE_SPAN
 
#if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_SPAN)
 
  template<binary DATA> std::span<std::byte> read(DATA &buf)
  {
    return {std::data(buf), raw_read(std::data(buf), std::size(buf))};
  }
#else  // PQXX_HAVE_CONCEPTS && PQXX_HAVE_SPAN
 
  template<typename ALLOC>
  std::basic_string_view<std::byte> read(std::vector<std::byte, ALLOC> &buf)
  {
    return {std::data(buf), raw_read(std::data(buf), std::size(buf))};
  }
#endif // PQXX_HAVE_CONCEPTS && PQXX_HAVE_SPAN
 
#if defined(PQXX_HAVE_CONCEPTS)
 
  template<binary DATA> void write(DATA const &data)
  {
    raw_write(std::data(data), std::size(data));
  }
#else
 
  template<typename DATA> void write(DATA const &data)
  {
    raw_write(std::data(data), std::size(data));
  }
#endif
 
 
  void resize(std::int64_t size);
 
  [[nodiscard]] std::int64_t tell() const;
 
 
  std::int64_t seek_abs(std::int64_t offset = 0);
 
  std::int64_t seek_rel(std::int64_t offset = 0);
 
  std::int64_t seek_end(std::int64_t offset = 0);
 
 
  static oid from_buf(
    dbtransaction &tx, std::basic_string_view<std::byte> data, oid id = 0);
 
 
  static void append_from_buf(
    dbtransaction &tx, std::basic_string_view<std::byte> data, oid id);
 
  [[nodiscard]] static oid from_file(dbtransaction &, char const path[]);
 
#if defined(PQXX_HAVE_PATH) && !defined(_WIN32)
 
  [[nodiscard]] static oid
  from_file(dbtransaction &tx, std::filesystem::path const &path)
  {
    return from_file(tx, path.c_str());
  }
#endif
 
 
  static oid from_file(dbtransaction &, char const path[], oid);
 
#if defined(PQXX_HAVE_PATH) && !defined(_WIN32)
 
  static oid
  from_file(dbtransaction &tx, std::filesystem::path const &path, oid id)
  {
    return from_file(tx, path.c_str(), id);
  }
#endif
 
 
  static void to_buf(
    dbtransaction &, oid, std::basic_string<std::byte> &,
    std::size_t max_size);
 
 
  static std::size_t append_to_buf(
    dbtransaction &tx, oid id, std::int64_t offset,
    std::basic_string<std::byte> &buf, std::size_t append_max);
 
  static void to_file(dbtransaction &, oid, char const path[]);
 
#if defined(PQXX_HAVE_PATH) && !defined(_WIN32)
 
  static void
  to_file(dbtransaction &tx, oid id, std::filesystem::path const &path)
  {
    to_file(tx, id, path.c_str());
  }
#endif
 
 
  void close();
 
private:
  PQXX_PRIVATE blob(connection &conn, int fd) noexcept :
          m_conn{&conn}, m_fd{fd}
  {}
  static PQXX_PRIVATE blob open_internal(dbtransaction &, oid, int);
  static PQXX_PRIVATE pqxx::internal::pq::PGconn *
  raw_conn(pqxx::connection *) noexcept;
  static PQXX_PRIVATE pqxx::internal::pq::PGconn *
  raw_conn(pqxx::dbtransaction const &) noexcept;
  static PQXX_PRIVATE std::string errmsg(connection const *);
  static PQXX_PRIVATE std::string errmsg(dbtransaction const &tx)
  {
    return errmsg(&tx.conn());
  }
  PQXX_PRIVATE std::string errmsg() const { return errmsg(m_conn); }
  PQXX_PRIVATE std::int64_t seek(std::int64_t offset, int whence);
  std::size_t raw_read(std::byte buf[], std::size_t size);
  void raw_write(std::byte const buf[], std::size_t size);
 
  connection *m_conn = nullptr;
  int m_fd = -1;
};
} // namespace pqxx
#endif