BCatalog Class Reference
[Data Model]

#include <support/Catalog.h>

Inheritance diagram for BCatalog:

BMetaDataCatalog SDatumGeneratorInt BIndexedCatalog SAtom BnCatalog BMetaDataNode BIndexedIterable ICatalog BBinder BGenericNode BGenericIterable IInterface IBinder BnNode BnIterable SSQLBuilder SAtom SAtom INode BBinder IIterable BBinder IInterface IBinder IInterface IBinder SAtom SAtom SAtom SAtom BPackageManager List of all members.

Public Member Functions

virtual status_t AddEntry (const SString &name, const SValue &entry)
virtual ssize_t AddEntryLocked (const SString &name, const SValue &entry, sptr< IBinder > *outEntry, bool *replaced)
 BCatalog (const SContext &context)
 BCatalog ()
virtual size_t CountEntriesLocked () const
 Return the number of entries in this catalog.
virtual sptr< IDatumCreateDatum (SString *name, uint32_t flags, status_t *err)
 Create a new IDatum object inside of this catalog.
virtual sptr< INodeCreateNode (SString *name, status_t *err)
 Create a new INode in this catalog.
virtual status_t EntryAtLocked (size_t index, uint32_t flags, SValue *key, SValue *entry)
 Return the entry at the given index.
virtual void InitAtom ()
 Called the first time a strong reference is acquired. All significant object initialization should go here.
virtual lock_status_t Lock () const
 Tie together the locks.
virtual status_t LookupEntry (const SString &entry, uint32_t flags, SValue *node)
 Lookup an entry 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)
virtual status_t StoreValueAtLocked (size_t index, const SValue &value)
 Change a value in the catalog.
virtual void Unlock () const
 Unlock the datum's state.
virtual SValue ValueAtLocked (size_t index) const
 Return the current value in the catalog.

Protected Member Functions

virtual sptr< INodeInstantiateNodeLocked (const SString &name, status_t *err)
 You can override this to create something other than a BCatalog.
virtual void OnEntryCreated (const SString &name, const sptr< IBinder > &entry)
 these are hook functions that get called when things happen
virtual void OnEntryModified (const SString &name, const sptr< IBinder > &entry)
virtual void OnEntryRemoved (const SString &name)
virtual void OnEntryRenamed (const SString &old_name, const SString &new_name, const sptr< IBinder > &entry)
virtual ~BCatalog ()

Constructor & Destructor Documentation

BCatalog  ) 
 

BCatalog const SContext context  ) 
 

~BCatalog  )  [protected, virtual]
 


Member Function Documentation

status_t AddEntry const SString name,
const SValue entry
[virtual]
 

Todo:
Fix this by hooking in to ReportChangeAtLocked()!!!

Implements ICatalog.

ssize_t AddEntryLocked const SString name,
const SValue entry,
sptr< IBinder > *  outEntry,
bool *  replaced
[virtual]
 

size_t CountEntriesLocked  )  const [virtual]
 

Return the number of entries in this catalog.

Implements BIndexedIterable.

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.

Reimplemented from BIndexedCatalog.

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.

Reimplemented from BIndexedCatalog.

status_t EntryAtLocked size_t  index,
uint32_t  flags,
SValue key,
SValue entry
[virtual]
 

Return the entry at the given index.

Implements BIndexedCatalog.

void InitAtom  )  [virtual]
 

Called the first time a strong reference is acquired. All significant object initialization should go here.

You can override it and do any setup you need. Note that you do not need to call the SAtom implementation. (So you can derive from two different SAtom implementations and safely call down to both of their IncStrong() methods.)

See also:
IncStrong()

Reimplemented from SAtom.

Reimplemented in BPackageManager.

sptr< INode > InstantiateNodeLocked const SString name,
status_t err
[protected, virtual]
 

You can override this to create something other than a BCatalog.

lock_status_t Lock  )  const [virtual]
 

Tie together the locks.

Reimplemented from SDatumGeneratorInt.

status_t LookupEntry const SString entry,
uint32_t  flags,
SValue node
[virtual]
 

Lookup an entry in this catalog.

Implements BGenericNode.

void OnEntryCreated const SString name,
const sptr< IBinder > &  entry
[protected, virtual]
 

these are hook functions that get called when things happen

void OnEntryModified const SString name,
const sptr< IBinder > &  entry
[protected, virtual]
 

void OnEntryRemoved const SString name  )  [protected, virtual]
 

void OnEntryRenamed const SString old_name,
const SString new_name,
const sptr< IBinder > &  entry
[protected, virtual]
 

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 old_name,
const SString new_name
[virtual]
 

Todo:
Need to keep the same IDatum object.
Todo:
Fix to only get the entry object if linked!!!

Implements ICatalog.

status_t StoreValueAtLocked size_t  index,
const SValue value
[virtual]
 

Change a value in the catalog.

Implements SDatumGeneratorInt.

void Unlock  )  const [virtual]
 

Unlock the datum's state.

Reimplemented from SDatumGeneratorInt.

SValue ValueAtLocked size_t  index  )  const [virtual]
 

Return the current value in the catalog.

Implements SDatumGeneratorInt.


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