Module: Toybox.Background

Overview

Background events are special events that trigger in the background when either certain system events occur, such as when an activity goal has been met, or at certain times (called temporal events). This allows an application to update its data even when the application is not active.

See Also:

Since:

API Level 2.3.0

Supported Devices:

Requires Permission:

  • Background

Classes Under Namespace

Classes: ExitDataSizeLimitException, InvalidBackgroundTimeException, MessageSizeLimitException

Instance Method Summary collapse

Instance Method Details

deleteActivityCompletedEvent() as Void

Stops the application from receiving activity completed events.

Since:

API Level 3.0.10

deleteGoalEvent(goalType as Application.GoalType) as Void

Remove the active goal background event of specified type for the application.

Parameters:

Example:

Background.deleteGoalEvent(GOAL_TYPE_STEPS);

Since:

API Level 2.3.0

deleteOAuthResponseEvent() as Void

Remove the OAuth response background event.

Since:

API Level 2.3.0

deletePhoneAppMessageEvent() as Void

Stops the application from receiving background phone app messages.

Supported Devices:

Since:

API Level 3.2.0

deletePushNotificationEvent() as Void

Stops the application from receiving silent and actionable push notifications.

Since:

API Level 3.0.10

deleteSleepEvent() as Void

Remove the active sleep background event for the application.

Since:

API Level 2.3.0

deleteStepsEvent() as Void

Remove the active steps background event for the application.

Since:

API Level 2.3.0

deleteTemporalEvent() as Void

Remove the active temporal background event for the application.

Since:

API Level 2.3.0

deleteWakeEvent() as Void

Remove the active wake background event for the application.

Since:

API Level 2.3.0

exit(backgroundData as Application.PropertyValueType) as Void

Terminates the current background process.

All background processes should call this method when they have completed the desired tasks. Data passed to this method will either be passed immediately to the active application if it is running, or will be saved and passed to the application the next time it runs. Data must be one of the following types:

Arrays and Dictionaries may contain null values or any of the above listed types. If no data should be passed to the main process, null may be specified.

This method will exit if called by a background process, but will do nothing if called by the main application process.

Parameters:

  • backgroundData — (Lang.Object) —

    The object to pass to the main process's AppBase.onBackgroundData() method. Passing null will not override previous data values not yet consumed by the parent application's AppBase.onBackgroundData() method.

Since:

API Level 2.3.0

Throws:

  • (Background.ExitDataSizeLimitException) —

    Indicates the data provided exceeds the data size limit (approximately 8 KB). If this exception is caught, the process will not exit and should attempt to call Background.exit() again with less data.

getActivityCompletedEventRegistered() as Lang.Boolean

Get whether a background event is registered with registerForActivityCompletedEvent()

Returns:

  • Lang.Boolean —

    true if a background event is registered with registerForActivityCompletedEvent(), otherwise false

Since:

API Level 3.0.10

getBackgroundData() as Application.PropertyValueType

Get data previously saved by a background process.

Data is delivered via AppBase.onBackgroundData(), and is reset to null once data has been delivered to the main process. This method always returns null in the main application's process.

See Also:

Since:

API Level 2.3.0

getGoalEventRegistered(goalType as Application.GoalType) as Lang.Boolean

Get whether a background event is registered with registerForGoalEvent().

Parameters:

Returns:

  • Lang.Boolean —

    true if a background event is registered with registerForGoalEvent(), otherwise false

Since:

API Level 3.0.0

getLastTemporalEventTime() as Time.Moment or Null

Get the time the last temporal background event was triggered.

This is useful for ensuring new events are not scheduled within the five minute minimum time allowed between temporal events.

Example:

Register a new temporal background event as soon as allowed

using Toybox.Background;
using Toybox.Time;
const FIVE_MINUTES = new Time.Duration(5 * 60);
var lastTime = Background.getLastTemporalEventTime();
if (lastTime != null) {
    // Events scheduled for a time in the past trigger immediately
    var nextTime = lastTime.add(FIVE_MINUTES);
    Background.registerForTemporalEvent(nextTime);
} else {
    Background.registerForTemporalEvent(Time.now());
}

Returns:

  • Time.Moment —

    The time the last background event was triggered, but may be null if no previous temporal background event has occurred or if the device app or widget has been started since the event was last triggered

See Also:

Since:

API Level 2.3.0

getOAuthResponseEventRegistered() as Lang.Boolean

Get whether a background event is registered with registerForOAuthResponseEvent()

Returns:

  • Lang.Boolean —

    true if a background event is registered with registerForOAuthResponseEvent(), otherwise false

Since:

API Level 3.0.0

getPhoneAppMessageEventRegistered() as Lang.Boolean

Get whether a background event is registered with registerForPhoneAppMessageEvent()

Supported Devices:

Returns:

  • Lang.Boolean —

    true if a background event is registered with registerForPhoneAppMessageEvent(), otherwise false

Since:

API Level 3.2.0

getPushNotificationEventRegistered() as Lang.Boolean

Get whether a background event is registered with registerForPushNotificationEvent()

Returns:

  • Lang.Boolean —

    true if a background event is registered with registerForPushNotificationEvent(), otherwise false

Since:

API Level 3.0.10

getSleepEventRegistered() as Lang.Boolean

Get whether a background event is registered with registerForSleepEvent().

Returns:

  • Lang.Boolean —

    true if a background event is registered with registerForSleepEvent(), otherwise false

Since:

API Level 3.0.0

getStepsEventRegistered() as Lang.Boolean

Get whether a background event is registered with registerForStepsEvent().

Returns:

  • Lang.Boolean —

    true if a background event is registered with registerForStepsEvent(), otherwise false

Since:

API Level 3.0.0

getTemporalEventRegisteredTime() as Time.Moment or Time.Duration or Null

Get the Moment or Duration with which a background event is registered by registerForTemporalEvent().

Returns:

  • Time.Moment, Time.Duration —

    The specific Moment in time at which a background event is registered to trigger, or the interval Duration at which to repeat a background event. May be null if no temporal background event is registered.

See Also:

Since:

API Level 3.0.0

getWakeEventRegistered() as Lang.Boolean

Get whether a background event is registered with registerForWakeEvent().

Returns:

  • Lang.Boolean —

    true if a background event is registered with registerForWakeEvent(), otherwise false

Since:

API Level 3.0.0

registerForActivityCompletedEvent() as Void

Registers the application to receive an event whenever an activity is completed.

Since:

API Level 3.0.10

registerForGoalEvent(goalType as Application.GoalType) as Void

Register a background event that triggers when the user reaches a specified goal.

Parameters:

Example:

Background.registerForGoalEvent(GOAL_TYPE_STEPS);

Since:

API Level 2.3.0

registerForOAuthResponseEvent() as Void

Registers a background event that triggers each time an OAuth login request completes and the token becomes available on the system for use.

This event is triggered when a OAuth response is received by the system.

Since:

API Level 2.3.0

registerForPhoneAppMessageEvent() as Void

Registers the application to receive an event whenever a phone app message is received.

Supported Devices:

Since:

API Level 3.2.0

registerForPushNotificationEvent() as Void

Registers the application to receive silent and actionable push notifications.

Since:

API Level 3.0.10

registerForSleepEvent() as Void

Register a background event that triggers at the sleep time configured on the device.

Since:

API Level 2.3.0

registerForStepsEvent() as Void

Registers a background event that triggers each time a multiple of 1000 steps is reached.

This event is triggered only by device-recorded steps, and will not trigger based on synced steps.

Since:

API Level 2.3.0

registerForTemporalEvent(time as Time.Moment or Time.Duration) as Void

Register a background event that triggers at a specific time or at a regular interval.

Temporal background events may be registered to run at a specific point in time by providing a Moment at which the event should trigger, or may be registered to run at a periodically by specifying an interval Duration. If a temporal event is scheduled for a time in the past, the event will trigger immediately.

Temporal events cannot be set to occur less than 5 minutes after the last temporal event occurred. For watch-apps and widgets the 5 minute restriction is cleared on application startup if the event was specified using a Moment.

Only one temporal event may be registered at a time. Calling registerForTemporalEvent will overwrite any previously registered temporal events.

Parameters:

  • time — (Time.Moment, Time.Duration) —

    The specific Moment in time at which to run a background event, or the interval Duration at which to repeat a background event

Example:

Schedule a background event to run five minutes from now

using Toybox.Background;
using Toybox.Time;
const FIVE_MINUTES = new Time.Duration(5 * 60);
var eventTime = Time.now().add(FIVE_MINUTES);
Background.registerForTemporalEvent(eventTime);

See Also:

Since:

API Level 2.3.0

Throws:

  • (Background.InvalidBackgroundTimeException) —

    Indicates an application has attempted to schedule a background event which either: * Occurs less than five minutes after the last background event occurred * Has a duration of less than five minutes

registerForWakeEvent() as Void

Register a background event that triggers at the wake time configured on the device.

Since:

API Level 2.3.0

requestApplicationWake(message as Lang.String) as Void

Display a confirmation dialog requesting to launch the application to which the background task belongs.

If the dialog is confirmed, the application will open. If the dialog is declined, the application will not open and the dialog will be dismissed. This request is only valid for widget or device app background tasks, and will be ignored by watch face apps. Background.exit() must be called at some point in the background process after this method is invoked because the confirmation dialog will only trigger after the background task exits.

Parameters:

  • message — (Lang.String) —

    The message to display in the dialog when requesting to launch the app

Example:

using Toybox.Background;
(:background)
class BackgroundServiceDelegate extends System.ServiceDelegate {
    function initialize() {
        ServiceDelegate.initialize();
    }

    function onTemporalEvent() {
        Background.requestApplicationWake("Launch Cool App?");
        Background.exit(null);
    }
}

See Also:

Since:

API Level 2.3.0

Throws:

Generated Sep 23, 2024, 3:32:48 PM