libpqxx  7.7.2
pqxx::largeobjectaccess Class Reference

Accessor for large object's contents. More...

#include <largeobject.hxx>

Inheritance diagram for pqxx::largeobjectaccess:

Public Types

using off_type = size_type
 
using pos_type = size_type
 
using openmode = std::ios::openmode
 Open mode: in, out (can be combined using "bitwise or"). More...
 
using seekdir = std::ios::seekdir
 Seek direction: beg, cur, end. More...
 
using size_type = large_object_size_type
 

Public Member Functions

 largeobjectaccess (dbtransaction &t, openmode mode=default_mode)
 Create new large object and open it. More...
 
 largeobjectaccess (dbtransaction &t, oid o, openmode mode=default_mode)
 Open large object with given oid. More...
 
 largeobjectaccess (dbtransaction &t, largeobject o, openmode mode=default_mode)
 Open given large object. More...
 
 largeobjectaccess (dbtransaction &t, std::string_view file, openmode mode=default_mode)
 Import large object from a local file and open it. More...
 
 ~largeobjectaccess () noexcept
 
void to_file (std::string_view file) const
 Export large object's contents to a local file. More...
 
 largeobjectaccess ()=delete
 
 largeobjectaccess (largeobjectaccess const &)=delete
 
largeobjectaccess operator= (largeobjectaccess const &)=delete
 
High-level access to object contents.
void write (char const buf[], std::size_t len)
 Write data to large object. More...
 
void write (std::string_view buf)
 Write string to large object. More...
 
size_type read (char buf[], std::size_t len)
 Read data from large object. More...
 
size_type seek (size_type dest, seekdir dir)
 Seek in large object's data stream. More...
 
size_type tell () const
 Report current position in large object's data stream. More...
 
Low-level access to object contents.

These functions provide a more "C-like" access interface, returning special values instead of throwing exceptions on error. These functions are generally best avoided in favour of the high-level access functions, which behave more like C++ functions should.

Due to libpq's underlying API, some operations are limited to "int" sizes, typically 2 GB, even though a large object can grow much larger.

pos_type cseek (off_type dest, seekdir dir) noexcept
 Seek in large object's data stream. More...
 
off_type cwrite (char const buf[], std::size_t len) noexcept
 Write to large object's data stream. More...
 
off_type cread (char buf[], std::size_t len) noexcept
 Read from large object's data stream. More...
 
pos_type ctell () const noexcept
 Report current position in large object's data stream. More...
 
Error/warning output
void process_notice (zview) noexcept
 Issue message to transaction's notice processor. More...
 

Static Public Attributes

static constexpr auto default_mode
 Default open mode: in, out, binary. More...
 

Detailed Description

Accessor for large object's contents.

Deprecated:
Use the blob class instead.

Member Typedef Documentation

◆ off_type

◆ openmode

using pqxx::largeobjectaccess::openmode = std::ios::openmode

Open mode: in, out (can be combined using "bitwise or").

According to the C++ standard, these should be in std::ios_base. We take them from derived class std::ios instead, which is easier on the eyes.

Historical note: taking it from std::ios was originally a workaround for a problem with gcc 2.95.

◆ pos_type

◆ seekdir

using pqxx::largeobjectaccess::seekdir = std::ios::seekdir

Seek direction: beg, cur, end.

◆ size_type

Constructor & Destructor Documentation

◆ largeobjectaccess() [1/6]

PQXX_COLD pqxx::largeobjectaccess::largeobjectaccess ( dbtransaction t,
openmode  mode = default_mode 
)
explicit

Create new large object and open it.

Parameters
tBackend transaction in which the object is to be created.
modeAccess mode, defaults to ios_base::in | ios_base::out | ios_base::binary.

◆ largeobjectaccess() [2/6]

PQXX_COLD pqxx::largeobjectaccess::largeobjectaccess ( dbtransaction t,
oid  o,
openmode  mode = default_mode 
)

Open large object with given oid.

Convert combination of a transaction and object identifier into a large object identity. Does not affect the database.

Parameters
tTransaction in which the object is to be accessed.
oObject identifier for the given object.
modeAccess mode, defaults to ios_base::in | ios_base::out | ios_base::binary.

◆ largeobjectaccess() [3/6]

PQXX_COLD pqxx::largeobjectaccess::largeobjectaccess ( dbtransaction t,
largeobject  o,
openmode  mode = default_mode 
)

Open given large object.

Open a large object with the given identity for reading and/or writing.

Parameters
tTransaction in which the object is to be accessed.
oIdentity for the large object to be accessed.
modeAccess mode, defaults to ios_base::in | ios_base::out | ios_base::binary.

◆ largeobjectaccess() [4/6]

PQXX_COLD pqxx::largeobjectaccess::largeobjectaccess ( dbtransaction t,
std::string_view  file,
openmode  mode = default_mode 
)

Import large object from a local file and open it.

Creates a large object containing the data found in the given file.

Parameters
tBackend transaction in which the large object is to be created.
fileA filename on the client program's filesystem.
modeAccess mode, defaults to ios_base::in | ios_base::out.

◆ ~largeobjectaccess()

pqxx::largeobjectaccess::~largeobjectaccess ( )
noexcept

◆ largeobjectaccess() [5/6]

pqxx::largeobjectaccess::largeobjectaccess ( )
delete

◆ largeobjectaccess() [6/6]

pqxx::largeobjectaccess::largeobjectaccess ( largeobjectaccess const &  )
delete

Member Function Documentation

◆ cread()

pqxx::largeobjectaccess::pos_type PQXX_COLD pqxx::largeobjectaccess::cread ( char  buf[],
std::size_t  len 
)
noexcept

Read from large object's data stream.

Does not throw exception in case of error; inspect return value and errno instead.

Parameters
bufArea where incoming bytes should be stored.
lenNumber of bytes to read.
Returns
Number of bytes actually read, or -1 if an error occurred..

Referenced by read().

◆ cseek()

pqxx::largeobjectaccess::pos_type PQXX_COLD pqxx::largeobjectaccess::cseek ( off_type  dest,
seekdir  dir 
)
noexcept

Seek in large object's data stream.

Does not throw exception in case of error; inspect return value and errno instead.

Parameters
destOffset to go to.
dirOrigin to which dest is relative: ios_base::beg (from beginning of the object), ios_base::cur (from current access position), or ios_base;:end (from end of object).
Returns
New position in large object, or -1 if an error occurred.

Referenced by seek().

◆ ctell()

pqxx::largeobjectaccess::pos_type PQXX_COLD pqxx::largeobjectaccess::ctell ( ) const
noexcept

Report current position in large object's data stream.

Does not throw exception in case of error; inspect return value and errno instead.

Returns
Current position in large object, of -1 if an error occurred.

Referenced by tell().

◆ cwrite()

pqxx::largeobjectaccess::pos_type PQXX_COLD pqxx::largeobjectaccess::cwrite ( char const  buf[],
std::size_t  len 
)
noexcept

Write to large object's data stream.

Does not throw exception in case of error; inspect return value and errno instead.

Parameters
bufData to write.
lenNumber of bytes to write.
Returns
Number of bytes actually written, or -1 if an error occurred.

Referenced by write().

◆ operator=()

largeobjectaccess pqxx::largeobjectaccess::operator= ( largeobjectaccess const &  )
delete

◆ process_notice()

void PQXX_COLD pqxx::largeobjectaccess::process_notice ( zview  s)
noexcept

Issue message to transaction's notice processor.

References pqxx::transaction_base::process_notice().

◆ read()

pqxx::largeobjectaccess::size_type PQXX_COLD pqxx::largeobjectaccess::read ( char  buf[],
std::size_t  len 
)

Read data from large object.

Throws an exception if an error occurs while reading.

Parameters
bufLocation to store the read data in.
lenNumber of bytes to try and read.
Returns
Number of bytes read, which may be less than the number requested if the end of the large object is reached.

References cread(), and pqxx::oid_none.

◆ seek()

pqxx::largeobjectaccess::size_type PQXX_COLD pqxx::largeobjectaccess::seek ( size_type  dest,
seekdir  dir 
)

Seek in large object's data stream.

Throws an exception if an error occurs.

Returns
The new position in the large object

References cseek(), and pqxx::oid_none.

◆ tell()

pqxx::largeobjectaccess::size_type PQXX_COLD pqxx::largeobjectaccess::tell ( ) const

Report current position in large object's data stream.

Throws an exception if an error occurs.

Returns
The current position in the large object.

References pqxx::transaction_base::conn(), ctell(), and pqxx::largeobject::reason().

◆ to_file()

void pqxx::largeobjectaccess::to_file ( std::string_view  file) const

Export large object's contents to a local file.

Writes the data stored in the large object to the given file.

Parameters
fileA filename on the client's filesystem.

References pqxx::largeobject::to_file().

◆ write() [1/2]

void PQXX_COLD pqxx::largeobjectaccess::write ( char const  buf[],
std::size_t  len 
)

Write data to large object.

Warning
The size of a write is currently limited to 2GB.
Parameters
bufData to write.
lenNumber of bytes from Buf to write.

References pqxx::internal::cmp_less(), cwrite(), and pqxx::oid_none.

◆ write() [2/2]

void pqxx::largeobjectaccess::write ( std::string_view  buf)

Write string to large object.

If not all bytes could be written, an exception is thrown.

Parameters
bufData to write; no terminating zero is written.

References pqxx::largeobject::raw_connection(), pqxx::largeobject::remove(), and write().

Referenced by write().

Member Data Documentation

◆ default_mode

constexpr auto pqxx::largeobjectaccess::default_mode
static
Initial value:
{
std::ios::in | std::ios::out | std::ios::binary}

Default open mode: in, out, binary.


The documentation for this class was generated from the following files: