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

Inheritance diagram for pqxx::largeobjectaccess:

Collaboration 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").

using	seekdir = std::ios::seekdir
	Seek direction: `beg`, `cur`, `end`.

using	size_type = large_object_size_type

Public Member Functions
	largeobjectaccess (dbtransaction &t, openmode mode=default_mode)
	Create new large object and open it.

	largeobjectaccess (dbtransaction &t, oid o, openmode mode=default_mode)
	Open large object with given oid.

	largeobjectaccess (dbtransaction &t, largeobject o, openmode mode=default_mode)
	Open given large object.

	largeobjectaccess (dbtransaction &t, std::string_view file, openmode mode=default_mode)
	Import large object from a local file and open it.

void	to_file (std::string_view file) const
	Export large object's contents to a local file.

oid	id () const noexcept
	Object identifier.

void	to_file (dbtransaction &t, std::string_view file) const
	Export large object's contents to a local file.

High-level access to object contents.
void	write (char const buf[], std::size_t len)
	Write data to large object.

void	write (std::string_view buf)
	Write string to large object.

size_type	read (char buf[], std::size_t len)
	Read data from large object.

size_type	seek (size_type dest, seekdir dir)
	Seek in large object's data stream.

size_type	tell () const
	Report current position in large object's data stream.

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.

off_type	cwrite (char const buf[], std::size_t len) noexcept
	Write to large object's data stream.

off_type	cread (char buf[], std::size_t len) noexcept
	Read from large object's data stream.

pos_type	ctell () const noexcept
	Report current position in large object's data stream.

Static Public Attributes
static constexpr auto	default_mode
	Default open mode: in, out, binary.

Error/warning output
void	process_notice (zview) noexcept
	Issue message to transaction's notice processor.

	largeobjectaccess (largeobjectaccess const &)=delete

largeobjectaccess	operator= (largeobjectaccess const &)=delete

void	remove (dbtransaction &t) const
	Delete large object from database.

bool	operator== (largeobject const &other) const
	Compare object identities.

bool	operator!= (largeobject const &other) const
	Compare object identities.

bool	operator< (largeobject const &other) const
	Compare object identities.

bool	operator<= (largeobject const &other) const
	Compare object identities.

bool	operator> (largeobject const &other) const
	Compare object identities.

bool	operator>= (largeobject const &other) const
	Compare object identities.

Detailed Description

Accessor for large object's contents.

Deprecated:: Use the blob class instead.

Member Typedef Documentation

◆ 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.

Constructor & Destructor Documentation

◆ largeobjectaccess() [1/4]

pqxx::largeobjectaccess::largeobjectaccess	(	dbtransaction &	t,
		openmode	mode = `default_mode`
	)

explicit

Create new large object and open it.

Parameters

t	Backend transaction in which the object is to be created.
mode	Access mode, defaults to ios_base::in \| ios_base::out \| ios_base::binary.

◆ largeobjectaccess() [2/4]

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

t	Transaction in which the object is to be accessed.
o	Object identifier for the given object.
mode	Access mode, defaults to ios_base::in \| ios_base::out \| ios_base::binary.

◆ largeobjectaccess() [3/4]

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

t	Transaction in which the object is to be accessed.
o	Identity for the large object to be accessed.
mode	Access mode, defaults to ios_base::in \| ios_base::out \| ios_base::binary.

◆ largeobjectaccess() [4/4]

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

t	Backend transaction in which the large object is to be created.
file	A filename on the client program's filesystem.
mode	Access mode, defaults to ios_base::in \| ios_base::out.

Member Function Documentation

◆ cread()

pqxx::largeobjectaccess::pos_type 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

buf	Area where incoming bytes should be stored.
len	Number of bytes to read.

Returns: Number of bytes actually read, or -1 if an error occurred..

◆ cseek()

pqxx::largeobjectaccess::pos_type 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

dest	Offset to go to.
dir	Origin 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.

◆ ctell()

pqxx::largeobjectaccess::pos_type 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.

◆ cwrite()

pqxx::largeobjectaccess::pos_type 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

buf	Data to write.
len	Number of bytes to write.

Returns: Number of bytes actually written, or -1 if an error occurred.

◆ id()

oid pqxx::largeobject::id ( ) const

inlinenoexcept

Object identifier.

The number returned by this function uniquely identifies the large object in the context of the database we're connected to.

◆ operator!=()

bool pqxx::largeobject::operator!= ( largeobject const & other ) const

inline

Compare object identities.

Warning: Only valid between large objects in the same database.

◆ operator<()

bool pqxx::largeobject::operator< ( largeobject const & other ) const

inline

Compare object identities.

Warning: Only valid between large objects in the same database.

◆ operator<=()

bool pqxx::largeobject::operator<= ( largeobject const & other ) const

inline

Compare object identities.

Warning: Only valid between large objects in the same database.

◆ operator==()

bool pqxx::largeobject::operator== ( largeobject const & other ) const

inline

Compare object identities.

Warning: Only valid between large objects in the same database.

◆ operator>()

bool pqxx::largeobject::operator> ( largeobject const & other ) const

inline

Compare object identities.

Warning: Only valid between large objects in the same database.

◆ operator>=()

bool pqxx::largeobject::operator>= ( largeobject const & other ) const

inline

Compare object identities.

Warning: Only valid between large objects in the same database.

◆ read()

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

Read data from large object.

Throws an exception if an error occurs while reading.

Parameters

buf	Location to store the read data in.
len	Number 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.

◆ remove()

void pqxx::largeobject::remove ( dbtransaction & t ) const

Delete large object from database.

Unlike its low-level equivalent cunlink, this will throw an exception if deletion fails.

Parameters

t	Transaction in which the object is to be deleted

◆ seek()

pqxx::largeobjectaccess::size_type 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

◆ tell()

pqxx::largeobjectaccess::size_type 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.

◆ to_file() [1/2]

void pqxx::largeobject::to_file	(	dbtransaction &	t,
		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

t	Transaction in which the object is to be accessed
file	A filename on the client's filesystem

◆ to_file() [2/2]

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

inline

Export large object's contents to a local file.

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

Parameters

file	A filename on the client's filesystem.

◆ write() [1/2]

void 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

buf	Data to write.
len	Number of bytes from Buf to write.

◆ write() [2/2]

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

inline

Write string to large object.

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

Parameters

buf	Data to write; no terminating zero is written.

Member Data Documentation

◆ default_mode

constexpr auto pqxx::largeobjectaccess::default_mode

staticconstexpr

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:

/build/reproducible-path/libpqxx-7.10.0/include/pqxx/largeobject.hxx
/build/reproducible-path/libpqxx-7.10.0/src/largeobject.cxx

Public Types

Public Member Functions

Static Public Attributes

Error/warning output

Detailed Description

Member Typedef Documentation

◆ openmode

Constructor & Destructor Documentation

◆ largeobjectaccess() [1/4]

◆ largeobjectaccess() [2/4]

◆ largeobjectaccess() [3/4]

◆ largeobjectaccess() [4/4]

Member Function Documentation

◆ cread()

◆ cseek()

◆ ctell()

◆ cwrite()

◆ id()

◆ operator!=()

◆ operator<()

◆ operator<=()

◆ operator==()

◆ operator>()

◆ operator>=()

◆ read()

◆ remove()

◆ seek()

◆ tell()

◆ to_file() [1/2]

◆ to_file() [2/2]

◆ write() [1/2]

◆ write() [2/2]

Member Data Documentation

◆ default_mode