blob: cec1884fc2c4952037f895e5e85cb387fd8d5a5a [file] [log] [blame]
// 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
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
// The event system that wraps the Starboard main loop and entry point.
#include "starboard/configuration.h"
#include "starboard/export.h"
#include "starboard/time.h"
#include "starboard/types.h"
#ifdef __cplusplus
extern "C" {
// The Starboard Application life cycle
// ------------------------------------
// *
// | _________________________
// Start | |
// | | Resume
// V V |
// [ STARTED ] --Pause--> [ PAUSED ] --Suspend--> [ SUSPENDED ]
// ^ | |
// | Unpause Stop
// |_____________________| |
// V
// [ STOPPED ]
// The first event that a Starboard application will receive is Start
// (kSbEventTypeStart). This puts the application in the STARTED state; it is in
// the foreground and can expect to do all the normal things it might want to
// do. Once in the STARTED state, it may receive a Pause event, putting the
// application into the PAUSED state.
// In the PAUSED state, the application is still visible, but has lost focus, or
// it is partially obscured by a modal dialog, or it is on its way to being shut
// down. The application should pause activity in this state. In this state, it
// can receive Unpause to be brought back to the foreground state, STARTED, or
// Suspend to be pushed further in the background to the SUSPENDED state.
// In the SUSPENDED state, the application is generally not visible. It should
// immediately release all graphics and video resources, and shut down all
// background activity (timers, rendering, etc). Additionally, the application
// should flush storage to ensure that if the application is killed, the storage
// will be up-to-date. The application may be killed at this point, but will
// ideally receive a Stop event for a more graceful shutdown.
// Note that the application is always expected to transition through PAUSED to
// SUSPENDED before receiving Stop or being killed.
// An enumeration of all possible event types dispatched directly by the
// system. Each event is accompanied by a void* data argument, and each event
// must define the type of the value pointed to by that data argument, if any.
typedef enum SbEventType {
// The first event that an application receives on startup. Applications
// should perform initialization and prepare to react to subsequent events.
// Applications that wish to run and then exit must call SbSystemRequestStop()
// to terminate. This event will only be sent once for a given process launch.
// SbEventStartData is passed as the data argument.
// A dialog will be raised or the application will otherwise be put into a
// background-but-visible or partially-obscured state (PAUSED). Graphics and
// video resources will still be available, but the application should pause
// foreground activity like animations and video playback. Can only be
// received after a Start event. The only events that should be dispatched
// after a Pause event are Unpause or Suspend. No data argument.
// The application is returning to the foreground (STARTED) after having been
// put in the PAUSED (e.g. partially-obscured) state. The application should
// unpause foreground activity like animations and video playback. Can only be
// received after a Pause or Resume event. No data argument.
// The operating system will put the application into a Suspended state after
// this event is handled. The application is expected to stop periodic
// background work, release ALL graphics and video resources, and flush any
// pending SbStorage writes. Some platforms will terminate the application if
// work is done or resources are retained after suspension. Can only be
// received after a Pause event. The only events that should be dispatched
// after a Suspend event are Resume or Stop. On some platforms, the process
// may also be killed after Suspend without a Stop event. No data argument.
// The operating system has restored the application to the PAUSED state from
// the SUSPENDED state. This is the first event the application will receive
// coming out of SUSPENDED, and it will only be received after a Suspend
// event. The application will now be in the PAUSED state. No data argument.
// The operating system will shut the application down entirely after this
// event is handled. Can only be recieved after a Suspend event, in the
// SUSPENDED state. No data argument.
// A user input event, including keyboard, mouse, gesture, or something else.
// SbInputData (from input.h) is passed as the data argument.
// A user change event, which means a new user signed-in or signed-out, or the
// current user changed. No data argument, call SbUserGetSignedIn() and
// SbUserGetCurrent() to get the latest changes.
// A navigational link has come from the system, and the application should
// consider handling it by navigating to the corresponding application
// location. The data argument is an application-specific, null-terminated
// string.
// The beginning of a vertical sync has been detected. This event is very
// timing-sensitive, so as little work as possible should be done on the main
// thread if the application wants to receive this event in a timely manner.
// No data argument.
// The platform has detected a network disconnection. The platform should make
// a best effort to send an event of this type when the network disconnects,
// but there are likely to be cases where the platform cannot detect the
// disconnection (e.g. if the connection is via a powered hub which becomes
// disconnected), so the current network state cannot always be inferred from
// the sequence of Connect/Disconnect events.
// The platform has detected a network connection. This event may be sent at
// application start-up, and should always be sent if the network reconnects
// since a disconnection event was sent.
// An event type reserved for scheduled callbacks. It will only be sent in
// response to an application call to SbEventSchedule(), and it will call the
// callback directly, so SbEventHandle should never receive this event
// directly. The data type is an internally-defined structure.
} SbEventType;
// Structure representing a Starboard event and its data.
typedef struct SbEvent {
SbEventType type;
void* data;
} SbEvent;
// A function that can be called back from the main Starboard event pump.
typedef void (*SbEventCallback)(void* context);
// A function that will cleanly destroy an event data instance of a specific
// type.
typedef void (*SbEventDataDestructor)(void* data);
// An ID that can be used to refer to a scheduled event.
typedef uint32_t SbEventId;
// Event data for kSbEventTypeStart events.
typedef struct SbEventStartData {
// The command-line argument values (argv).
char** argument_values;
// The command-line argument count (argc).
int argument_count;
// The startup link, if any.
const char* link;
} SbEventStartData;
#define kSbEventIdInvalid (SbEventId)0
// Returns whether the given event handle is valid.
static SB_C_FORCE_INLINE bool SbEventIsIdValid(SbEventId handle) {
return handle != kSbEventIdInvalid;
// Declaration of the entry point that Starboard applications MUST implement.
// Any memory pointed at by |event| or the |data| field inside |event| is owned
// by the system, and will be reclaimed after this function returns, so the
// implementation must copy this data to extend its life. This should also be
// assumed of all fields within the data object, unless otherwise explicitly
// specified. This function will only be called from the main Starboard thread.
// There is no specification about what other work might happen on this thread,
// so the application should generally do as little work as possible on this
// thread, and just dispatch it over to another thread.
SB_IMPORT void SbEventHandle(const SbEvent* event);
// Schedules an event |callback| into the main Starboard event loop, with
// accompanying |context|. This function may be called from any thread, but
// |callback| will always be called from the main Starboard thread, queued with
// other pending events. |callback| will not be called any earlier than |delay|
// microseconds from the time SbEventInject is called. Set |delay| to 0 to call
// the event as soon as possible.
SB_EXPORT SbEventId SbEventSchedule(SbEventCallback callback,
void* context,
SbTime delay);
// Cancels the injected |event_id|. Does nothing if the event already fired. Can
// be safely called from any thread, but there is no guarantee that the event
// will not run anyway unless it is called from the main Starboard event loop
// thread.
SB_EXPORT void SbEventCancel(SbEventId event_id);
#ifdef __cplusplus
} // extern "C"