src/starboard/system.h

// Copyright 2015 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

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

#ifndef STARBOARD_SYSTEM_H_
#define STARBOARD_SYSTEM_H_

#include "starboard/configuration.h"
#include "starboard/export.h"
#include "starboard/types.h"

#ifdef __cplusplus
extern "C" {
#endif

// A type that can represent a system error code across all Starboard platforms.
typedef int SbSystemError;

// Enumeration of special paths that the platform can define.
typedef enum SbSystemPathId {
  // Path to where the local content files that ship with the binary are
  // available.
  kSbSystemPathContentDirectory,

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

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

  // Path to the directory containing the root of the source tree.
  kSbSystemPathSourceDirectory,

  // Path to a directory where temporary files can be written.
  kSbSystemPathTempDirectory,

  // Path to a directory where test results can be written.
  kSbSystemPathTestOutputDirectory,

  // Full path to the executable file.
  kSbSystemPathExecutableFile,
} SbSystemPathId;

// System properties that can be queried for. Many of these are used in
// User-Agent string generation.
typedef enum SbSystemPropertyId {
  // The full model number of the main platform chipset, including any
  // vendor-specific prefixes.
  kSbSystemPropertyChipsetModelNumber,

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

  // 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).
  kSbSystemPropertyFriendlyName,

  // A deprecated alias for |kSbSystemPropertyBrandName|.
  kSbSystemPropertyManufacturerName,

  // The name of the brand under which the device is being sold.
  kSbSystemPropertyBrandName = kSbSystemPropertyManufacturerName,

  // The final production model number of the device.
  kSbSystemPropertyModelName,

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

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

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

  // A universally-unique ID for the current user.
  kSbSystemPropertyPlatformUuid,

#if SB_VERSION(2)
  // 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 are able to enable the
  // Speech APIs and generate a Speech API key.
  kSbSystemPropertySpeechApiKey,
#endif  // SB_VERSION(2)
} SbSystemPropertyId;

// Enumeration of device types.
typedef enum SbSystemDeviceType {
  // Blue-ray Disc Player (BDP).
  kSbSystemDeviceTypeBlueRayDiskPlayer,

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

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

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

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

  // Desktop PC.
  kSbSystemDeviceTypeDesktopPC,

  // Unknown device.
  kSbSystemDeviceTypeUnknown,
} SbSystemDeviceType;

// Enumeration of network connection types.
typedef enum SbSystemConnectionType {
  // The system is on a wired connection.
  kSbSystemConnectionTypeWired,

  // The system is on a wireless connection.
  kSbSystemConnectionTypeWireless,

  // The system connection type is unknown.
  kSbSystemConnectionTypeUnknown,
} SbSystemConnectionType;

// Runtime capabilities are boolean properties of a platform that can't be
// determined at compile-time, and may vary from device to device, but 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.
typedef enum SbSystemCapabilityId {
  // Whether this system has reversed Enter and Back keys.
  kSbSystemCapabilityReversedEnterAndBack,

  // Whether this system has the ability to report on GPU memory usage.
  // If (and only if) a system has this capcability will
  // SbSystemGetTotalGPUMemory() and SbSystemGetUsedGPUMemory() be valid to
  // call.
  kSbSystemCapabilityCanQueryGPUMemoryStats,
} SbSystemCapabilityId;

// Enumeration of possible values for the |type| parameter passed to  the
// |SbSystemRaisePlatformError| function.
typedef enum SbSystemPlatformErrorType {
  // Cobalt received a network connection error, or a network disconnection
  // event.
  kSbSystemPlatformErrorTypeConnectionError,

  // The current user is not signed in (e.g. to PSN network).
  kSbSystemPlatformErrorTypeUserSignedOut,

  // The current user does not meet the age requirements to use the app.
  kSbSystemPlatformErrorTypeUserAgeRestricted
} SbSystemPlatformErrorType;

// Possible responses for |SbSystemPlatformErrorCallback|.
typedef enum SbSystemPlatformErrorResponse {
  kSbSystemPlatformErrorResponsePositive,
  kSbSystemPlatformErrorResponseNegative,
  kSbSystemPlatformErrorResponseCancel
} SbSystemPlatformErrorResponse;

// 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|.
typedef void (*SbSystemPlatformErrorCallback)(
    SbSystemPlatformErrorResponse response,
    void* user_data);

// Private structure used to represent a raised platform error.
typedef struct SbSystemPlatformErrorPrivate SbSystemPlatformErrorPrivate;

// Opaque handle returned by |SbSystemRaisePlatformError| that can be passed
// to |SbSystemClearPlatformError|.
typedef SbSystemPlatformErrorPrivate* SbSystemPlatformError;

// Well-defined value for an invalid |SbSystemPlatformError|.
#define kSbSystemPlatformErrorInvalid (SbSystemPlatformError) NULL

// Checks whether a |SbSystemPlatformError| is valid.
static SB_C_INLINE bool SbSystemPlatformErrorIsValid(
    SbSystemPlatformError handle) {
  return handle != kSbSystemPlatformErrorInvalid;
}

// Called by Cobalt to notify the platform that an error has occurred in the
// application that may have to be handled by the platform. It is expected the
// platform will notify the user of the error, and provide interaction if
// required, for example by showing a dialog.
//
// |type| is one of the enumerated types above to define the error; |callback|
// is a function that may be called by the platform to let the caller know the
// user has reacted to the error; |user_data| is an opaque pointer that the
// platform should pass as an argument to the callback, if called.
// Returns a handle that may be used in a subsequent call to
// |SbClearPlatformError|, for example to programatically dismiss a dialog that
// may have been 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. If the platform cannot respond to the error, then
// this function should return |kSbSystemPlatformErrorInvalid|.
//
// This function may be called from any thread; it is the responsibility of the
// platform to decide how to handle an error received while a previous error is
// still pending - if only one error can be handled at a time, then the
// platform may queue the second error or ignore it by returning
// |kSbSystemPlatformErrorInvalid|.
SB_EXPORT SbSystemPlatformError
SbSystemRaisePlatformError(SbSystemPlatformErrorType type,
                           SbSystemPlatformErrorCallback callback,
                           void* user_data);

// Clears a platform error that was previously raised by a call to
// |SbSystemRaisePlatformError|, specified by the handle that was returned by
// that function. The platform may use this, for example, to close a dialog
// that was opened in response to the error.
SB_EXPORT void SbSystemClearPlatformError(SbSystemPlatformError handle);

// Pointer to a function to compare two items, returning less than zero, zero,
// or greater than zero depending on whether |a| is less than |b|, equal to |b|,
// or greater than |b|, respectively (standard *cmp semantics).
typedef int (*SbSystemComparator)(const void* a, const void* b);

// Breaks the current program into the debugger, if a debugger is
// attached. Aborts the program otherwise.
SB_EXPORT void SbSystemBreakIntoDebugger();

// Attempts to determine if the current program is running inside or attached to
// a debugger.
SB_EXPORT bool SbSystemIsDebuggerAttached();

// Returns the number of processor cores available to this application. If the
// process is sandboxed to a subset of the physical cores, it will return that
// sandboxed limit.
SB_EXPORT int SbSystemGetNumberOfProcessors();

// Gets the total CPU memory (in bytes) potentially available to this
// application. If the process is sandboxed to a maximum allowable limit, it
// will return the lesser of the physical and sandbox limits.
SB_EXPORT int64_t SbSystemGetTotalCPUMemory();

// 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().
SB_EXPORT int64_t SbSystemGetUsedCPUMemory();

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

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

// Returns the type of the device.
SB_EXPORT SbSystemDeviceType SbSystemGetDeviceType();

// Returns the device's current network connection type.
SB_EXPORT SbSystemConnectionType SbSystemGetConnectionType();

// Gets the platform-defined system path specified by |path_id|, placing it as a
// zero-terminated string into the user-allocated |out_path|, unless it is
// longer than |path_length| - 1. Returns false if |path_id| is invalid for this
// platform, or if |path_length| is too short for the given result, or if
// |out_path| is NULL. On failure, |out_path| will not be changed.
// Implementation must be thread-safe.
SB_EXPORT bool SbSystemGetPath(SbSystemPathId path_id,
                               char* out_path,
                               int path_length);

// Gets the platform-defined system property specified by |property_id|, placing
// it as a zero-terminated string into the user-allocated |out_value|, unless it
// is longer than |value_length| - 1. Returns false if |property_id| is invalid
// for this platform, or if |value_length| is too short for the given result, or
// if |out_value| is NULL. On failure, |out_value| will not be changed.
// Implementation must be thread-safe.
SB_EXPORT bool SbSystemGetProperty(SbSystemPropertyId property_id,
                                   char* out_value,
                                   int value_length);

// Returns whether the platform has the runtime capability specified by
// |capability_id|. Returns false for any unknown capabilities. Implementation
// must be thread-safe.
SB_EXPORT bool SbSystemHasCapability(SbSystemCapabilityId capability_id);

// 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, and how display numbers,
// dates, currency, and the like are formatted.
//
// At its simplest, it can just be a BCP 47 language code, like "en_US". These
// days, POSIX also wants to include the encoding, like "en_US.UTF8". POSIX
// additionally 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 a single
// locale at a time.
//
// RFC 5646 describing BCP 47 language codes:
// https://tools.ietf.org/html/bcp47
//
// For more information than you want on POSIX locales:
// http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html
SB_EXPORT const char* SbSystemGetLocaleId();

// Gets sixty-four random bits returned as an uint64_t. This is expected to be a
// cryptographically secure random number generator, and doesn't require manual
// seeding.
SB_EXPORT uint64_t SbSystemGetRandomUInt64();

// Produces an arbitrary non-negative number, |buffer_size|, of random bytes
// which must not be negative, placing the result in |out_buffer|, which must
// not be null. This is expected to be a cryptographically secure random number
// generator, and doesn't require manual seeding.
SB_EXPORT void SbSystemGetRandomData(void* out_buffer, int buffer_size);

// 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.
SB_EXPORT SbSystemError SbSystemGetLastError();

// Clears the last error set by a Starboard call in the current thread.
SB_EXPORT void SbSystemClearLastError();

// Writes a human-readable string for |error|, up to |string_length| bytes, into
// the provided |out_string|. Returns the total desired length of the string.
// |out_string| may be null, in which case just the total desired length of the
// string is returned. |out_string| is always terminated with a null byte.
SB_EXPORT int SbSystemGetErrorString(SbSystemError error,
                                     char* out_string,
                                     int string_length);

// Places up to |stack_size| instruction pointer addresses of the current
// execution stack into |out_stack|, returning the number of entries
// populated. |out_stack| must point to a non-NULL array of void * of at least
// |stack_size| entries. The returned stack frames will be in "downward" order
// from the calling frame towards the entry point of the thread. So, if all the
// stack frames do not fit, the ones truncated will be the less interesting ones
// towards the thread entry point. This function must be async-signal-safe on
// platforms that support signals, as it will be used in crash signal handlers.
//
// See the following about 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
SB_EXPORT int SbSystemGetStack(void** out_stack, int stack_size);

// 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. Returns whether it found a
// reasonable match for |address|. If the return value is false, |out_buffer|
// will not be modified. This function must be async-signal-safe on platforms
// that support signals, as it will be used in crash signal handlers.
SB_EXPORT bool SbSystemSymbolize(const void* address,
                                 char* out_buffer,
                                 int buffer_size);

// Requests that the application be terminated gracefully at the next convenient
// point. Some work may continue to be done, and unrelated system events
// dispatched, in the meantime. This will eventually result in a
// kSbEventTypeStop event being dispatched to the application.  When the process
// finally terminates, it will return |error_level|, if that has any meaning on
// the current platform.
SB_EXPORT void SbSystemRequestStop(int error_level);

// 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|. Meant to be a drop-in replacement for bsearch.
SB_EXPORT void* SbSystemBinarySearch(const void* key,
                                     const void* base,
                                     size_t element_count,
                                     size_t element_width,
                                     SbSystemComparator comparator);

// Sorts an array of elements |base|, with |element_count| elements of
// |element_width| bytes each, using |comparator| as the comparison function.
// Meant to be a drop-in replacement for qsort.
SB_EXPORT void SbSystemSort(void* base,
                            size_t element_count,
                            size_t element_width,
                            SbSystemComparator comparator);

// 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.
SB_EXPORT void SbSystemHideSplashScreen();

#ifdef __cplusplus
}  // extern "C"
#endif

#endif  // STARBOARD_SYSTEM_H_