.TH "OpenDBX::Lob" 3 "Fri Sep 5 2014" "Version 1.4.6" "opendbx" \" -*- nroff -*-
.ad l
.nh
.SH NAME
OpenDBX::Lob \- 
.PP
Handling large objects if supported by the database\&.  

.SH SYNOPSIS
.br
.PP
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "void \fBclose\fP ()  throw ( std::exception )"
.br
.RI "\fICloses the large object and commits the changes\&. \fP"
.ti -1c
.RI "\fBLob\fP (const \fBLob\fP &ref)  throw ()"
.br
.RI "\fICopy constructor\&. \fP"
.ti -1c
.RI "\fBLob\fP & \fBoperator=\fP (const \fBLob\fP &ref)  throw ()"
.br
.RI "\fIAssign large object instance to another one\&. \fP"
.ti -1c
.RI "ssize_t \fBread\fP (void *buffer, size_t buflen)  throw ( std::exception )"
.br
.RI "\fIReads content from large object into the buffer\&. \fP"
.ti -1c
.RI "ssize_t \fBwrite\fP (void *buffer, size_t buflen)  throw ( std::exception )"
.br
.RI "\fIWrites data from the buffer into the large object\&. \fP"
.ti -1c
.RI "\fB~Lob\fP ()  throw ()"
.br
.RI "\fIDestroy large object instance if no other references exist\&. \fP"
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "\fBLob\fP ()  throw ()"
.br
.RI "\fIDefault constructor\&. \fP"
.ti -1c
.RI "\fBLob\fP (Lob_Iface *impl)  throw ( std::exception )"
.br
.RI "\fICreate large object instance\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
Handling large objects if supported by the database\&. 


.PP
\fBAuthor:\fP
.RS 4
Norbert Sendetzky norbert@linuxnetworks.de 
.RE
.PP
\fBVersion:\fP
.RS 4
1\&.0 
.RE
.PP

.SH "Constructor & Destructor Documentation"
.PP 
.SS "OpenDBX::Lob::Lob ()\fC [inline]\fP, \fC [protected]\fP"

.PP
Default constructor\&. The default constructor isn't part of the public interface as the object must not be created manually\&. Instead, the \fBResult::getLob()\fP method is a factory for instances of the large object class\&.
.PP
\fBReturns:\fP
.RS 4
\fBLob\fP instance 
.RE
.PP

.SS "OpenDBX::Lob::Lob (Lob_Iface *impl)std::exception\fC [protected]\fP"

.PP
Create large object instance\&. The constructor isn't part of the public interface as the object must not be created manually\&. Instead, the \fBResult::getLob()\fP method is a factory for instances of the large object class\&.
.PP
\fBParameters:\fP
.RS 4
\fIimpl\fP Pointer to private implementation 
.RE
.PP
\fBReturns:\fP
.RS 4
\fBLob\fP instance 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fIstd::exception\fP If an error occures 
.RE
.PP

.SS "OpenDBX::Lob::~Lob ()"

.PP
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\&. 
.SS "OpenDBX::Lob::Lob (const \fBLob\fP &ref)"

.PP
Copy constructor\&. Enables the transfer of the internal state of an object \fIref\fP 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\&.
.PP
\fBParameters:\fP
.RS 4
\fIref\fP Original large object instance 
.RE
.PP

.SH "Member Function Documentation"
.PP 
.SS "void OpenDBX::Lob::close ()std::exception"

.PP
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\&.
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP

.SS "\fBLob\fP& OpenDBX::Lob::operator= (const \fBLob\fP &ref)"

.PP
Assign large object instance to another one\&. Assigns the internal state of an object \fIref\fP 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\&.
.PP
\fBParameters:\fP
.RS 4
\fIref\fP Large object instance 
.RE
.PP
\fBReturns:\fP
.RS 4
Large object reference of this instance 
.RE
.PP

.SS "ssize_t OpenDBX::Lob::read (void *buffer, size_tbuflen)std::exception"

.PP
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 \fBread()\fP 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 \fIbuffer\fP up to \fIbuflen\fP bytes\&.
.PP
The method returns the number of bytes placed into \fIbuffer\fP, which may be up to \fIbuflen\fP bytes\&. If the end of the content is reached and no more data is available, the return value will be 0 (zero)\&.
.PP
\fBParameters:\fP
.RS 4
\fIbuffer\fP Pointer to a byte array where the data should be written to 
.br
\fIbuflen\fP Length of the given buffer in bytes 
.RE
.PP
\fBReturns:\fP
.RS 4
Number of bytes written into the buffer 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP

.SS "ssize_t OpenDBX::Lob::write (void *buffer, size_tbuflen)std::exception"

.PP
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 \fIbuffer\fP up to \fIbuflen\fP bytes\&.
.PP
The method returns the number of bytes read from \fIbuffer\fP and sent to the database server, which may be up to \fIbuflen\fP 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 \fIbuflen\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIbuffer\fP Pointer to a byte array where the content is stored 
.br
\fIbuflen\fP Length of the data in the buffer in bytes 
.RE
.PP
\fBReturns:\fP
.RS 4
Number of bytes written into the large object 
.RE
.PP
\fBExceptions:\fP
.RS 4
\fI\fBOpenDBX::Exception\fP\fP If the underlying database library returns an error 
.RE
.PP


.SH "Author"
.PP 
Generated automatically by Doxygen for opendbx from the source code\&.