ITable Class Reference
[Data Model]

#include <support/ITable.h>

Inheritance diagram for ITable:

Detailed Description

Extended interface to an IIterable holding a 2d data structure.

The ITable interface provides special extended operations for IIterable objects Binder Data Model that are holding two-dimensional data such as an array of structures.

An object that implements ITable will always implement IIterable -- ITable is essentially another way to manipulate data that you would normally retrieve through queries on an IIterable. These objects will also usually implement INode and ICatalog, though they may not do so if the table rows do not have names (as is the case with a raw database table). They may also implement more specialized interfaces such as IMenuData.

An ITable can generally be thought of as a database table, where all rows in the table has a fixed number of columns that are defined by that table. Such a structure is used extensively, for example, to provide data to an IListView, which is the facility for displaying such two-dimensional data structures. Note, however, that IListView itself only needs an IIterable for accessing that data -- the ITable provides additional or more optimal features beyond the basic IIterable facilities, for manipulating and monitoring the data in a table. Some ITable objects also allow you to add and remove columns from the table.

Todo:: I think it would be cleaner to get rid of the CreateRow() and RemoveNode() APIs, putting that functionality on ICatalog so it continues to be your one-stop-shopping for manipulating entries. This interface then is just very specific table operation -- monitoring table changes, and finding and manipulating columns.

Public Types

enum { CHANGE_DETAILS_SENT = 0x0001 }

Flags for ITable::TableChanged event. More...

Public Member Functions

virtual status_t AddColumn (const SString &name, uint32_t typeCode, size_t maxSize, uint32_t flags, const SValue &extras)=0

Add a new column to the table.

virtual SValue ColumnNames () const =0

Return set of column names.

virtual status_t CreateRow (SString *name, const SValue &columns, uint32_t flags=0, sptr< INode > *createdRow=NULL)=0

Create a new row in the table.

status_t LinkTable (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)

virtual status_t RemoveColumn (const SString &name)=0

Remove an existing column from the table.

virtual status_t RemoveRow (const sptr< INode > &row)=0

Remove an existing row from the table.

virtual SValue Schema () const =0

Return all information about columns.

status_t UnlinkTable (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)

Protected Member Functions

ITable ()

virtual ~ITable ()

Member Enumeration Documentation

anonymous enum

Flags for ITable::TableChanged event.

Enumerator:

CHANGE_DETAILS_SENT Used in ITable::TableChanged when a detailed event was also sent.
You can use this flag to determine if the table has also pushed one of the most detailed change events. If it is not sent, then this is the ONLY change notifications you will get, and you can't make any more assumptions about the contents of the table. If it is set and you have linked to the other change events, you can safely ignore this event.

Constructor & Destructor Documentation

ITable ( ) [inline, protected]

virtual ~ITable ( ) [protected, virtual]

Member Function Documentation

virtual status_t AddColumn ( const SString & name,

uint32_t typeCode,

size_t maxSize,

uint32_t flags,

const SValue & extras

) [pure virtual]

Add a new column to the table.

Parameters:

[in] name Name of the new column. Must be unique.

[in] typeCode Data type of the new column, such as B_INT32_TYPE.

[in] maxSize For data types that are variable length (such as B_STRING_TYPE), this is the maximum amount of data it can contain. For fixed-length types, this is ignored, or the table may simply ignore it completely and not impose a size limit.

[in] flags Additional information about the column.

[in] extras For future extension.

Returns:
B_OK if the column was successfully added, B_NAME_IN_USE if there is already a column with this name, etc.
Some tables are dynamic, allow you to add and/or remove columns. If supported, this API lets you create a new column in the table.
Implemented in BSchemaTableNode, and BIndexedTableNode.

virtual SValue ColumnNames ( ) const [pure virtual]

Return set of column names.

Todo:
Should be replaced with an IIterable interface.

Implemented in BSchemaTableNode, and BIndexedTableNode.

virtual status_t CreateRow ( SString * name,

const SValue & columns,

uint32_t flags = 0,

sptr< INode > * createdRow = NULL

) [pure virtual]

Create a new row in the table.

Parameters:

[in,out] name Incoming, the desired name for the new row. Outgoing, the actual name that was used. Some table may completely ignore your desired name and use their own. Alternatively, a table may use your name as-is, and return an error if an entry with that name already exists. A table may even not have names at all, in which case the name will be returned with the value "".

[in] columns Any initial values you would like for the columns in this row. This is a set of mappings, where the key is the name of the column and the value is the data to place in the row for that column.

[in] flags Additional control flags. None currently defined.

[out] createdRow Optional output of the INode object representing the new row.

Returns:
B_OK on success, else an appropriate error code.

Todo:
This should probably be removed from this interface, and the ICatalog::CreateNode() API extended to have all of this functionality.

Implemented in BSchemaTableNode, and BIndexedTableNode.

status_t LinkTable ( const sptr< IBinder > & to,

const SValue & mappings,

uint32_t flags = 0

) [inline]

virtual status_t RemoveColumn ( const SString & name ) [pure virtual]

Remove an existing column from the table.

Parameters:

[in] name Name of the column to be removed.

Returns:
B_OK if the column was successfully added, B_NAME_NOT_FOUND if there is no column with the given name, etc.
Some tables are dynamic, allow you to add and/or remove columns. If supported, this API lets you remove columns from the table.
Implemented in BSchemaTableNode, and BIndexedTableNode.

virtual status_t RemoveRow ( const sptr< INode > & row ) [pure virtual]

Remove an existing row from the table.

Parameters:

[in] row The row to be removed.

Returns:
B_OK if the entry was removed, some other error code on error. In particular, B_ENTRY_NOT_FOUND if the given INode does not map to a row in the table.
This is like ICatalog::RemoveEntry(), but allows you to identify the row to be removed through its INode object. This allows it to work with tables that do not have names for their rows -- that is, a table that is only an IIterable.

Todo:
This should probably be removed from this interface, and put on ICatalog.

Implemented in BSchemaTableNode, and BIndexedTableNode.

virtual SValue Schema ( ) const [pure virtual]

Return all information about columns.

Todo:
Should be replaced with an IIterable interface.

Implemented in BSchemaTableNode, and BIndexedTableNode.

status_t UnlinkTable ( const sptr< IBinder > & to,

const SValue & mappings,

uint32_t flags = 0

) [inline]

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

ITable.h


Public Types
enum	{ CHANGE_DETAILS_SENT = 0x0001 }
	Flags for ITable::TableChanged event. More...
Public Member Functions
virtual status_t	AddColumn (const SString &name, uint32_t typeCode, size_t maxSize, uint32_t flags, const SValue &extras)=0
	Add a new column to the table.
virtual SValue	ColumnNames () const =0
	Return set of column names.
virtual status_t	CreateRow (SString name, const SValue &columns, uint32_t flags=0, sptr< INode > createdRow=NULL)=0
	Create a new row in the table.
status_t	LinkTable (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)
virtual status_t	RemoveColumn (const SString &name)=0
	Remove an existing column from the table.
virtual status_t	RemoveRow (const sptr< INode > &row)=0
	Remove an existing row from the table.
virtual SValue	Schema () const =0
	Return all information about columns.
status_t	UnlinkTable (const sptr< IBinder > &to, const SValue &mappings, uint32_t flags=0)
Protected Member Functions
	ITable ()
virtual	~ITable ()

ITable Class Reference [Data Model]

Detailed Description

Public Types

Public Member Functions

Protected Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

ITable Class Reference
[Data Model]