IDatum Class Reference
[Data Model]

#include <support/IDatum.h>

Inheritance diagram for IDatum:

IInterface SAtom BnDatum BGenericDatum BStreamDatum SDatumLord::Datum BValueDatum SDatumGeneratorInt::IndexedDatum List of all members.

Detailed Description

Interface to a single piece of data, such as a file.

An IDatum represents a single, indivisible piece of data in the Binder Data Model. Clients will usually use the SDatum convenience class instead of making direct calls on an IDatum. Implementations should never directly implement IDatum, instead deriving from BGenericDatum or one of its subclasses.

The IDatum API is designed to enable two approaches to accessing data. The first maps directly to a traditional file, where you perform an "open" operation to retrieve one or more interfaces (of IStorage, IByteInput, IByteOutput, IByteSeekable) that read and/or write a raw stream of bytes. You can also view it as a container for a single piece of data, in which case you retrieve and write it as a single SValue object type.

In general you will always be able to Open() the contents of a datum, but there will be many times when you can't retrieve it directly as an SValue. For example, if the datum is more than 4KB, it will exceed the current IPC data size limit.

The value of a datum should never contain a Binder object. If you want to place a Binder object at a location in the namespace, it can be put there directly without wrapping it in a datum. The role of the datum is really to provide a Binder object for data that otherwise is not itself an object.

The CopyTo() and CopyFrom() methods allow the datum to implement optimized opying paths. The BGenericDatum base class implements both of these by either manually copying the data (reading from the source and writing to the destination) if NO_COPY_REDIRECTION is set, or calling the matching version on the other datum with NO_COPY_REDIRECTION. Subclasses can implement specialized versions of these functions in cases where they can perform copies between datums more efficiently.


Public Types

enum  {
  READ_ONLY = 0x0000, WRITE_ONLY = 0x0001, READ_WRITE = 0x0002, READ_WRITE_MASK = 0x0003,
  ERASE_DATUM = 0x0200, OPEN_AT_END = 0x0400
}
enum  { NO_COPY_REDIRECTION = 0x0001 }

Public Member Functions

virtual status_t CopyFrom (const sptr< IDatum > &src, uint32_t flags=0)=0
 Read src in to this datum.
virtual status_t CopyTo (const sptr< IDatum > &dest, uint32_t flags=0)=0
 Write this datum in to dest.
status_t LinkDatum (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)
virtual sptr< IBinder > Open (uint32_t mode, const sptr< IBinder > &editor=NULL, uint32_t newType=0)=0
 Access data as stream/storage.
virtual void SetSize (off_t value)=0
 Number of bytes in datum.
virtual void SetValue (const SValue &value)=0
 Access datum as an SValue.
virtual void SetValueType (uint32_t value)=0
 Current type code of this datum. Default is B_RAW_TYPE.
virtual off_t Size () const =0
 Number of bytes in datum.
status_t UnlinkDatum (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)
virtual SValue Value () const =0
 Access datum as an SValue.
virtual uint32_t ValueType () const =0
 Current type code of this datum. Default is B_RAW_TYPE.

Protected Member Functions

 IDatum ()
virtual ~IDatum ()

Member Enumeration Documentation

anonymous enum
 

Enumerator:
READ_ONLY  Retrieve a read-only stream from Open().
WRITE_ONLY  Retrive a write-only stream from Open().
READ_WRITE  Retrive a read/write stream from Open().
READ_WRITE_MASK  Bits for Open() flags to control read/write access.
ERASE_DATUM  Use with Open() to get an empty stream.
OPEN_AT_END  Use with Open() for the stream position to start at the end.

anonymous enum
 

Enumerator:
NO_COPY_REDIRECTION  Used with CopyTo() and CopyFrom() to prevent one from calling the other.

You will not normally use this flag yourself. Instead, implementations of IDatum will use it when redirecting between their CopyTo() and CopyFrom() implementation, to prevent recursion from happening. When this flag is set, the CopyTo() or CopyFrom() implementation being called must do the copy itself.

Constructor & Destructor Documentation

IDatum (   )  [inline, protected]
 

virtual ~IDatum (   )  [protected, virtual]
 

Member Function Documentation

virtual status_t CopyFrom (  const sptr< IDatum > &  src,
uint32_t  flags = 0
)  [pure virtual]
 

Read src in to this datum.

Upon a succeessful return, this datum will hold the same data as src. The implementation may accomplish this by calling CopyTo() on src, unless the NO_COPY_REDIRECTION flag is set.

Implemented in BGenericDatum.

virtual status_t CopyTo (  const sptr< IDatum > &  dest,
uint32_t  flags = 0
)  [pure virtual]
 

Write this datum in to dest.

Upon a succeessful return, dest will contain the same data as the source datum. The implementation may accomplish this by calling CopyFrom() on dest, unless the NO_COPY_REDIRECTION flag is set.

Implemented in BGenericDatum.

status_t LinkDatum (  const sptr< IBinder > &  to,
const SValue &  mappings,
uint32_t  flags = 0
)  [inline]
 

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

Access data as stream/storage.

Parameters:
[in] mode The desired open mode: READ_ONLY, WRITE_ONLY, READ_WRITE, ERASE_DATUM, OPEN_AT_END.
[in] editor An optional IBinder object providing the identity of modifications made through this Open() call. Will be propagated through DatumChanged so that you can identify changes due to your own modifications.
[in] newType Optional new type code for the datum. If 0 (the default), the current type will remain unchanged.
Returns:
A new object through which you can manipulate the data inside of the IDatum. Use interface_cast<T> to retrieve the IByteInput, IByteOutput, IByteSeekable, and IStorage interfaces as desired. Returns NULL if there was an error.
Todo:
Add status_t output to retrieve error codes.

Implemented in BStreamDatum, and SDatumLord::Datum.

virtual void SetSize (  off_t  value  )  [pure virtual]
 

Number of bytes in datum.

Implemented in BStreamDatum, and SDatumLord::Datum.

virtual void SetValue (  const SValue &  value  )  [pure virtual]
 

Access datum as an SValue.

You can link to this for notifications when the datum changes. If the datum can not be represented as a value, the value here is "undefined" OR an error value, and it is not pushed when the datum changes. To ensure you always get notified when it changes, you should use the DatumChanged event.

Implemented in BStreamDatum, and SDatumLord::Datum.

virtual void SetValueType (  uint32_t  value  )  [pure virtual]
 

Current type code of this datum. Default is B_RAW_TYPE.

Implemented in BStreamDatum, and SDatumLord::Datum.

virtual off_t Size (   )  const [pure virtual]
 

Number of bytes in datum.

Implemented in BStreamDatum, and SDatumLord::Datum.

status_t UnlinkDatum (  const sptr< IBinder > &  to,
const SValue &  mappings,
uint32_t  flags = 0
)  [inline]
 

virtual SValue Value (   )  const [pure virtual]
 

Access datum as an SValue.

You can link to this for notifications when the datum changes. If the datum can not be represented as a value, the value here is "undefined" OR an error value, and it is not pushed when the datum changes. To ensure you always get notified when it changes, you should use the DatumChanged event.

Implemented in BStreamDatum, and SDatumLord::Datum.

virtual uint32_t ValueType (   )  const [pure virtual]
 

Current type code of this datum. Default is B_RAW_TYPE.

Implemented in BStreamDatum, and SDatumLord::Datum.

The documentation for this class was generated from the following file:
Generated on Wed Dec 28 22:33:31 2005 by Doxygen 1.4.4 for OpenBinder Documentation Version 1.0

PalmSource, Inc. © 2005