BStreamDatum Class Reference
[Data Model]

#include <storage/StreamDatum.h>

Inheritance diagram for BStreamDatum:

Detailed Description

Base implementation of IDatum from stream-like data operations.

This is the standard base implementation of IDatum. It takes care of all the IDatum APIs, introducing new higher-level virtuals that derived classes can then implement. In particular, it introduces a locking regimen to the class, and a standard implementation of Open() that generates stream objects which call back on to BStreamDatum for their implementation.

There are two general approaches derived classes can take to create a concrete class: using a stream model or a memory model.

To use a stream model, you will need to implement at least the virtuals StoreSizeLocked(), StoreLocked(), ReadLocked(), and WriteLocked(). You may also implement other virtuals to provide additional functionality (such as StoreValueTypeLocked()) or a more optimal implementation (such as StoreValueLocked()).

To use a memory model, you will need to implement at least the virtuals StoreSizeLocked(), SizeLocked(), StartReadingLocked(), FinishReadingLocked(), StartWritingLocked(), and FinishWritingLocked(). You will also almost always be able to provide a better implementation of StoreValueLocked() and ValueLocked(), so should do so.

New IDatum Virtuals

Subclasses must implement SizeLocked() and StoreSizeLocked() as part of the basic protocol. You can override the other virtuals to customize/optimize how values are returned. You don't need to do your own locking, since these are called with the datum lock held. You also don't need to worry about pushing properties or events as a result of changes, which will also be done for you by this class.

enum { TYPE_CHANGED = 0x0001, SIZE_CHANGED = 0x0002, DATA_CHANGED = 0x0004 }

virtual void ReportChangeLocked (const sptr< IBinder > &editor, uint32_t changes, off_t start=-1, off_t length=-1)

Called when any part of the datum (data, type, size) changes.

virtual off_t SizeLocked () const =0

Derived classes must implement to return the total amount of data available.

virtual status_t StoreSizeLocked (off_t size)=0

Derived classes must implement to set the total amount of data.

virtual status_t StoreValueLocked (const SValue &value)

The default implementation changes the contents of the datum to the value.

virtual status_t StoreValueTypeLocked (uint32_t type)

The default implementation does nothing, returning B_UNSUPPORTED.

virtual SValue ValueLocked () const

The default implementation generates a new SValue from the datum.

virtual uint32_t ValueTypeLocked () const

The default implementation returns B_RAW_TYPE.

Bookkeeping

Creation, destruction, locking, etc.

BStreamDatum (const SContext &context, uint32_t mode=IDatum::READ_WRITE)

BStreamDatum (uint32_t mode=IDatum::READ_WRITE)

virtual lock_status_t Lock () const

Lock the datum's state.

uint32_t Mode () const

Return the mode flags the class was instantiated with.

virtual void Unlock () const

Unlock the datum's state.

static uint32_t RestrictMode (uint32_t requested, uint32_t limit)

Return a new mode value based on a requested mode and desired read/write limitations.

virtual ~BStreamDatum ()

Stream Virtuals

These virtuals allow you to implement memory operations on the datum. Return a buffer of data from the Start functions, which will be read or written as needed; you can do whatever cleanup is needed after that in the Finish functions. Note that StartWritingLocked() (or FinishWritingLocked()) MUST take care of the B_WRITE_END flag for truncating the datum size.
You are guaranteed that the datum will not be unlocked between the start and end calls.

Note:
These functions will be called with stream set to NULL when being used by the default implementation of ValueLocked() and StoreValueLocked().

virtual void FinishReadingLocked (const sptr< Stream > &stream, const void *data) const

The default implementation does nothing.

virtual void FinishWritingLocked (const sptr< Stream > &stream, void *data)

The default implementation does nothing.

virtual const void * StartReadingLocked (const sptr< Stream > &stream, off_t position, ssize_t *inoutSize, uint32_t flags) const

The default implementation returns NULL.

virtual void * StartWritingLocked (const sptr< Stream > &stream, off_t position, ssize_t *inoutSize, uint32_t flags)

The default implementation returns NULL.

IDatum Implementation

This class provides a default implementation of the IDatum API. You will need to fill in the new pure virtuals it has to have a concrete implementation.

virtual sptr< IBinder > Open (uint32_t mode, const sptr< IBinder > &editor=NULL, uint32_t newType=0)

Creates a new Stream object on the datum.

virtual void SetSize (off_t size)

Acquires the datum lock and calls SetSizeLocked().

status_t SetSizeLocked (off_t size)

Uses StoreSizeLocked() to change the size and calls ReportChangeLocked() as appropriate.

virtual void SetValue (const SValue &value)

Acquires the datum lock and calls SetValueLocked().

status_t SetValueLocked (const SValue &value)

Uses StoreValueLocked() to change the value and calls ReportChangeLocked() as appropriate.

virtual void SetValueType (uint32_t type)

Acquires the datum lock and calls SetValueTypeLocked().

status_t SetValueTypeLocked (uint32_t type)

Uses StoreValueTypeLocked() to change the type and calls ReportChangeLocked() as appropriate.

virtual off_t Size () const

Acquires the datum lock and calls SizeLocked().

virtual SValue Value () const

Acquires the datum lock and calls ValueLocked().

virtual uint32_t ValueType () const

Acquires the datum lock and calls ValueTypeLocked().

Raw Stream Virtuals

These virtuals allow you to implement raw byte stream operations on the datum. These are used to implement stream-style datums, such as one representing a file on a filesystem. The default implementation translates these into the memory-style operations StartReadingLocked(), FinishReadingLocked(), StartWritingLocked(), and FinishWritingLocked().
One case where you may need to override these instead is to implement datums that can block when reading or writing. In that case you can temporarily unlock the datum while inside these functions (need to check if the implementation here will actually be happy with that).

Note:
These functions will be called with stream set to NULL when being used by the default implementation of ValueLocked() and StoreValueLocked().

virtual ssize_t ReadLocked (const sptr< Stream > &stream, off_t position, const struct iovec *vector, ssize_t count, uint32_t flags) const

Retrieve bytes from the datum and place them into the iovec.

virtual status_t SyncLocked ()

Block until all data has been written to storage.

virtual ssize_t WriteLocked (const sptr< Stream > &stream, off_t position, const struct iovec *vector, ssize_t count, uint32_t flags)

Write bytes from the iovec into the datum.

Friends

class Stream

Classes

class Stream

An open stream on BStreamDatum. More...

Member Enumeration Documentation

anonymous enum

Enumerator:

TYPE_CHANGED Use with ReportChangeLocked() when the type property has changed.

SIZE_CHANGED Use with ReportChangeLocked() when the size property has changed.

DATA_CHANGED Use with ReportChangeLocked() when the data contents have changed.

Reimplemented from IDatum.

Constructor & Destructor Documentation

BStreamDatum ( uint32_t mode = IDatum::READ_WRITE )

BStreamDatum ( const SContext & context,

uint32_t mode = IDatum::READ_WRITE

)

~BStreamDatum ( ) [protected, virtual]

Member Function Documentation

void FinishReadingLocked ( const sptr< Stream > & stream,

const void * data

) const [virtual]

The default implementation does nothing.

Reimplemented in SDatumGeneratorInt::IndexedDatum, and BValueDatum.

void FinishWritingLocked ( const sptr< Stream > & stream,

void * data

) [virtual]

The default implementation does nothing.

Reimplemented in SDatumGeneratorInt::IndexedDatum, and BValueDatum.

lock_status_t Lock ( ) const [virtual]

Lock the datum's state.
To keep itself consistent, this class provides a public lock that is used when doing read/write operations on the class state as well as the actual data. The default implemention of this method acquires an internal lock. You can override it to cause all internal implementation to acquire some other lock. Be sure to also override Unlock() if doing so.
Reimplemented in SDatumGeneratorInt::IndexedDatum.

uint32_t Mode ( ) const

Return the mode flags the class was instantiated with.

sptr< IBinder > Open ( uint32_t mode,

const sptr< IBinder > & editor = NULL,

uint32_t newType = 0

) [virtual]

Creates a new Stream object on the datum.

Implements IDatum.

ssize_t ReadLocked ( const sptr< Stream > & stream,

off_t position,

const struct iovec * vector,

ssize_t count,

uint32_t flags

) const [virtual]

Retrieve bytes from the datum and place them into the iovec.

void ReportChangeLocked ( const sptr< IBinder > & editor,

uint32_t changes,

off_t start = -1,

off_t length = -1

) [virtual]

Called when any part of the datum (data, type, size) changes.
The default implementation pushes the appropriate properties and events based on the changes flags, which may be any of TYPE_CHANGED, SIZE_CHANGED, or DATA_CHANGED. The value property is always pushed. For DATA_CHANGED, start and length must be supplied with the range of data that changed; for all other changes, ValueLocked(), ValueTypeLocked(), and SizeLocked() are called as needed to retrieve the current values.
You can override this method in your own subclass to easily discover when changes happen. If you do so, be sure to also call through to this implementation.
Reimplemented in SDatumGeneratorInt::IndexedDatum.

uint32_t RestrictMode ( uint32_t requested,

uint32_t limit

) [static]

Return a new mode value based on a requested mode and desired read/write limitations.

void SetSize ( off_t size ) [virtual]

Acquires the datum lock and calls SetSizeLocked().

Implements IDatum.

status_t SetSizeLocked ( off_t size )

Uses StoreSizeLocked() to change the size and calls ReportChangeLocked() as appropriate.

void SetValue ( const SValue & value ) [virtual]

Acquires the datum lock and calls SetValueLocked().

Implements IDatum.

status_t SetValueLocked ( const SValue & value )

Uses StoreValueLocked() to change the value and calls ReportChangeLocked() as appropriate.

void SetValueType ( uint32_t type ) [virtual]

Acquires the datum lock and calls SetValueTypeLocked().

Implements IDatum.

status_t SetValueTypeLocked ( uint32_t type )

Uses StoreValueTypeLocked() to change the type and calls ReportChangeLocked() as appropriate.

off_t Size ( ) const [virtual]

Acquires the datum lock and calls SizeLocked().

Implements IDatum.

virtual off_t SizeLocked ( ) const [pure virtual]

Derived classes must implement to return the total amount of data available.

Implemented in SDatumGeneratorInt::IndexedDatum, and BValueDatum.

const void * StartReadingLocked ( const sptr< Stream > & stream,

off_t position,

ssize_t * inoutSize,

uint32_t flags

) const [virtual]

The default implementation returns NULL.

Reimplemented in SDatumGeneratorInt::IndexedDatum, and BValueDatum.

void * StartWritingLocked ( const sptr< Stream > & stream,

off_t position,

ssize_t * inoutSize,

uint32_t flags

) [virtual]

The default implementation returns NULL.

Reimplemented in SDatumGeneratorInt::IndexedDatum, and BValueDatum.

virtual status_t StoreSizeLocked ( off_t size ) [pure virtual]

Derived classes must implement to set the total amount of data.

Implemented in SDatumGeneratorInt::IndexedDatum, and BValueDatum.

status_t StoreValueLocked ( const SValue & value ) [virtual]

The default implementation changes the contents of the datum to the value.
The datum is changed by calling StoreValueTypeLocked(), StoreSizeLocked(), and StoreLocked(). This is fairly inefficient, so you will want to provide your own implementation if possible.
Reimplemented in SDatumGeneratorInt::IndexedDatum, and BValueDatum.

status_t StoreValueTypeLocked ( uint32_t type ) [virtual]

The default implementation does nothing, returning B_UNSUPPORTED.

Reimplemented in SDatumGeneratorInt::IndexedDatum, and BValueDatum.

status_t SyncLocked ( ) [virtual]

Block until all data has been written to storage.

void Unlock ( ) const [virtual]

Unlock the datum's state.

Reimplemented in SDatumGeneratorInt::IndexedDatum.

SValue Value ( ) const [virtual]

Acquires the datum lock and calls ValueLocked().

Implements IDatum.

SValue ValueLocked ( ) const [virtual]

The default implementation generates a new SValue from the datum.
The SValue is created by calling ValueTypeLocked(), SizeLocked(), and ReadLocked(). This is fairly inefficient, so you will want to provide your own implementation if possible. It will not attempt to return the datum as an SValue if the datum is larger than a reasonable size (a couple kilobytes).
Reimplemented in SDatumGeneratorInt::IndexedDatum, and BValueDatum.

uint32_t ValueType ( ) const [virtual]

Acquires the datum lock and calls ValueTypeLocked().

Implements IDatum.

uint32_t ValueTypeLocked ( ) const [virtual]

The default implementation returns B_RAW_TYPE.

Reimplemented in SDatumGeneratorInt::IndexedDatum, and BValueDatum.

ssize_t WriteLocked ( const sptr< Stream > & stream,

off_t position,

const struct iovec * vector,

ssize_t count,

uint32_t flags

) [virtual]

Write bytes from the iovec into the datum.

Friends And Related Function Documentation

friend class Stream [friend]

The documentation for this class was generated from the following files:


New IDatum Virtuals
Subclasses must implement SizeLocked() and StoreSizeLocked() as part of the basic protocol. You can override the other virtuals to customize/optimize how values are returned. You don't need to do your own locking, since these are called with the datum lock held. You also don't need to worry about pushing properties or events as a result of changes, which will also be done for you by this class.
enum	{ TYPE_CHANGED = 0x0001, SIZE_CHANGED = 0x0002, DATA_CHANGED = 0x0004 }
virtual void	ReportChangeLocked (const sptr< IBinder > &editor, uint32_t changes, off_t start=-1, off_t length=-1)
	Called when any part of the datum (data, type, size) changes.
virtual off_t	SizeLocked () const =0
	Derived classes must implement to return the total amount of data available.
virtual status_t	StoreSizeLocked (off_t size)=0
	Derived classes must implement to set the total amount of data.
virtual status_t	StoreValueLocked (const SValue &value)
	The default implementation changes the contents of the datum to the value.
virtual status_t	StoreValueTypeLocked (uint32_t type)
	The default implementation does nothing, returning B_UNSUPPORTED.
virtual SValue	ValueLocked () const
	The default implementation generates a new SValue from the datum.
virtual uint32_t	ValueTypeLocked () const
	The default implementation returns B_RAW_TYPE.
Bookkeeping
Creation, destruction, locking, etc.
	BStreamDatum (const SContext &context, uint32_t mode=IDatum::READ_WRITE)
	BStreamDatum (uint32_t mode=IDatum::READ_WRITE)
virtual lock_status_t	Lock () const
	Lock the datum's state.
uint32_t	Mode () const
	Return the mode flags the class was instantiated with.
virtual void	Unlock () const
	Unlock the datum's state.
static uint32_t	RestrictMode (uint32_t requested, uint32_t limit)
	Return a new mode value based on a requested mode and desired read/write limitations.
virtual	~BStreamDatum ()
Stream Virtuals
These virtuals allow you to implement memory operations on the datum. Return a buffer of data from the Start functions, which will be read or written as needed; you can do whatever cleanup is needed after that in the Finish functions. Note that StartWritingLocked() (or FinishWritingLocked()) MUST take care of the B_WRITE_END flag for truncating the datum size. You are guaranteed that the datum will not be unlocked between the start and end calls. Note: These functions will be called with stream set to NULL when being used by the default implementation of ValueLocked() and StoreValueLocked().
virtual void	FinishReadingLocked (const sptr< Stream > &stream, const void *data) const
	The default implementation does nothing.
virtual void	FinishWritingLocked (const sptr< Stream > &stream, void *data)
	The default implementation does nothing.
virtual const void *	StartReadingLocked (const sptr< Stream > &stream, off_t position, ssize_t *inoutSize, uint32_t flags) const
	The default implementation returns NULL.
virtual void *	StartWritingLocked (const sptr< Stream > &stream, off_t position, ssize_t *inoutSize, uint32_t flags)
	The default implementation returns NULL.
IDatum Implementation
This class provides a default implementation of the IDatum API. You will need to fill in the new pure virtuals it has to have a concrete implementation.
virtual sptr< IBinder >	Open (uint32_t mode, const sptr< IBinder > &editor=NULL, uint32_t newType=0)
	Creates a new Stream object on the datum.
virtual void	SetSize (off_t size)
	Acquires the datum lock and calls SetSizeLocked().
status_t	SetSizeLocked (off_t size)
	Uses StoreSizeLocked() to change the size and calls ReportChangeLocked() as appropriate.
virtual void	SetValue (const SValue &value)
	Acquires the datum lock and calls SetValueLocked().
status_t	SetValueLocked (const SValue &value)
	Uses StoreValueLocked() to change the value and calls ReportChangeLocked() as appropriate.
virtual void	SetValueType (uint32_t type)
	Acquires the datum lock and calls SetValueTypeLocked().
status_t	SetValueTypeLocked (uint32_t type)
	Uses StoreValueTypeLocked() to change the type and calls ReportChangeLocked() as appropriate.
virtual off_t	Size () const
	Acquires the datum lock and calls SizeLocked().
virtual SValue	Value () const
	Acquires the datum lock and calls ValueLocked().
virtual uint32_t	ValueType () const
	Acquires the datum lock and calls ValueTypeLocked().
Raw Stream Virtuals
These virtuals allow you to implement raw byte stream operations on the datum. These are used to implement stream-style datums, such as one representing a file on a filesystem. The default implementation translates these into the memory-style operations StartReadingLocked(), FinishReadingLocked(), StartWritingLocked(), and FinishWritingLocked(). One case where you may need to override these instead is to implement datums that can block when reading or writing. In that case you can temporarily unlock the datum while inside these functions (need to check if the implementation here will actually be happy with that). Note: These functions will be called with stream set to NULL when being used by the default implementation of ValueLocked() and StoreValueLocked().
virtual ssize_t	ReadLocked (const sptr< Stream > &stream, off_t position, const struct iovec *vector, ssize_t count, uint32_t flags) const
	Retrieve bytes from the datum and place them into the iovec.
virtual status_t	SyncLocked ()
	Block until all data has been written to storage.
virtual ssize_t	WriteLocked (const sptr< Stream > &stream, off_t position, const struct iovec *vector, ssize_t count, uint32_t flags)
	Write bytes from the iovec into the datum.
Friends
class	Stream
Classes
class	Stream
	An open stream on BStreamDatum. More...

BStreamDatum Class Reference [Data Model]

Detailed Description

New IDatum Virtuals

Bookkeeping

Stream Virtuals

IDatum Implementation

Raw Stream Virtuals

Friends

Classes

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

BStreamDatum Class Reference
[Data Model]