SYNOPSIS

Public Member Functions

void close () throw ( std::exception )
Closes the large object and commits the changes.
Lob (const Lob &ref) throw ()
Copy constructor.
Lob & operator= (const Lob &ref) throw ()
Assign large object instance to another one.
ssize_t read (void *buffer, size_t buflen) throw ( std::exception )
Reads content from large object into the buffer.
ssize_t write (void *buffer, size_t buflen) throw ( std::exception )
Writes data from the buffer into the large object.
~Lob () throw ()
Destroy large object instance if no other references exist.

Protected Member Functions

Lob () throw ()
Default constructor.
Lob (Lob_Iface *impl) throw ( std::exception )
Create large object instance.

Detailed Description

Handling large objects if supported by the database.

Author:

Norbert Sendetzky [email protected]

Version:

1.0

Constructor & Destructor Documentation

OpenDBX::Lob::Lob () [inline], [protected]

Default constructor. The default constructor isn't part of the public interface as the object must not be created manually. Instead, the Result::getLob() method is a factory for instances of the large object class.

Returns:

Lob instance

OpenDBX::Lob::Lob (Lob_Iface * impl)std::exception [protected]

Create large object instance. The constructor isn't part of the public interface as the object must not be created manually. Instead, the Result::getLob() method is a factory for instances of the large object class.

Parameters:

impl Pointer to private implementation

Returns:

Lob instance

Exceptions:

std::exception If an error occures

OpenDBX::Lob::~Lob ()

Destroy large object instance if no other references exist. Each large object uses a reference counter to remember if the internal variables are shared with other objects. If this isn't the case or if this object is the last one referencing the variables, the object is cleanup up and the allocated memory freed.

OpenDBX::Lob::Lob (const Lob & ref)

Copy constructor. Enables the transfer of the internal state of an object ref of the same type to this object. Both objects share the same variables and the reference counter afterwards. The reference counter is incremented each time an object is copied and will be decremented if it is destroyed.

Parameters:

ref Original large object instance

Member Function Documentation

void OpenDBX::Lob::close ()std::exception

Closes the large object and commits the changes. After reading from or writing new content into the large object, it should be closed to commit changes to the disk and clean up the resources. If this isn't done, the destructor of the object tries to close the large object automatically, but there's no guarantee it was successful as the destructor doesn't throw an exception in case of an error. Therefore, it's highly recommended to call this method once when you don't need the object any more.

Exceptions:

OpenDBX::Exception If the underlying database library returns an error

Lob& OpenDBX::Lob::operator= (const Lob & ref)

Assign large object instance to another one. Assigns the internal state of an object ref of the same type to this object. Both objects share the same variables and the reference counter afterwards. The reference counter is incremented each time an object is copied and will be decremented if it is destroyed.

Parameters:

ref Large object instance

Returns:

Large object reference of this instance

ssize_t OpenDBX::Lob::read (void * buffer, size_t buflen)std::exception

Reads content from large object into the buffer. To get the content of a large object, this method fetches the data in one or more pieces from the server and stores it into the user supplied buffer. The first call to read() will return the bytes from the beginning. The second and all other calls will store subsequent parts of the large object content into the buffer until the end of the data is reached. To reread the content a second time, you have to close the large object handle and reopen it again as some databases provide no way to reposition the internal file position indicator for the stream. The large object content fetched from the server is stored into the user supplied buffer up to buflen bytes.

The method returns the number of bytes placed into buffer, which may be up to buflen bytes. If the end of the content is reached and no more data is available, the return value will be 0 (zero).

Parameters:

buffer Pointer to a byte array where the data should be written to
buflen Length of the given buffer in bytes

Returns:

Number of bytes written into the buffer

Exceptions:

OpenDBX::Exception If the underlying database library returns an error

ssize_t OpenDBX::Lob::write (void * buffer, size_t buflen)std::exception

Writes data from the buffer into the large object. It sends the data supplied in buffer to the server for storing it inside the large object. The function can be called more than once to add subsequent parts of the content to the object. If it isn't a new or empty object, the existing data will be overwritten and truncated to the new size. It's not possible to update only parts of the content as some databases doesn't support to position the internal file position indicator. The data which should be send to the server is read from buffer up to buflen bytes.

The method returns the number of bytes read from buffer and sent to the database server, which may be up to buflen bytes. It isn't guaranteed that the complete chunk was sent to the server, so the returned size may be less than the value in buflen.

Parameters:

buffer Pointer to a byte array where the content is stored
buflen Length of the data in the buffer in bytes

Returns:

Number of bytes written into the large object

Exceptions:

OpenDBX::Exception If the underlying database library returns an error

Author

Generated automatically by Doxygen for opendbx from the source code.