Starboard Module Reference: system.h

Defines a broad set of APIs that allow the client application to query build and runtime properties of the enclosing system.

Macros

kSbSystemPlatformErrorInvalid

Well-defined value for an invalid SbSystemPlatformError.

Enums

SbSystemCapabilityId

Runtime capabilities are boolean properties of a platform that can't be determined at compile-time. They may vary from device to device, but they will not change over the course of a single execution. They often specify particular behavior of other APIs within the bounds of their operating range.

Values

  • kSbSystemCapabilityReversedEnterAndBack

    Whether this system has reversed Enter and Back keys.

  • kSbSystemCapabilityCanQueryGPUMemoryStats

    Whether this system has the ability to report on GPU memory usage. If (and only if) a system has this capability will SbSystemGetTotalGPUMemory() and SbSystemGetUsedGPUMemory() be valid to call.

  • kSbSystemCapabilitySetsInputTimestamp

    Whether this system sets the timestamp field of SbInputData . If the system does not set this field, then it will automatically be set; however, the relative time between input events likely will not be preserved, so time-related calculations (e.g. velocity for move events) will be incorrect.

SbSystemConnectionType

Enumeration of network connection types.

Values

  • kSbSystemConnectionTypeWired

    The system is on a wired connection.

  • kSbSystemConnectionTypeWireless

    The system is on a wireless connection.

  • kSbSystemConnectionTypeUnknown

    The system connection type is unknown.

SbSystemDeviceType

Enumeration of device types.

Values

  • kSbSystemDeviceTypeBlueRayDiskPlayer

    Blue-ray Disc Player (BDP).

  • kSbSystemDeviceTypeGameConsole

    A relatively high-powered TV device used primarily for playing games.

  • kSbSystemDeviceTypeOverTheTopBox

    Over the top (OTT) devices stream content via the Internet over another type of network, e.g. cable or satellite.

  • kSbSystemDeviceTypeSetTopBox

    Set top boxes (STBs) stream content primarily over cable or satellite. Some STBs can also stream OTT content via the Internet.

  • kSbSystemDeviceTypeTV

    A Smart TV is a TV that can directly run applications that stream OTT content via the Internet.

  • kSbSystemDeviceTypeDesktopPC

    Desktop PC.

  • kSbSystemDeviceTypeAndroidTV

    An Android TV Device.

  • kSbSystemDeviceTypeUnknown

    Unknown device.

SbSystemPathId

Enumeration of special paths that the platform can define.

Values

  • kSbSystemPathContentDirectory

    Path to where the local content files that ship with the binary are available.

  • kSbSystemPathCacheDirectory

    Path to the directory that can be used as a local file cache, if available.

  • kSbSystemPathDebugOutputDirectory

    Path to the directory where debug output (e.g. logs, trace output, screenshots) can be written into.

  • kSbSystemPathFontDirectory

    Path to a directory where system font files can be found. Should only be specified on platforms that provide fonts usable by Starboard applications.

  • kSbSystemPathFontConfigurationDirectory

    Path to a directory where system font configuration metadata can be found. May be the same directory as kSbSystemPathFontDirectory, but not necessarily. Should only be specified on platforms that provide fonts usable by Starboard applications.

  • kSbSystemPathTempDirectory

    Path to a directory where temporary files can be written.

  • kSbSystemPathTestOutputDirectory

    Path to a directory where test results can be written.

  • kSbSystemPathExecutableFile

    Full path to the executable file.

SbSystemPlatformErrorResponse

Possible responses for SbSystemPlatformErrorCallback.

Values

  • kSbSystemPlatformErrorResponsePositive
  • kSbSystemPlatformErrorResponseNegative
  • kSbSystemPlatformErrorResponseCancel

SbSystemPlatformErrorType

Enumeration of possible values for the type parameter passed to the SbSystemRaisePlatformError function.

Values

  • kSbSystemPlatformErrorTypeConnectionError

    Cobalt received a network connection error, or a network disconnection event. If the response passed to SbSystemPlatformErrorCallback is kSbSystemPlatformErrorResponsePositive then the request should be retried, otherwise the app should be stopped.

SbSystemPropertyId

System properties that can be queried for. Many of these are used in User-Agent string generation.

Values

  • kSbSystemPropertyCertificationScope

    The certification scope that identifies a group of devices.

  • kSbSystemPropertyBase64EncodedCertificationSecret

    The HMAC-SHA256 base64 encoded symmetric key used to sign a subset of the query parameters from the application startup URL.

  • kSbSystemPropertyChipsetModelNumber

    The full model number of the main platform chipset, including any vendor- specific prefixes.

  • kSbSystemPropertyFirmwareVersion

    The production firmware version number which the device is currently running.

  • kSbSystemPropertyFriendlyName

    A friendly name for this actual device. It may include user-personalization like "Upstairs Bedroom." It may be displayed to users as part of some kind of device selection (e.g. in-app DIAL).

  • kSbSystemPropertyManufacturerName

    A deprecated alias for kSbSystemPropertyBrandName.

  • kSbSystemPropertyBrandName

    The name of the brand under which the device is being sold.

  • kSbSystemPropertyModelName

    The final production model number of the device.

  • kSbSystemPropertyModelYear

    The year the device was launched, e.g. "2016".

  • kSbSystemPropertyNetworkOperatorName

    The name of the network operator that owns the target device, if applicable.

  • kSbSystemPropertyPlatformName

    The name of the operating system and platform, suitable for inclusion in a User-Agent, say.

  • kSbSystemPropertySpeechApiKey

    The Google Speech API key. The platform manufacturer is responsible for registering a Google Speech API key for their products. In the API Console ( http://developers.google.com/console ), you can enable the Speech APIs and generate a Speech API key.

  • kSbSystemPropertyUserAgentAuxField

    A field that, if available, is appended to the user agent

Typedefs

SbSystemComparator

Pointer to a function to compare two items. The return value uses standard *cmp semantics:

  • < 0 if a is less than b

  • 0 if the two items are equal

  • > 1 if a is greater than b

a: The first value to compare. b: The second value to compare.

Definition

typedef int(* SbSystemComparator) (const void *a, const void *b)

SbSystemError

A type that can represent a system error code across all Starboard platforms.

Definition

typedef int SbSystemError

SbSystemPlatformError

Opaque handle returned by SbSystemRaisePlatformError that can be passed to SbSystemClearPlatformError.

Definition

typedef SbSystemPlatformErrorPrivate* SbSystemPlatformError

SbSystemPlatformErrorCallback

Type of callback function that may be called in response to an error notification from SbSystemRaisePlatformError. response is a code to indicate the user's response, e.g. if the platform raised a dialog to notify the user of the error. user_data is the opaque pointer that was passed to the call to SbSystemRaisePlatformError.

Definition

typedef void(* SbSystemPlatformErrorCallback) (SbSystemPlatformErrorResponse response, void *user_data)

Functions

SbSystemBinarySearch

Binary searches a sorted table base of element_count objects, each element element_width bytes in size for an element that comparator compares equal to key.

This function is meant to be a drop-in replacement for bsearch.

key: The key to search for in the table. base: The sorted table of elements to be searched. element_count: The number of elements in the table. element_width: The size, in bytes, of each element in the table. comparator: A value that indicates how the element in the table should compare to the specified key.

Declaration

void* SbSystemBinarySearch(const void *key, const void *base, size_t element_count, size_t element_width, SbSystemComparator comparator)

SbSystemBreakIntoDebugger

Breaks the current program into the debugger, if a debugger is attached. If a debugger is not attached, this function aborts the program.

Declaration

SB_NORETURN void SbSystemBreakIntoDebugger()

SbSystemClearLastError

Clears the last error set by a Starboard call in the current thread.

Declaration

void SbSystemClearLastError()

SbSystemClearPlatformError

Clears a platform error that was previously raised by a call to SbSystemRaisePlatformError. The platform may use this, for example, to close a dialog that was opened in response to the error.

handle: The platform error to be cleared.

Declaration

void SbSystemClearPlatformError(SbSystemPlatformError handle)

SbSystemGetConnectionType

Returns the device's current network connection type.

Declaration

SbSystemConnectionType SbSystemGetConnectionType()

SbSystemGetDeviceType

Returns the type of the device.

Declaration

SbSystemDeviceType SbSystemGetDeviceType()

SbSystemGetErrorString

Generates a human-readable string for an error. The return value specifies the total desired length of the string.

error: The error for which a human-readable string is generated. out_string: The generated string. This value may be null, and it is always terminated with a null byte. string_length: The maximum length of the error string.

Declaration

int SbSystemGetErrorString(SbSystemError error, char *out_string, int string_length)

SbSystemGetLastError

Gets the last platform-specific error code produced by any Starboard call in the current thread for diagnostic purposes. Semantic reactions to Starboard function call results should be modeled explicitly.

Declaration

SbSystemError SbSystemGetLastError()

SbSystemGetLocaleId

Gets the system's current POSIX-style Locale ID. The locale represents the location, language, and cultural conventions that the system wants to use, which affects which text is displayed to the user as well as how displayed numbers, dates, currency, and similar values are formatted.

At its simplest, the locale ID can just be a BCP 47 language code, like en_US. Currently, POSIX also wants to include the encoding as in en_US.UTF8. POSIX also allows a couple very bare-bones locales, like "C" or "POSIX", but they are not supported here. POSIX also supports different locale settings for a few different purposes, but Starboard only exposes one locale at a time.

RFC 5646 describes BCP 47 language codes: https://tools.ietf.org/html/bcp47

For more information than you probably want about POSIX locales, see: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html

Declaration

const char* SbSystemGetLocaleId()

SbSystemGetNumberOfProcessors

Returns the number of processor cores available to this application. If the process is sandboxed to a subset of the physical cores, the function returns that sandboxed limit.

Declaration

int SbSystemGetNumberOfProcessors()

SbSystemGetPath

Retrieves the platform-defined system path specified by path_id and places it as a zero-terminated string into the user-allocated out_path unless it is longer than path_length - 1. This implementation must be thread-safe.

This function returns true if the path is retrieved successfully. It returns false under any of the following conditions and, in any such case, out_path is not changed:

  • path_id is invalid for this platform

  • path_length is too short for the given result

  • out_path is NULL

path_id: The system path to be retrieved. out_path: The platform-defined system path specified by path_id. path_length: The length of the system path.

Declaration

bool SbSystemGetPath(SbSystemPathId path_id, char *out_path, int path_length)

SbSystemGetProperty

Retrieves the platform-defined system property specified by property_id and places its value as a zero-terminated string into the user-allocated out_value unless it is longer than value_length - 1. This implementation must be thread- safe.

This function returns true if the property is retrieved successfully. It returns false under any of the following conditions and, in any such case, out_value is not changed:

  • property_id is invalid for this platform

  • value_length is too short for the given result

  • out_value is NULL

property_id: The system path to be retrieved. out_value: The platform- defined system property specified by property_id. value_length: The length of the system property.

Declaration

bool SbSystemGetProperty(SbSystemPropertyId property_id, char *out_value, int value_length)

SbSystemGetRandomData

A cryptographically secure random number generator that produces an arbitrary, non-negative number of buffer_size random, non-negative bytes. The generated number is placed in out_buffer. This function does not require manual seeding.

out_buffer: A pointer for the generated random number. This value must not be null. buffer_size: The size of the random number, in bytes.

Declaration

void SbSystemGetRandomData(void *out_buffer, int buffer_size)

SbSystemGetRandomUInt64

A cryptographically secure random number generator that gets 64 random bits and returns them as an uint64_t. This function does not require manual seeding.

Declaration

uint64_t SbSystemGetRandomUInt64()

SbSystemGetStack

Places up to stack_size instruction pointer addresses of the current execution stack into out_stack. The return value specifies the number of entries added.

The returned stack frames are in "downward" order from the calling frame toward the entry point of the thread. So, if all the stack frames do not fit, the ones truncated will be the less interesting ones toward the thread entry point.

This function is used in crash signal handlers and, therefore, it must be async- signal-safe on platforms that support signals. The following document discusses what it means to be async-signal-safe on POSIX: http://pubs.opengroup.org/onlinepubs/009695399/functions/xsh_chap02_04.html#tag_02_04_03

out_stack: A non-NULL array of void * of at least stack_size entries. stack_size: The maximum number of instruction pointer addresses to be placed into out_stack from the current execution stack.

Declaration

int SbSystemGetStack(void **out_stack, int stack_size)

SbSystemGetTotalCPUMemory

Returns the total CPU memory (in bytes) potentially available to this application. If the process is sandboxed to a maximum allowable limit, the function returns the lesser of the physical and sandbox limits.

Declaration

int64_t SbSystemGetTotalCPUMemory()

SbSystemGetTotalGPUMemory

Returns the total GPU memory (in bytes) available for use by this application. This function may only be called the return value for calls to SbSystemHasCapability(kSbSystemCapabilityCanQueryGPUMemoryStats) is true.

Declaration

int64_t SbSystemGetTotalGPUMemory()

SbSystemGetUsedCPUMemory

Returns the total physical CPU memory (in bytes) used by this application. This value should always be less than (or, in particularly exciting situations, equal to) SbSystemGetTotalCPUMemory().

Declaration

int64_t SbSystemGetUsedCPUMemory()

SbSystemGetUsedGPUMemory

Returns the current amount of GPU memory (in bytes) that is currently being used by this application. This function may only be called if the return value for calls to SbSystemHasCapability(kSbSystemCapabilityCanQueryGPUMemoryStats) is true.

Declaration

int64_t SbSystemGetUsedGPUMemory()

SbSystemHasCapability

Returns whether the platform has the runtime capability specified by capability_id. Returns false for any unknown capabilities. This implementation must be thread-safe.

capability_id: The runtime capability to check.

Declaration

bool SbSystemHasCapability(SbSystemCapabilityId capability_id)

SbSystemHideSplashScreen

Hides the system splash screen on systems that support a splash screen that is displayed while the application is loading. This function may be called from any thread and must be idempotent.

Declaration

void SbSystemHideSplashScreen()

SbSystemIsDebuggerAttached

Attempts to determine whether the current program is running inside or attached to a debugger. The function returns false if neither of those cases is true.

Declaration

bool SbSystemIsDebuggerAttached()

SbSystemPlatformErrorIsValid

Checks whether a SbSystemPlatformError is valid.

Declaration

static bool SbSystemPlatformErrorIsValid(SbSystemPlatformError handle)

SbSystemRaisePlatformError

Cobalt calls this function to notify the platform that an error has occurred in the application that the platform may need to handle. The platform is expected to then notify the user of the error and to provide a means for any required interaction, such as by showing a dialog.

The return value is a handle that may be used in a subsequent call to SbSystemClearPlatformError. For example, the handle could be used to programatically dismiss a dialog that was raised in response to the error. The lifetime of the object referenced by the handle is until the user reacts to the error or the error is dismissed by a call to SbSystemClearPlatformError, whichever happens first. Note that if the platform cannot respond to the error, then this function should return kSbSystemPlatformErrorInvalid.

This function may be called from any thread, and it is the platform's responsibility to decide how to handle an error received while a previous error is still pending. If that platform can only handle one error at a time, then it may queue the second error or ignore it by returning kSbSystemPlatformErrorInvalid.

type: An error type, from the SbSystemPlatformErrorType enum, that defines the error. callback: A function that may be called by the platform to let the caller know that the user has reacted to the error. user_data: An opaque pointer that the platform should pass as an argument to the callback function, if it is called.

Declaration

SbSystemPlatformError SbSystemRaisePlatformError(SbSystemPlatformErrorType type, SbSystemPlatformErrorCallback callback, void *user_data)

SbSystemRequestPause

Requests that the application move into the Paused state at the next convenient point. This should roughly correspond to "unfocused application" in a traditional window manager, where the application may be partially visible.

This function eventually causes a kSbEventTypePause event to be dispatched to the application. Before the kSbEventTypePause event is dispatched, some work may continue to be done, and unrelated system events may be dispatched.

Declaration

void SbSystemRequestPause()

SbSystemRequestStop

Requests that the application be terminated gracefully at the next convenient point. In the meantime, some work may continue to be done, and unrelated system events may be dispatched. This function eventually causes a kSbEventTypeStop event to be dispatched to the application. When the process finally terminates, it returns error_level, if that has any meaning on the current platform.

error_level: An integer that serves as the return value for the process that is eventually terminated as a result of a call to this function.

Declaration

void SbSystemRequestStop(int error_level)

SbSystemRequestSuspend

Requests that the application move into the Suspended state at the next convenient point. This should roughly correspond to "minimization" in a traditional window manager, where the application is no longer visible.

This function eventually causes a kSbEventTypeSuspend event to be dispatched to the application. Before the kSbEventTypeSuspend event is dispatched, some work may continue to be done, and unrelated system events may be dispatched.

In the Suspended state, the application will be resident, but probably not running. The expectation is that an external system event will bring the application out of the Suspended state.

Declaration

void SbSystemRequestSuspend()

SbSystemRequestUnpause

Requests that the application move into the Started state at the next convenient point. This should roughly correspond to a "focused application" in a traditional window manager, where the application is fully visible and the primary receiver of input events.

This function eventually causes a kSbEventTypeUnpause event to be dispatched to the application. Before kSbEventTypeUnpause is dispatched, some work may continue to be done, and unrelated system events may be dispatched.

Declaration

void SbSystemRequestUnpause()

SbSystemSort

Sorts an array of elements base, with element_count elements of element_width bytes each, using comparator as the comparison function.

This function is meant to be a drop-in replacement for qsort.

base: The array of elements to be sorted. element_count: The number of elements in the array. element_width: The size, in bytes, of each element in the array. comparator: A value that indicates how the array should be sorted.

Declaration

void SbSystemSort(void *base, size_t element_count, size_t element_width, SbSystemComparator comparator)

SbSystemSupportsResume

Returns false if the platform doesn't need resume after suspend support. In such case Cobalt will free up the resource it retains for resume after suspend. Note that if this function returns false, the Starboard implementation cannot send kSbEventTypeResume to the event handler. The return value of this function cannot change over the life time of the application.

Declaration

bool SbSystemSupportsResume()

SbSystemSymbolize

Looks up address as an instruction pointer and places up to (buffer_size - 1) characters of the symbol associated with it in out_buffer, which must not be NULL. out_buffer will be NULL-terminated.

The return value indicates whether the function found a reasonable match for address. If the return value is false, then out_buffer is not modified.

This function is used in crash signal handlers and, therefore, it must be async- signal-safe on platforms that support signals.

Declaration

bool SbSystemSymbolize(const void *address, char *out_buffer, int buffer_size)