# pqxx::largeobjectaccess Class Reference

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

`#include <largeobject.hxx>`

Inheritance diagram for pqxx::largeobjectaccess:

[legend]

List of all members.

## Public Types
typedef long | off_type
typedef size_type | pos_type
typedef std::ios::openmode | openmode
| Open mode: `in`, `out` (can be combined with the "or" operator).
typedef std::ios::seekdir | seekdir
| Seek direction: `beg`, `cur`, `end`.
typedef long | size_type
## Public Member Functions
| largeobjectaccess (dbtransaction &T, openmode mode=std::ios::in|std::ios::out)
| Create new large object and open it.
| largeobjectaccess (dbtransaction &T, oid O, openmode mode=std::ios::in|std::ios::out)
| Open large object with given oid.
| largeobjectaccess (dbtransaction &T, largeobject O, openmode mode=std::ios::in|std::ios::out)
| Open given large object.
| largeobjectaccess (dbtransaction &T, const std::string &File, openmode mode=std::ios::in|std::ios::out)
| Import large object from a local file and open it.
| ~largeobjectaccess () throw ()
void | to_file (const std::string &File) const
| Export large object's contents to a local file.
High-level access to object contents
void | write (const char Buf[], size_type Len)
| Write data to large object.
void | write (const std::string &Buf)
| Write string to large object.
size_type | read (char Buf[], size_type 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.
pos_type | cseek (off_type dest, seekdir dir) throw ()
| Seek in large object's data stream.
off_type | cwrite (const char Buf[], size_type Len) throw ()
| Write to large object's data stream.
off_type | cread (char Buf[], size_type Len) throw ()
| Read from large object's data stream.
pos_type | ctell () const throw ()
| Report current position in large object's data stream.
Error/warning output
void | process_notice (const std::string &) throw ()
| Issue message to transaction's notice processor.

## Detailed Description

Accessor for large object's contents.

## Member Typedef Documentation

typedef long pqxx::largeobjectaccess::off_type

typedef std ::ios::openmode pqxx::largeobjectaccess::openmode

Open mode: `in`, `out` (can be combined with the "or" operator).

According to the C++ standard, these should be in `std::ios_base`. We take them from `std::ios` instead, which should be safe because it inherits the same definition, to accommodate gcc 2.95 & 2.96.

typedef size_type pqxx::largeobjectaccess::pos_type

typedef std ::ios::seekdir pqxx::largeobjectaccess::seekdir

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

According to the C++ standard, these should be in `std::ios_base`. We take them from `std::ios` instead, which should be safe because it inherits the same definition, to accommodate gcc 2.95 & 2.96.

typedef long pqxx::largeobject::size_type

## Constructor & Destructor Documentation

pqxx::largeobjectaccess::largeobjectaccess | ( | dbtransaction & | T,
|  | openmode | mode = `std ::ios::in | std ::ios::out` |
| ) |  |  | `[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

References largeobjectaccess().

Referenced by largeobjectaccess().

pqxx::largeobjectaccess::largeobjectaccess | ( | dbtransaction & | T,
|  | oid | O,
|  | openmode | mode = `std ::ios::in | std ::ios::out` |
| ) |  |  |

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

References largeobjectaccess().

pqxx::largeobjectaccess::largeobjectaccess | ( | dbtransaction & | T,
|  | largeobject | O,
|  | openmode | mode = `std ::ios::in | std ::ios::out` |
| ) |  |  |

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

References largeobjectaccess().

pqxx::largeobjectaccess::largeobjectaccess | ( | dbtransaction & | T,
|  | const std::string & | File,
|  | openmode | mode = `std ::ios::in | std ::ios::out` |
| ) |  |  |

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

References largeobjectaccess().

pqxx::largeobjectaccess::~largeobjectaccess | ( |  | ) | throw ()

## Member Function Documentation

pqxx::largeobjectaccess::pos_type pqxx::largeobjectaccess::cread | ( | char | Buf[],
|  | size_type | Len |
| ) |  |  | throw ()

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.

Referenced by read().

pqxx::largeobjectaccess::pos_type pqxx::largeobjectaccess::cseek | ( | off_type | dest,
|  | seekdir | dir |
| ) |  |  | throw ()

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.

Referenced by seek().

pqxx::largeobjectaccess::pos_type pqxx::largeobjectaccess::ctell | ( |  | ) | const throw ()

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().

pqxx::largeobjectaccess::pos_type pqxx::largeobjectaccess::cwrite | ( | const char | Buf[],
|  | size_type | Len |
| ) |  |  | throw ()

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.

Referenced by write().

void pqxx::largeobjectaccess::process_notice | ( | const std::string & | s | ) | throw ()

Issue message to transaction's notice processor.

pqxx::largeobjectaccess::size_type pqxx::largeobjectaccess::read | ( | char | Buf[],
|  | size_type | 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 cread(), and pqxx::to_string().

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

References cseek().

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

References ctell().

void pqxx::largeobjectaccess::to_file | ( | const std::string & | 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().

void pqxx::largeobjectaccess::write | ( | const std::string & | 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().

void pqxx::largeobjectaccess::write | ( | const char | Buf[],
|  | size_type | Len |
| ) |  |  |

Write data to large object.

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

Parameters:

  | Buf | Data to write
  | Len | Number of bytes from Buf to write

References cwrite(), and pqxx::to_string().

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

- largeobject.hxx
- largeobject.cxx