NAME

       OpenDBX::Lob - Handling large objects if supported by the database.

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 norbert@linuxnetworks.de

       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.