Defines the Storage API. This is a simple, all-at-once BLOB storage and
retrieval API intended for robust, long-term storage. Because platforms use
different storage mechanisms, this API provides a consistent interface for
client applications.

Only one storage record can exist; therefore, you can open at most one storage
record at a time. Attempting to open a second record results in undefined
behavior.

These APIs are not thread-safe. Call them from a single thread, or use proper
synchronization.

## Macros

### kSbStorageInvalidRecord

Well-defined value for an invalid storage record handle.

## Typedefs

### SbStorageRecord

A handle to an open storage record.

#### Definition

    typedef SbStorageRecordPrivate* SbStorageRecord

## Functions

### SbStorageCloseRecord

Closes `record`, synchronously ensuring that all written data is flushed. This
function performs blocking I/O on the calling thread.

Returns whether the operation succeeded. Storage writes should be atomic; the
record should either be fully written or remain unchanged.

- `record`: The storage record to close. The handle becomes invalid, and subsequent calls using it will fail.

#### Declaration

    bool SbStorageCloseRecord(SbStorageRecord record)

### SbStorageDeleteRecord

Deletes the `SbStorageRecord` specified by `name`. Returns `true` if the record
existed and was successfully deleted; otherwise, returns `false`.

If `name` is `NULL`, this function deletes the default storage record (matching
the behavior of previous API versions).

Do not call this function while the storage record is open. This function
performs blocking I/O on the calling thread.

- `name`: The filesystem-safe name of the record to open.

#### Declaration

    bool SbStorageDeleteRecord(const char *name)

### SbStorageGetRecordSize

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

- `record`: The record to retrieve the size of.

#### Declaration

    int64_t SbStorageGetRecordSize(SbStorageRecord record)

### SbStorageIsValidRecord

Returns whether the given storage record handle is valid.

#### Declaration

    static bool SbStorageIsValidRecord(SbStorageRecord record)

### SbStorageOpenRecord

Opens and returns the `SbStorageRecord` specified by `name`, blocking the
calling thread until the operation completes. Returns an empty `SbStorageRecord`
(size zero) if the record does not exist. Opening an already-open
`SbStorageRecord` results in undefined behavior.

If `name` is `NULL`, opens the default storage record (matching the behavior of
previous API versions).

- `name`: The filesystem-safe name of the record to open.

#### Declaration

    SbStorageRecord SbStorageOpenRecord(const char *name)

### SbStorageReadRecord

Reads up to `data_size` bytes from `record`, starting at the beginning of the
record. Returns the actual number of bytes read (which is less than or equal to
`data_size`), or `-1` on error. This function makes a best-effort to read the
entire record, blocking the calling thread until the operation completes or
fails.

- `record`: The record to read.

- `out_data`: The destination buffer for the read data.

- `data_size`: The number of bytes to read.

#### Declaration

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

### SbStorageWriteRecord

Replaces the data in `record` with `data_size` bytes from `data`, deleting any
previous data. Returns whether the write succeeded. This function makes a
best-effort to write the entire record, and may perform blocking I/O on the
calling thread.

Although `SbStorageWriteRecord()` may defer persistence, a subsequent
`SbStorageReadRecord()` call must immediately reflect the write, even without
calling `SbStorageCloseRecord()`. Data should persist shortly after writing,
even in the event of unexpected process termination.

- `record`: The record to write.

- `data`: The data to write.

- `data_size`: The number of bytes to write.

#### Declaration

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