SDatum Class Reference
[Data Model]

#include <support/Datum.h>

Detailed Description

Convenience class for using an IDatum.

This class makes it easier to work with the dual nature of IDatum (SValue vs. Open()) by providing new APIs for retrieving the datum value that are more robust for the client.

Bookkeeping

Creation, destruction, copying, comparing, etc.

sptr< IDatum > Datum () const

Retrieve the IDatum object being used.

bool operator!= (const SDatum &o) const

Retrieve the IDatum object being used.

bool operator< (const SDatum &o) const

Retrieve the IDatum object being used.

bool operator<= (const SDatum &o) const

Retrieve the IDatum object being used.

SDatum & operator= (const SDatum &o)

Replace this SDatum with o.

bool operator== (const SDatum &o) const

Retrieve the IDatum object being used.

bool operator> (const SDatum &o) const

Retrieve the IDatum object being used.

bool operator>= (const SDatum &o) const

Retrieve the IDatum object being used.

SDatum (const SDatum &datum)

Copy from another SDatum.

SDatum (const sptr< IDatum > &datum)

Initialize directly from an IDatum.

SDatum (const sptr< IBinder > &binder)

Retrieve a datum from an IBinder, casting to an IDatum interface.

SDatum (const SValue &value)

Retrieve a datum from a generic SValue.

SDatum ()

Create a new, empty datum.

status_t StatusCheck () const

Returns B_OK if we hold a value IDatum or defined SValue.

~SDatum ()

Release reference on IDatum.

Datum Operations

Convenience functions for working with IDatum.

SValue FetchTruncatedValue (size_t maxSize, status_t *outError=NULL) const

Retrieve data, possibly truncated, associated with this value.

SValue FetchValue (size_t maxSize, status_t *outError=NULL) const

Retrieve the entire data associated with this value.

sptr< IByteInput > OpenInput (uint32_t mode=IDatum::READ_ONLY, status_t *outError=NULL) const

Open datum for reading.

sptr< IByteOutput > OpenOutput (uint32_t mode, const sptr< IBinder > &editor, uint32_t newType, status_t *outError=NULL)

Open datum for writing, allowing editor objects and/or type changes.

sptr< IByteOutput > OpenOutput (uint32_t mode=IDatum::READ_WRITE|IDatum::ERASE_DATUM, status_t *outError=NULL)

Open datum for simple writing.

Constructor & Destructor Documentation

SDatum ( )

Create a new, empty datum.

SDatum ( const SValue & value )

Retrieve a datum from a generic SValue.
If the SValue contains an IDatum object, that will be used directly. Otherwise, the SValue will be used as a plain blob of data, as if it has been retrieved from IDatum::Value().

SDatum ( const sptr< IBinder > & binder )

Retrieve a datum from an IBinder, casting to an IDatum interface.

SDatum ( const sptr< IDatum > & datum )

Initialize directly from an IDatum.

SDatum ( const SDatum & datum )

Copy from another SDatum.

~SDatum ( )

Release reference on IDatum.

Member Function Documentation

sptr< IDatum > Datum ( ) const

Retrieve the IDatum object being used.

SValue FetchTruncatedValue ( size_t maxSize,

status_t * outError = NULL

) const

Retrieve data, possibly truncated, associated with this value.

Parameters:

[in] maxSize Maximum number of bytes to read from the datum if using IDatum::Open(); if it is larger, only that number of bytes is read and outError is set to B_DATA_TRUNCATED.

[out] outError Optional error code output in the case when B_UNDEFINED_VALUE is returned or data is truncated.

Returns:
A value SValue if the data was successfully fetched, else B_UNDEFINED_VALUE. If the data is truncated, this will contain only the truncated data and outError will be set to B_DATA_TRUNCATED.
This is exactly like FetchValue(), except in the case where the data to be read is larger than maxSize. In that case here, we will still read the data, but only maxSize bytes of it, and outError will be set to B_DATA_TRUNCATED.

SValue FetchValue ( size_t maxSize,

status_t * outError = NULL

) const

Retrieve the entire data associated with this value.

Parameters:

[in] maxSize Maximum number of bytes to read from the datum if using IDatum::Open(); if it is larger, the fetch will fail with B_OUT_OF_RANGE.

[out] outError Optional error code output in the case when B_UNDEFINED_VALUE is returned.

Returns:
A value SValue if the data was successfully fetched, else B_UNDEFINED_VALUE.
If this is a raw blob of data in an SValue, that is returned directly. Otherwise, if IDatum::Value() succeeds, that value is returned. Otherwise, we try to read the data by opening the datum and streaming in the bytes.
If, in case of reading the data, IDatum::Size() is larger than maxSize, B_UNDEFINED_VALUE is returned and outError is set to B_OUT_OF_RANGE. Otherwise the data is read in. The function may return an undefined value if some other error occurs while reading, such as running out of memory, in which case outError is set to the appropriate error code.

sptr< IByteInput > OpenInput ( uint32_t mode = IDatum::READ_ONLY,

status_t * outError = NULL

) const

Open datum for reading.

Parameters:

[in] mode Desired IDatum open modes.

[out] outError Status code from IDatum::Open(), B_OK on success.

Returns:
The input stream ready for you to read from. If NULL, outError will be set to an error code.
This is a wrapper for calling IDatum::Open() to read, specifically returning an IByteInput stream to you. You can use interface_cast<T> to also retrieve the IByteSeekable interface.

Note:
This only succeeds if working with an IDatum object -- if this is a simple SValue, the open will always fail.

sptr< IByteOutput > OpenOutput ( uint32_t mode,

const sptr< IBinder > & editor,

uint32_t newType,

status_t * outError = NULL

)

Open datum for writing, allowing editor objects and/or type changes.

Parameters:

[in] mode Desired IDatum open modes.

[in] editor Editor object for change notifications as per IDatum::Open().

[in] newType New type code for this datum as per IDatum::Open(). Use 0 to leave the existing type code as-is.

[out] outError Status code from IDatum::Open(), B_OK on success.

Returns:
The output stream ready for you to write to. If NULL, outError will be set to an error code.
This is a wrapper for calling IDatum::Open() to write, specifically returning an IByteOutput stream to you. You can use interface_cast<T> to also retrieve the IByteSeekable or IByteInput interfaces.

Note:
This only succeeds if working with an IDatum object -- if this is a simple SValue, the open will always fail.

sptr< IByteOutput > OpenOutput ( uint32_t mode = IDatum::READ_WRITE|IDatum::ERASE_DATUM,

status_t * outError = NULL

)

Open datum for simple writing.

Parameters:

[in] mode Desired IDatum open modes.

[out] outError Status code from IDatum::Open(), B_OK on success.

Returns:
The output stream ready for you to write to. If NULL, outError will be set to an error code.
This is a wrapper for calling IDatum::Open() to write, specifically returning an IByteOutput stream to you. You can use interface_cast<T> to also retrieve the IByteSeekable or IByteInput interfaces.

Note:
This only succeeds if working with an IDatum object -- if this is a simple SValue, the open will always fail.

bool operator!= ( const SDatum & o ) const

Retrieve the IDatum object being used.

bool operator< ( const SDatum & o ) const

Retrieve the IDatum object being used.

bool operator<= ( const SDatum & o ) const

Retrieve the IDatum object being used.

SDatum & operator= ( const SDatum & o )

Replace this SDatum with o.

bool operator== ( const SDatum & o ) const

Retrieve the IDatum object being used.

bool operator> ( const SDatum & o ) const

Retrieve the IDatum object being used.

bool operator>= ( const SDatum & o ) const

Retrieve the IDatum object being used.

status_t StatusCheck ( ) const

Returns B_OK if we hold a value IDatum or defined SValue.

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


Bookkeeping
Creation, destruction, copying, comparing, etc.
sptr< IDatum >	Datum () const
	Retrieve the IDatum object being used.
bool	operator!= (const SDatum &o) const
	Retrieve the IDatum object being used.
bool	operator< (const SDatum &o) const
	Retrieve the IDatum object being used.
bool	operator<= (const SDatum &o) const
	Retrieve the IDatum object being used.
SDatum &	operator= (const SDatum &o)
	Replace this SDatum with o.
bool	operator== (const SDatum &o) const
	Retrieve the IDatum object being used.
bool	operator> (const SDatum &o) const
	Retrieve the IDatum object being used.
bool	operator>= (const SDatum &o) const
	Retrieve the IDatum object being used.
	SDatum (const SDatum &datum)
	Copy from another SDatum.
	SDatum (const sptr< IDatum > &datum)
	Initialize directly from an IDatum.
	SDatum (const sptr< IBinder > &binder)
	Retrieve a datum from an IBinder, casting to an IDatum interface.
	SDatum (const SValue &value)
	Retrieve a datum from a generic SValue.
	SDatum ()
	Create a new, empty datum.
status_t	StatusCheck () const
	Returns B_OK if we hold a value IDatum or defined SValue.
	~SDatum ()
	Release reference on IDatum.
Datum Operations
Convenience functions for working with IDatum.
SValue	FetchTruncatedValue (size_t maxSize, status_t *outError=NULL) const
	Retrieve data, possibly truncated, associated with this value.
SValue	FetchValue (size_t maxSize, status_t *outError=NULL) const
	Retrieve the entire data associated with this value.
sptr< IByteInput >	OpenInput (uint32_t mode=IDatum::READ_ONLY, status_t *outError=NULL) const
	Open datum for reading.
sptr< IByteOutput >	OpenOutput (uint32_t mode, const sptr< IBinder > &editor, uint32_t newType, status_t *outError=NULL)
	Open datum for writing, allowing editor objects and/or type changes.
sptr< IByteOutput >	OpenOutput (uint32_t mode=IDatum::READ_WRITE\|IDatum::ERASE_DATUM, status_t *outError=NULL)
	Open datum for simple writing.

SDatum Class Reference [Data Model]

Detailed Description

Bookkeeping

Datum Operations

Constructor & Destructor Documentation

Member Function Documentation

SDatum Class Reference
[Data Model]