BCatalogDelegate Class Reference
[Data Model]

#include <storage/CatalogDelegate.h>

Inheritance diagram for BCatalogDelegate:

Detailed Description

Provides base implementation of delegations for INode/IIterable/ICatalog.

Given an existing object that implements one or more of the INode, IIterable, and ICatalog interfaces, provides a new object that delegates to the existing implementation. This gives you a base class from which you can implement modifications to the data supplied by existing data objects.

Note:: This class only delegates the given base object. It will not create a wrapper for any objects retrieved from it, such as IDatums or other INodes.

ICatalog

Delegation to ICatalog interface.

virtual status_t AddEntry (const SString &name, const SValue &entry)

Add or modify an entry in the catalog.

sptr< ICatalog > BaseCatalog () const

Returns original ICatalog object, or NULL if that interface was not available.

virtual sptr< IDatum > CreateDatum (SString *name, uint32_t flags, status_t *err)

Create a new IDatum object inside of this catalog.

virtual sptr< INode > CreateNode (SString *name, status_t *err)

Create a new INode in this catalog.

virtual status_t RemoveEntry (const SString &name)

Remove an existing entry from the catalog.

virtual status_t RenameEntry (const SString &entry, const SString &name)

Change the name of an entry in the catalog.

IIterable

Delegation to IIterable interface.

sptr< IIterable > BaseIterable () const

Returns original IIterable object, or NULL if that interface was not available.

virtual sptr< GenericIterator > NewGenericIterator (const SValue &args)

Returns original IIterable object, or NULL if that interface was not available.

Bookkeeping

Creation, destruction, locking, etc.

BCatalogDelegate (const SContext &context, const sptr< IBinder > &base)

SContext Context ()

Disambiguate.

virtual SValue Inspect (const sptr< IBinder > &caller, const SValue &which, uint32_t flags)

Make INode, IIterable, and ICatalog interfaces visible based on delegate.

virtual lock_status_t Lock () const

Disambiguate.

virtual void Unlock () const

Disambiguate.

virtual ~BCatalogDelegate ()

Classes

class IteratorDelegate

Generic base class implementation of a BGenericIterable's iterator. More...

Constructor & Destructor Documentation

BCatalogDelegate ( const SContext & context,

const sptr< IBinder > & base

)

~BCatalogDelegate ( ) [protected, virtual]

Member Function Documentation

status_t AddEntry ( const SString & name,

const SValue & entry

) [virtual]

Add or modify an entry in the catalog.

Parameters:

[in] name Desired name of the entry.

[in] entry Data or object for the entry.

Returns:
B_OK on success, else an error code.
AddEntry() is a general way to place new entries into a catalog. There are two main ways it can be useful. The first is as an equivalent to the INode::REQUEST_DATA hint for reading entries –- if you supply an SValue of data to ddEntry(), it can create a new entry with that data, without requiring an intermediate operation through an IDatum object.
The second reason for using this API is to add new types of objects to the catalog – if the SValue contains an IBinder object, the given object will be directly added as the new entry. This latter approach allows you to create places where the namespace crosses processes, mount new types of directories in the namespace, etc. Note, however, that many catalogs (such as one representing a filesystem) will not be able to host references to external objects.
Contrast this with CreateNode() and CreateDatum(), which creates new entry objects that are owned and managed by the catalog.

Todo:
This API should not allow both creation of new entries and modification of existing entries.

Todo:
This API should work more like CreateDatum(), where the name is an in/out parameter, and it should be able to return the created object as an optional output. Perhaps this functionality should be moved to CreateNode() and CreateDatum(), and this method changed to ReplaceEntry() to only modify an existing entry.

Implements ICatalog.

sptr<ICatalog> BaseCatalog ( ) const [inline]

Returns original ICatalog object, or NULL if that interface was not available.

sptr<IIterable> BaseIterable ( ) const [inline]

Returns original IIterable object, or NULL if that interface was not available.

SContext Context ( ) [inline]

Disambiguate.

Reimplemented from BNodeDelegate.

sptr< IDatum > CreateDatum ( SString * name,

uint32_t flags,

status_t * err

) [virtual]

Create a new IDatum object inside of this catalog.

Parameters:

[in,out] name Incoming, the desired name for the new entry. Outgoing, the actual name that was used. Some catalogs may completely ignore your desired name and use their own. Alternatively, a catalog may use your name as-is, and return an error if an entry with that name already exists.

[in] flags Additional options. Always set to 0.

[out] err B_OK on success, else an error code.

Returns:
The newly created IDatum, or NULL on failure.
This is like CreateNode() (see that API for further details), but creates an object implementing the IDatum interface and thus allowing you to place actual data under this entry.
Note that the returned object may very well support other interfaces (including INode), however its main purpose is to hold data for you.
Implements ICatalog.

sptr< INode > CreateNode ( SString * name,

status_t * err

) [virtual]

Create a new INode in this catalog.

Parameters:

[in,out] name Incoming, the desired name for the new entry. Outgoing, the actual name that was used. Some catalogs may completely ignore your desired name and use their own. Alternatively, a catalog may use your name as-is, and return an error if an entry with that name already exists.

[out] err B_OK on success, else an error code.

Returns:
The newly created INode, or NULL on failure.
Use this API to create a new subdirectory kind of object inside of this catalog. The returned object will be at least an INode that can itself contain one or more child entries. However, the details of how the node INode works are entirely dependent on this containing catalog: it could start out empty and have its own ICatalog interface through which you can add any arbitrary entries, start out with a fixed set of entries that can not be changed, etc.
This, along with CreateDatum(), is the mechanism you should normally use when entries in a particular catalog, because they allow the catalog to ensure that objects with the correct implementation are created. For example, if the catalog is on a filesystem, it will need to modify the filesystem data to hold the new structure and create and return a proxy object for the new entry it just created.
Even in a generic catalog the use of this function is important, since it ensures objects are created in the same process as the parent directory. Consider, for example, an application that wishes to create a node with some data that will stay around after the application itself exits.
Contrast this with AddEntry(), which if called with an IBinder object will place a reference to that object in the catalog.
Implements ICatalog.

SValue Inspect ( const sptr< IBinder > & caller,

const SValue & which,

uint32_t flags

) [virtual]

Make INode, IIterable, and ICatalog interfaces visible based on delegate.
This will allow you to cast to the same interfaces that are supported by the base object, but returning the new delegate implementations.
Reimplemented from BnCatalog.

lock_status_t Lock ( ) const [virtual]

Disambiguate.

Reimplemented from BGenericIterable.

sptr< BGenericIterable::GenericIterator > NewGenericIterator ( const SValue & args ) [virtual]

Returns original IIterable object, or NULL if that interface was not available.

Implements BGenericIterable.

status_t RemoveEntry ( const SString & name ) [virtual]

Remove an existing entry from the catalog.

Parameters:

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

Returns:
B_OK if the entry was removed, some other error code on error. In particular, B_ENTRY_NOT_FOUND if there is not an entry with the given name.

Implements ICatalog.

status_t RenameEntry ( const SString & entry,

const SString & name

) [virtual]

Change the name of an entry in the catalog.

Parameters:

[in] entry Name of the entry to be renamed.

[in] name New name for the entry.

Returns:
B_OK if the entry was removed, some other error code on error. Most common errors are B_ENTRY_NOT_FOUND (entry does not exist), B_ENTRY_EXISTS (there is already an existing entry named name), B_UNSUPPORTED (this catalog does not support renaming).

Implements ICatalog.

void Unlock ( ) const [virtual]

Disambiguate.

Reimplemented from BGenericIterable.

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


ICatalog
Delegation to ICatalog interface.
virtual status_t	AddEntry (const SString &name, const SValue &entry)
	Add or modify an entry in the catalog.
sptr< ICatalog >	BaseCatalog () const
	Returns original ICatalog object, or NULL if that interface was not available.
virtual sptr< IDatum >	CreateDatum (SString name, uint32_t flags, status_t err)
	Create a new IDatum object inside of this catalog.
virtual sptr< INode >	CreateNode (SString name, status_t err)
	Create a new INode in this catalog.
virtual status_t	RemoveEntry (const SString &name)
	Remove an existing entry from the catalog.
virtual status_t	RenameEntry (const SString &entry, const SString &name)
	Change the name of an entry in the catalog.
IIterable
Delegation to IIterable interface.
sptr< IIterable >	BaseIterable () const
	Returns original IIterable object, or NULL if that interface was not available.
virtual sptr< GenericIterator >	NewGenericIterator (const SValue &args)
	Returns original IIterable object, or NULL if that interface was not available.
Bookkeeping
Creation, destruction, locking, etc.
	BCatalogDelegate (const SContext &context, const sptr< IBinder > &base)
SContext	Context ()
	Disambiguate.
virtual SValue	Inspect (const sptr< IBinder > &caller, const SValue &which, uint32_t flags)
	Make INode, IIterable, and ICatalog interfaces visible based on delegate.
virtual lock_status_t	Lock () const
	Disambiguate.
virtual void	Unlock () const
	Disambiguate.
virtual	~BCatalogDelegate ()
Classes
class	IteratorDelegate
	Generic base class implementation of a BGenericIterable's iterator. More...

BCatalogDelegate Class Reference [Data Model]

Detailed Description

ICatalog

IIterable

Bookkeeping

Classes

Constructor & Destructor Documentation

Member Function Documentation

BCatalogDelegate Class Reference
[Data Model]