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.