Loading...
Searching...
No Matches
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-2024, 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
// C++20: Assume support.
#if __has_include(<ranges>)
# include <ranges>
#endif
// C++20: Assume support.
#if __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(bytes &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> bytes_view 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, bytes_view data, oid id = 0);
static void append_from_buf(dbtransaction &tx, bytes_view 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, bytes &, std::size_t max_size);
static std::size_t append_to_buf(
dbtransaction &tx, oid id, std::int64_t offset, bytes &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 &cx, int fd) noexcept : m_conn{&cx}, 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
pqxx::blob
Definition blob.hxx:55
pqxx::blob::write
void write(DATA const &data)
Write data large object, at the current position.
Definition blob.hxx:198
pqxx::blob::blob
blob()=default
You can default-construct a blob, but it won't do anything useful.
pqxx::blob::read
bytes_view read(std::vector< std::byte, ALLOC > &buf)
Read up to std::size(buf) bytes from the object.
Definition blob.hxx:148
pqxx::connection
Connection to a database.
Definition connection.hxx:279
pqxx::dbtransaction
Abstract transaction base class: bracket transactions on the database.
Definition dbtransaction.hxx:54
pqxx
The home of all libpqxx classes, functions, templates, etc.
Definition array.cxx:27
pqxx::bytes
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:375
pqxx::oid
unsigned int oid
PostgreSQL database row identifier.
Definition libpq-forward.hxx:33
pqxx::bytes_view
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:385