pqxx::largeobjectaccess Class Reference

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

`#include <largeobject.hxx>`

Inheritance diagram for pqxx::largeobjectaccess:
[legend]

## 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.
| ~largeobjectaccess () noexcept
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 ()=delete
| 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

## off_type

using pqxx::largeobjectaccess::off_type = size_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

using pqxx::largeobjectaccess::pos_type = size_type

## seekdir

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

Seek direction: `beg`, `cur`, `end`.

## size_type

using pqxx::largeobject::size_type = large_object_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

  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/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

  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/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

  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/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

  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.

## ~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

  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_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

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

## 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

  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

noexcept

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

Compare object identities.

Warning
  Only valid between large objects in the same database.

## operator<()

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

Compare object identities.

Warning
  Only valid between large objects in the same database.

## operator<=()

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

Compare object identities.

Warning
  Only valid between large objects in the same database.

## operator=()

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

delete

References pqxx::largeobject::raw_connection().

## operator==()

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

Compare object identities.

Warning
  Only valid between large objects in the same database.

## operator>()

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

Compare object identities.

Warning
  Only valid between large objects in the same database.

## operator>=()

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

Compare object identities.

Warning
  Only valid between large objects in the same database.

## process_notice()

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

noexcept

Issue message to transaction's notice processor.

## 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

  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.

References pqxx::oid_none.

## remove()

void PQXX_COLD 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_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 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.

## to_file() [1/2]

void PQXX_COLD 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

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.

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

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

References pqxx::internal::cmp_less(), 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

  buf | Data to write; no terminating zero is written.

References write().

Referenced by write().

## Member Data Documentation

## default_mode

constexpr auto pqxx::largeobjectaccess::default_mode

static constexpr

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:

- largeobject.hxx
- largeobject.cxx