Starboard Module Reference: storage.h

Defines a user-based Storage API. This is a simple, all-at-once BLOB storage and retrieval API that is intended for robust long-term, per-user storage. Some platforms have different mechanisms for this kind of storage, so this API exists to allow a client application to access this kind of storage.
Note that there can be only one storage record per user and, thus, a maximum of one open storage record can exist for each user. Attempting to open a second record for a user will result in undefined behavior.
These APIs are NOT expected to be thread-safe, so either call them from a single thread, or perform proper synchronization around all calls.

Structs

SbStorageRecordPrivate

Private structure representing a single storage record.

Functions

SbStorageCloseRecord

Description

Closes record, synchronously ensuring that all written data is flushed. This function performs blocking I/O on the calling thread.
The return value indicates whether the operation succeeded. Storage writes should be as atomic as possible, so the record should either be fully written or deleted (or, even better, untouched).

Declaration and definitions

SB_EXPORT bool SbStorageCloseRecord(SbStorageRecord record);

#include "starboard/storage.h"

bool SbStorageCloseRecord(SbStorageRecord /*record*/) {
  return false;
}

Parameters

Parameters
SbStorageRecord
record
The storage record to close. record is invalid after this point, and subsequent calls referring to record will fail.

SbStorageDeleteRecord

Description

Deletes the SbStorageRecord for the specified user. The return value indicates whether the record existed and was successfully deleted. If the record did not exist or could not be deleted, the function returns false.
This function must not be called while the user's storage record is open. This function performs blocking I/O on the calling thread.

Declaration and definitions

SB_EXPORT bool SbStorageDeleteRecord(SbUser user);

#include "starboard/storage.h"

bool SbStorageDeleteRecord(SbUser /*user*/) {
  return false;
}

Parameters

Parameters
SbUser
user
The user for whom the record is deleted.

SbStorageGetRecordSize

Description

Returns the size of record, or -1 if there is an error. This function performs blocking I/O on the calling thread.

Declaration and definitions

SB_EXPORT int64_t SbStorageGetRecordSize(SbStorageRecord record);

#include "starboard/storage.h"

int64_t SbStorageGetRecordSize(SbStorageRecord /*record*/) {
  return -1;
}

Parameters

Parameters
SbStorageRecord
record
The record to retrieve the size of.

SbStorageIsValidRecord

Description

Returns whether the given storage record handle is valid.

Declaration

static SB_C_INLINE bool SbStorageIsValidRecord(SbStorageRecord record) {
  return record != kSbStorageInvalidRecord;
}

Parameters

Parameters
SbStorageRecord
record

SbStorageOpenRecord

Description

Opens and returns a SbStorageRecord for user, blocking I/O on the calling thread until it returns. If user is not a valid SbUser, the function returns kSbStorageInvalidRecord.

Declaration and definitions

SB_EXPORT SbStorageRecord SbStorageOpenRecord(SbUser user);

#include "starboard/storage.h"

SbStorageRecord SbStorageOpenRecord(SbUser /*user*/) {
  return kSbStorageInvalidRecord;
}

Parameters

Parameters
SbUser
user
The user for which the storage record is opened.

SbStorageReadRecord

Description

Reads up to data_size bytes from record, starting at the beginning of the record. The function returns the actual number of bytes read, which must be <= data_size. The function returns -1 in the event of an error. This function makes a best-effort to read the entire record, and it performs blocking I/O on the calling thread until the entire record is read or an error is encountered.

Declaration and definitions

SB_EXPORT int64_t SbStorageReadRecord(SbStorageRecord record,
                                      char* out_data,
                                      int64_t data_size);

#include "starboard/storage.h"

int64_t SbStorageReadRecord(SbStorageRecord /*record*/,
                            char* /*out_data*/,
                            int64_t /*data_size*/) {
  return -1;
}

Parameters

Parameters
SbStorageRecord
record
The record to be read.
char*
out_data
The data read from the record.
int64_t
data_size
The amount of data, in bytes, to read.

SbStorageWriteRecord

Description

Replaces the data in record with data_size bytes from data. This function always deletes any previous data in that record. The return value indicates whether the write succeeded. This function makes a best-effort to read the entire record, and it performs performs blocking I/O on the calling thread until the entire record is read or an error is encountered.

Declaration and definitions

SB_EXPORT bool SbStorageWriteRecord(SbStorageRecord record,
                                    const char* data,
                                    int64_t data_size);

#include "starboard/storage.h"

bool SbStorageWriteRecord(SbStorageRecord /*record*/,
                          const char* /*data*/,
                          int64_t /*data_size*/) {
  return false;
}

Parameters

Parameters
SbStorageRecord
record
The record to be written to.
const char*
data
The data to write to the record.
int64_t
data_size
The amount of data, in bytes, to write to the record. Thus, if data_size is smaller than the total size of data, only part of data is written to the record.