Sifteo::StoredObject Class Reference

A lightweight ID for a persistently stored object. More...

#include <sifteo/filesystem.h>

Public Member Functions
int	erase () const
	Erase this object. Equivalent to a zero-length write()
	operator const _SYSObjectKey () const
	Implicit conversion to system object.
bool	operator!= (_SYSObjectKey other) const
	Inequality comparison operator.
bool	operator== (_SYSObjectKey other) const
	Equality comparison operator.
int	read (void *buffer, unsigned bufferSize, _SYSVolumeHandle volume=0) const
	Read a stored object into memory. More...
template<typename T >
int	read (T &buffer, _SYSVolumeHandle volume=0) const
	Template wrapper for read() of fixed-size objects. More...
template<typename T >
int	readObject (T &buffer, _SYSVolumeHandle volume=0) const
	Template wrapper for read() of fixed-size objects.
	StoredObject (_SYSObjectKey k)
	Initialize from a system object.
	StoredObject (int k)
	Initialize from an integer.
	StoredObject (unsigned k)
	Initialize from an unsigned integer.
int	write (const void *data, unsigned dataSize) const
	Save a new version of an object. More...
template<typename T >
int	write (const T &buffer) const
	Template wrapper for write() of fixed-size objects. More...
template<typename T >
int	writeObject (const T &buffer) const
	Template wrapper for write() of fixed-size objects.

Static Public Member Functions
static StoredObject	allocate ()
	Allocate a unique StoredObject value at compile-time. More...

Static Public Attributes
static const unsigned	LIMIT = _SYS_FS_MAX_OBJECT_KEYS - 1
	Maximum allowed value for a key (255)
static const unsigned	MAX_SIZE = _SYS_FS_MAX_OBJECT_SIZE
	Maximum size of an object, in bytes (4080)

Detailed Description

A lightweight ID for a persistently stored object.

Games may read and write such objects stored in a key-value dictionary associated with their volume. The key space is limited. Valid keys range from 0 to LIMIT. These keys may be allocated manually or automatically.

If you're computing keys dynamically, cast your key to a StoredObject in order to access the object data at that key. If you're allocating keys statically, you can create global StoredObject instances which act as a single place to associate IDs with names.

By default, objects are both read from and written to a store associated with the current game's Volume. It is possible to read another game's stored data (by specifying its Volume) but you may not write to another game's object store.

Objects are stored in a journaled filesystem, and writes are synchronous. By design, if power fails or the system is otherwise interrupted during a write, future reads will continue to return the last successfully-written version of an object.

Object sizes must be at least one byte, and no more than MAX_SIZE bytes.

Member Function Documentation

static StoredObject Sifteo::StoredObject::allocate ( )

inlinestatic

Allocate a unique StoredObject value at compile-time.

Every time this function is invoked, it is resolved by the linker to a unique StoredObject. We start allocating at LIMIT, and each successive call to allocate() returns a value decremented by one.

This allocation order supports a strategy in which manually-assigned or calculated IDs begin at 0 and count up, and automatically allocated IDs begin at LIMIT and count down.

int Sifteo::StoredObject::read ( void *  buffer, unsigned  bufferSize, _SYSVolumeHandle  volume = 0  ) const

inline

Read a stored object into memory.

Reads into the provided buffer. Returns the actual number of bytes read, which on success always equals either the size of the stored data for this object or the size of the provided buffer, whichever is smaller.

The provided 'bufferSize' must be large enough to hold the entire stored object, excepting only any trailing 0xFF bytes. It is not, in general, possible to perform partial reads of a stored object.

If no data has been stored for this object yet, returns zero. Note that the object store does not distinguish between zero-length values and missing values.

By default, this reads from the object store associated with the current game. The optional 'volume' parameter can be set to a specific Sifteo::Volume instance in order to read objects from a different game's data store.

Returns

size of the data retrieved, or < 0 on failure. The following results indicate a specific failure mode:

• _SYS_ENOENT - No such object found
• _SYS_EFAULT - Bad address
• _SYS_EINVAL - Invalid argument
• _SYS_ENOSPC - No space left on device

template<typename T >

int Sifteo::StoredObject::read ( T &  buffer, _SYSVolumeHandle  volume = 0  ) const

inline

Template wrapper for read() of fixed-size objects.

Deprecated:

Use readObject() instead. This will be removed in a future version update.

int Sifteo::StoredObject::write ( const void *  data, unsigned  dataSize  ) const

inline

Save a new version of an object.

Replace this object's contents with a new block of data. On success, always returns the number of bytes written, which is always equal to dataSize.

The data block will be padded to the next multiple of 16 bytes.

Writing an empty data block is equivalent to erasing the stored object.

If power fails during a write, by design subsequent reads will return the last successfully-saved version of that object.

Returns

size of the data written, or < 0 on failure. The following results indicate a specific failure mode:

• _SYS_ENOENT - No such object found
• _SYS_EFAULT - Bad address
• _SYS_EINVAL - Invalid argument
• _SYS_ENOSPC - No space left on device

template<typename T >

int Sifteo::StoredObject::write ( const T &  buffer ) const

inline

Template wrapper for write() of fixed-size objects.

Deprecated:

Use writeObject() instead. This will be removed in a future version update.

---

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

• filesystem.h