v1.1.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Modules Pages
Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
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: