Loading...
Searching...
No Matches
pqxx::largeobjectaccess Class Reference

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

Inheritance diagram for pqxx::largeobjectaccess:
[legend]
Collaboration 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.
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

inline 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

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

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:

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