SourcePro® API Reference Guide

 
List of all members | Public Member Functions
RWDBBlob Class Reference

Stores Binary Large Objects (Blobs) and includes relevant accessors. More...

#include <rw/db/blob.h>

Inheritance diagram for RWDBBlob:
RWCollectable

Public Member Functions

 RWDBBlob ()
 
 RWDBBlob (size_t size)
 
 RWDBBlob (void *data, size_t length)
 
 RWDBBlob (const RWDBBlob &blob)
 
void acquire () const
 
virtual RWspace binaryStoreSize () const
 
size_t capacity () const
 
void clear (size_t size=0)
 
virtual int compareTo (const RWCollectable *c) const
 
virtual RWCollectablecopy () const
 
unsigned char * data () const
 
void getBytes (void *buffer, size_t size, size_t offset=0) const
 
virtual unsigned hash () const
 
virtual RWClassID isA () const
 
virtual bool isEqual (const RWCollectable *c) const
 
size_t length () const
 
virtual RWCollectablenewSpecies () const
 
RWDBBloboperator= (const RWDBBlob &blob)
 
void putBytes (const void *buffer, size_t size, size_t offset=0, size_t resize=256)
 
void release () const
 
virtual void restoreGuts (RWFile &file)
 
virtual void restoreGuts (RWvistream &stream)
 
virtual void saveGuts (RWFile &file) const
 
virtual void saveGuts (RWvostream &stream) const
 
- Public Member Functions inherited from RWCollectable
virtual ~RWCollectable ()
 
RWspace recursiveStoreSize () const
 
RWStringID stringID () const
 

Additional Inherited Members

- Static Public Member Functions inherited from RWCollectable
static RWClassID classID (const RWStringID &name)
 
static RWClassID classIsA ()
 
static bool isAtom (RWClassID id)
 
static RWspace nilStoreSize ()
 

Detailed Description

Most database vendors supply one or more data types that can store binary data of any length. These data types are commonly known as Binary Large Objects or Blobs. The DB Interface Module stores data of these types as RWDBBlob. Class RWDBBlob provides storage and rudimentary access to the binary data. Applications may want to derive from RWDBBlob to add semantics to the data.

This class is implemented using a technique called copy on write. With this technique, the copy constructor and assignment operators still reference the old object and hence are very fast. An actual copy is made only when a write is performed, that is, if the object is about to be changed. The net result is excellent performance, but with easy-to-understand value semantics.

The member function putBytes() is used to populate an RWDBBlob. This method is safe and robust, but can be inconvenient in cases where large objects have already been loaded into memory. The constructor RWDBBlob(void* data, size_t length) is provided to allow applications to wrap existing data blocks in an RWDBBlob interface. Blobs built with this constructor do not manage the memory addressed by the data pointer; your application continues to be responsible for it.

RWDBBlob inherits from class RWCollectable. The virtual functions of the base class RWCollectable have been redefined.

Synopsis
#include <rw/db/blob.h>
RWDBBlob b; // default; zero capacity and length
RWDBBlob b(2048);
RWDBBlob b((void*)&myGif.data(),myGif.size());

Constructor & Destructor Documentation

RWDBBlob::RWDBBlob ( )

Default constructor. Creates a blob with zero capacity and length.

RWDBBlob::RWDBBlob ( size_t  size)

Creates a blob that has an initial capacity to store size bytes of binary data. The length is set to zero.

RWDBBlob::RWDBBlob ( void *  data,
size_t  length 
)

Creates a blob using the data block provided. The caller retains ownership of the data, and is responsible for providing an accurate length, for ensuring that the data pointer is valid for the lifetime of the blob, and for deallocation of the data, if necessary.

RWDBBlob::RWDBBlob ( const RWDBBlob blob)

Copy constructor. The created blob shares data with blob until the data is modified.

Member Function Documentation

void RWDBBlob::acquire ( ) const

Attempts to acquire the internal mutex lock. If the mutex is already locked by another thread, the function blocks until the mutex is released. This function can be called from a const object.

Note
In single-threaded builds, this function evaluates to a no-op.
virtual RWspace RWDBBlob::binaryStoreSize ( ) const
virtual

Returns the number of bytes needed to store self.

Reimplemented from RWCollectable.

size_t RWDBBlob::capacity ( ) const

Returns the current capacity of self in bytes. This is the number of bytes self can hold without resizing.

void RWDBBlob::clear ( size_t  size = 0)

Sets self's data length to 0 and capacity to size. If the current capacity is not equal to size, reallocates memory to adjust self's capacity to size. To avoid reallocation of memory, pass the current capacity as size.

virtual int RWDBBlob::compareTo ( const RWCollectable c) const
virtual

If c points to an RWDBBlob, returns 0 if c shares the same data or compares equal according to std::memcmp, otherwise returns a nonzero value.

Reimplemented from RWCollectable.

virtual RWCollectable* RWDBBlob::copy ( ) const
virtual

Returns a new, copy-constructed object of the same type as self. The caller is responsible for deleting the object.

Reimplemented from RWCollectable.

unsigned char* RWDBBlob::data ( ) const

Provides access to the blob's data as a pointer to the data storage. The data storage is owned by the RWDBBlob and may not be changed or deleted. If the data must be manipulated, the application should derive from RWDBBlob to gain access to the protected data storage and controls.

void RWDBBlob::getBytes ( void *  buffer,
size_t  size,
size_t  offset = 0 
) const

Copies size bytes, starting at self's offset to buffer. The buffer is assumed to be large enough to contain the bytes. Failure to provide a large enough buffer results in a memory overwrite, which may have unpredictable results.

virtual unsigned RWDBBlob::hash ( ) const
virtual

Returns a hash value for use in collection classes.

Reimplemented from RWCollectable.

virtual RWClassID RWDBBlob::isA ( ) const
virtual

Redefined from class RWCollectable. Returns __RWDBBLOB.

Reimplemented from RWCollectable.

virtual bool RWDBBlob::isEqual ( const RWCollectable t) const
virtual

Behaves as if compareTo(t) was invoked, returning true if the result equals 0, false otherwise.

Reimplemented from RWCollectable.

size_t RWDBBlob::length ( ) const

Returns the current length of self's data in bytes.

virtual RWCollectable* RWDBBlob::newSpecies ( ) const
virtual

Returns a new, default-constructed object of the same type as self. The caller is responsible for deleting the object.

Reimplemented from RWCollectable.

RWDBBlob& RWDBBlob::operator= ( const RWDBBlob blob)

Assignment operator. Self shares data with blob until the data is modified. Returns a reference to self.

void RWDBBlob::putBytes ( const void *  buffer,
size_t  size,
size_t  offset = 0,
size_t  resize = 256 
)

Copies size bytes from buffer into self, starting at self's offset. Exactly size bytes are copied, and therefore buffer is assumed to contain at least size bytes. Self's capacity is enlarged by multiples of resize bytes if the existing capacity is insufficient.

void RWDBBlob::release ( ) const

Releases a previously acquired mutex. This function can be called from a const object.

Note
In single-threaded builds, this function evaluates to a no-op.
virtual void RWDBBlob::restoreGuts ( RWFile file)
virtual

Reads file, replacing the contents of self.

Reimplemented from RWCollectable.

virtual void RWDBBlob::restoreGuts ( RWvistream stream)
virtual

Reads stream, replacing the contents of self.

Reimplemented from RWCollectable.

virtual void RWDBBlob::saveGuts ( RWFile file) const
virtual

Writes the contents of self to file.

Reimplemented from RWCollectable.

virtual void RWDBBlob::saveGuts ( RWvostream stream) const
virtual

Writes the contents of self to stream.

Reimplemented from RWCollectable.

Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.