com.webos.service.activitymanager

API Summary

Monitors various parts of the system and does actions when the corresponding events happen. Activities can also be used to schedule work periodically or at particular times.

Overview of the API

The Activity Manager is responsible for coordinating work in the system. This includes work currently being done and work that is scheduled to be done at some point in the future. The primary unit of control is the Activity, which represents some specific item of work in the system - such as syncing an email account or a game that is being played.

The Activity Manager will track H/W and S/W through Activity and notify when the specified events occur. If there is a dynamic service that needs to wake up when certain conditions are met, Activity Manager is the best choice.

activity state transition diagram

An Activity can have the state shown in the diagram above. What the Activity does for each state is as follows.

  • creating
    • The create method is called and the activity is creating.
  • created 
    • The activity was created successfully. 
    • When the create method is called with {'start' : true}, the activity automatically moves to unsatisfied state.
  • starting
    • The start method is called and the activity is starting.
    • In this step, the activity will subscribe requirements, triggers, and schedule.
  • unsatisfied
    • The activity waits for all conditions to be satisfied - requirements, triggers and schedule.
    • The activity in unsatisfied state can be paused by the pause method.
  • pausing
    • The pause method is called and the activity is pausing.
  • paused
    • The activity is paused.
    • In this state, the activity does not move to the satisfied state, although all conditions are satisfied.
    • The activity can move to unsatisfied state by start method.
  • satisfying
    • All conditions of the activity are satisfying
    • An activity in unsatisfied state automatically moves to this state without an API call.
  • satisfied
    • All conditions of the activity are satisfied.
    • There is nothing to do special.
  • expiring
    • The activity is expiring.
    • The activity will call the callback method and unsubscribe triggers and cancel schedule.
  • expired
    • The activity is over.
    • All callbacks are handled successfully.
    • If the activity is not set to continuous property, the activity is in expired state forever.
    • If its parent wants to start it again, the parent should call complete method with {'restart ': true}.
    • If parent does not want to restart it, then it must call the cancel method.
  • restarting
    • The activity is restarting.
    • There are two ways to restart an activity.
      • One is to call the complete method with {'restart' : true}.
      • Another is to give the continuous property to true when creating the activity. If the activity was created with continuous property, the activity will move to unsatisfied state as soon as receive the callback response.
  • failing
    • An error occurs during activity job and the activity is failing.
    • Any activity in any state can move to this state, if an error occurs.
    • Make sure that Triggers or Callbacks do not fail for any reason. Their failure will move the activity immediately to this state.
  • failed
    • The activity has failed, and the activity manager cannot do anything anymore.
    • The parent should call cancel method to destroy the activity.
  • destroying
    • The cancel method is called and the activity is destroying.
    • The cancel method can be called in any activity state,
  • destroyed
    • The activity is destroyed.
    • In this state, the activity will be excluded from being managed by the activity manager.

Methods

create

Description

Note: The 'creator' in Activity object can be set only by configurator.

Create a new Activity and return its ID. Each of created Activities must have a unique name.

Activities can be scheduled to run at a specific time or when certain conditions are met or events occur.

If the Activity specify start as true, because the Activity moves to unsatisfied state, you do not need to call start method.

Parameters

Name

Required

Type

Description

activityRequiredObject: Activity

Activity object.

subscribeOptionalBoolean

Flag that enables whether to subscribe or not.

  • To enable subscribe, set subscribe to true. The caller becomes a parent of the Activity.
  • To disable subscribe, set subscribe to false. When the caller does not subscribe to the Activity, callback must be specified and start must set to true.
  • The default value of subscribe is false
detailedEventsOptionalBoolean

Flag that enables to return detailed Activity information in a subscription response. It needs to be used when subscribe is set to true.

  • To enable detailedEvents, set detailedEvents to true.
  • To disable detailedEvents, set detailedEvents to false.
  • The default value of detailedEvents is false.
startOptionalBoolean

Start Activity immediately flag.

  • To indicate the Activity is fully-initialized and ready to launch, set start to true. When subscribe is set to false, must set start to true
  • To disable start, set start to false. If start is set to false, you need to call the start method to make the Activity runnable.   
  • The default value of start is false.

Note: It is recommended to use start as true regardless of the default value of this. Then you do not need to call start method.

replaceOptionalBoolean
  • To create a new Activity with the same name with the existing Activity, set replace to true. This cancels the existing Activity and replaces it to new one.
  • Otherwise, set replace to false.
  • The default value of replace is false.

Note: If an Activity is located in '/etc/palm/activities', replace should be set carefully. That is, if replace is true, the Activity created by configurator can overwrite the existing Activity.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
activityIdOptionalNumber (uint64_t)

Activity ID.

subscribedOptionalBoolean

If it is subscribed, subscribed will contain true.
If it is not subscribed, subscribed will contain false.

errorCodeOptionalNumber (int64_t)

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. 

Subscription Returns

Name

Required

Type

Description

activityIdRequiredNumber (uint64_t)

Created Activity ID. You could get a subscription when there's status updates.  

eventRequiredString

Note: These events may be changed, as the activity state has been redefined.

Indicate what the created Activity just has been done. The Activity Manager will generate the following events when the corresponding requirements are met:

  • "start"
  • "cancel"
  • "stop"
  • “pause”
  • "complete”
  • “orphan”
  • “adopted”
  • "update" (available only when detailedEvents input parameter is set to true)

The following JSON object is a subscription example that shows the created activity just started:

{
    "activityId": 10813,
    "event": "start",
    "returnValue": true
}

$activityOptionalObject: Activity

Acitivity object.

subscribedRequiredBoolean

If it is subscribed, subscribed will contain true.
If it is not subscribed, subscribed will contain false.

returnValueOptionalBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.

Example

1. Example code to create basic activity:

# luna-send -f -i luna://com.webos.service.activitymanager/create '{
  "activity": {
    "name": "basicactivity",
    "description": "Test create",
    "type": { "foreground": true }
  },
  "start": true,
  "subscribe": true
}'

Response:

{
  "activityId": 83,
  "returnValue": true,
  "subscribed": true
}

Subscription Response:

{
  "event": "start",
  "activityId": 83,
  "returnValue": true,
  "subscribed": true
}

-----------------------------------------------------------------------------------------------------------------------

2. Example code to create scheduled activity:

# luna-send -f -i luna://com.webos.service.activitymanager/create '{
  "activity": {
    "name": "ScheduledActivity",
    "description": "Test create of scheduled activity",
    "type": { "foreground": true },
    "schedule": { "start": "2015-02-15 13:22:00" }
  },
  "start": true,
  "subscribe": true
}'

Response:

{
  "activityId": 102,
  "returnValue": true,
  "subscribed": true
}

Subscription response:

{
  "event": "start",
  "activityId": 102,
  "returnValue": true,
  "subscribed": true
}

-----------------------------------------------------------------------------------------------------------------------

3. Example code to create scheduled activity with callback:

# luna-send -f -i luna://com.webos.service.activitymanager/create '{
  "activity": {
    "name": "ScheduledActivityWithCallback",
    "description": "Test create of scheduled activity with callback",
    "type": { "foreground": true },
    "callback": {
      "method": "luna://com.webos.service.applicationmanager/launch",
      "params": { "id": "com.webos.app.enactbrowser" }
    },
    "schedule": { "start": "2015-02-15 00:05:00" }
  },
  "start": true,
  "subscribe": true
}'

Response:

{
  "activityId": 84,
  "returnValue": true,
  "subscribed": true
}

Subscription response:

{
  "event": "start",
  "activityId": 84,
  "returnValue": true,
  "subscribed": true
}

-----------------------------------------------------------------------------------------------------------------------

4. Example code to create activity with multiple trigger:

# luna-send -i -f luna://com.webos.service.activitymanager/create '{
  "activity": {
    "name": "browser restart",
    "description":"",
    "type": { "foreground":true, "continuous": true },
    "callback": {
      "method": "luna://com.webos.service.applicationmanager/launch",
      "params": { "id": "com.webos.app.enactbrowser" }
    },
    "trigger": {
      "and": [
        {
          "method": "luna://com.webos.service.applicationmanager/getAppLifeStatus",
          "params": { "subscribe": true },
          "where": {
            "and": [
              { "op": "=", "prop": "appId", "val": "com.webos.app.enactbrowser" },
              { "op": "=", "prop": "status", "val": "stop"}
            ]
          }
        },
        {
          "method": "luna://com.webos.service.connectionmanager/getstatus",
          "params": { "subscribe": true },
          "where": { "prop": "isInternetConnectionAvailable", "op": "=", "val": true }
        }
      ]
    }
  },
  "start": true,
  "subscribe": true
}'

Response:

{
  "activityId": 85,
  "returnValue": true,
  "subscribed": true
}

Subscription response:

{
  "event": "start",
  "activityId": 85,
  "returnValue": true,
  "subscribed": true
}

-----------------------------------------------------------------------------------------------------------------------

5. Example code to create continuous activity

# luna-send -n 1 -f luna://com.webos.service.activitymanager/create '{
  "activity": {
    "name": "continuous-schedule",
    "description":"",
    "type": {"foreground": true, "continuous": true},
    "callback": {
        "method": "luna://com.webos.notification/createToast",
        "params": {"message": "5m", "persistent": true}
    },
    "schedule": {"interval": "5m"}
  },
  "replace":true,
  "start":true
}'

Response:

{
  "activityId": 60,
  "returnValue": true,
  "subscribed": false
}

Subscription response:

{
  "event": "start",
  "activityId": 60,
  "returnValue": true,
  "subscribed": true
}

start

Description

Attempt to start the specified Activity, either moving its state from 'created' to 'starting', or from 'paused' to 'resuming'.

Parameters

Name

Required

Type

Description

activityIdRequiredNumber (uint64_t)

Activity ID. 

Note: Either activityId or activityName is a REQUIRED field.

activityNameRequiredString

Activity name.Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. 
errorCodeOptionalNumber (int64_t)

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. 

Example

# luna-send -n 1 -f luna://com.webos.service.activitymanager/start '{"activityId" : 93}'

complete

Description

Terminate the specified Activity and optionally restart it with(or without) new callback, schedule or trigger. Only the Activity's parent can call this method. Other subscribers to the Activity receive a "complete" event.

If the Activity is persistent (i.e., persist in the Type object is set to true), the db8 is updated before the call returns.

Note: The invocations to callback/triggers are constrained by ACG security model. It means that Activity Manager can invoke trigger/callback when both Activity Manager and activity creator have the permissions to those methods. Otherwise, the method fails with the error "'com.webos.service.activitymanager' doesn't have rights to call callback/trigger".

Parameters

Name

Required

Type

Description

activityIdRequiredNumber (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityNameRequiredString

Activity name.Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

restartOptionalBoolean
  • To restart the Activity with any new callback, schedule or trigger, set restart to true. The restarted Activity goes into the Activity Manager queue.
  • To disable restart, set restart to false.
  • The default value of restart is false.

Note: If restart is false, this is equivalent to cancel. Therefore, it is recommended to always set restart to true to avoid confusion.

callbackOptionalObject: Callback

Callback to use when the specified Activity is restarted.

  • To use the current callback condition, do not specify callback parameter.
  • To remove the current callback condition, set callback to false.
scheduleOptionalObject: Schedule

Schedule to use when Activity is restarted.

  • To use the current callback condition, do not specify schedule parameter.
  • To remove the current callback condition, set schedule to false.
triggerOptionalObject: Trigger

Trigger to use when the specified Activity is restarted.

  • To use the current callback condition, do not specify trigger parameter.
  • To remove the current callback condition, set trigger to false.
metadataOptionalObject

Opaque object the Activity Manager stores and returns in the callback parameters.

  • To use the current metadata, do not specify metadata parameter.
  • To remove the current metadata, set metadata to false.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCodeOptionalNumber (int64_t)

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. 

Example

Step 1: Create an activity that is to be triggered when any app is stopped.

# luna-send -n 1 -f -a myapp luna://com.webos.service.activitymanager/create '{
    "activity": {
        "name": "browser closed",
        "description": "",
        "type": {"foreground": true},
        "callback": {
            "method": "luna://com.webos.notification/createToast",
            "params": {"message": "browser closed", "persistent": true}
        },
        "trigger": {
            "method": "luna://com.webos.service.applicationmanager/getAppLifeStatus",
            "params": {"subscribe": true},
            "where": {
                "prop": "status",
                "op": "=",
                "val": "stop"
             }
        }
    },
    "replace": true,
    "start": true
}'

Response:

{
    "subscribed": false,
    "activityId": 62,
    "returnValue": true
}

 

Step 2: Close any app.

# luna-send -n 1 -f luna://com.webos.service.applicationmanager/closeByAppId '{"id":"com.webos.app.enactbrowser"}'

Response:

{
    "appId": "com.webos.app.enactbrowser",
    "returnValue": true
}

 

Step 3: Complete the activity and then start it again.

# luna-send -n 1 -f -a myapp luna://com.webos.service.activitymanager/complete '{
    "activityName": "browser closed",
    "restart": true
}'

Response:

{
    "returnValue": true
}

cancel

Description

Terminate the specified Activity and send a "cancel" event to all subscribers to this Activity. This method succeeds if the Activity exists.

Parameters

Name

Required

Type

Description

activityIdRequiredNumber (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityNameRequiredString

Activity name.Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

If the cancel method succeeds, returnValue will contain true.

If the cancel method fails, returnValue will contain false.

errorCodeOptionalNumber (int64_t)

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -f luna://com.webos.service.activitymanager/cancel '{"activityId" : 93}'

stop

Description

Stop the specified Activity and send a "stop" event to subscribers to this Activity. This method succeeds if the Activity exists.

This method is exactly the same as cancel method. It is recommended to use cancel to avoid confusion.

Parameters

Name

Required

Type

Description

activityIdRequiredNumber (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityNameRequiredString

Activity name.Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCodeOptionalNumber (int64_t)

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -f luna://com.webos.service.activitymanager/stop '{"activityId" : 95}'

adopt

Description

The Activity Manager considers the creator of the Activity as a parent.

Therefore, the creator of the activity does not need to adopt the Activity to be a parent.

An app or a service registers its willingness to become an Activity's parent, which means becoming an adopter.

  • If there are adopters, all subscribers to this Activity receives an "orphan" event and the Activity is adopted to the new parent, one of the adopters. 
  • If there are no waiting adopters, all subscribers to this Activity receives a "cancel" event and the Activity disappears immediately.

Parameters

Name

Required

Type

Description

activityIdRequiredNumber (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityNameRequiredString

Activity name. Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

waitRequiredBoolean

Flag that enables whether to wait until the Activity is available to be adopted or not.

  • If an app or a service wants to wait until the Activity is available to be adopted, set wait to true. If the Activity is not immediately adopted, returnValue will contain true and adopted will contain false. Once the Activity is disconnected with its parent, the caller is informed of an "orphan" event and becomes the new parent of the Activity.
  • Otherwise, set wait to false. Generally returnValue will contain false with an errorCode. If the Activity does not have a parent returnValue will contain true.
  • The default value of wait is false.
subscribeRequiredBoolean

Flag that enables whether to get informed when status of the created activity has been changed or not.

  • To enable subscribe, set subscribe to true.
  • To disable subscribe, set subscribe to false.
  • The default value of subscribe is false.
detailedEventsOptionalBoolean

Flag that enables to return detailed Activity information in a subscription response. It needs to be used when subscribe is set to true.

  • To enable detailedEvents, set detailedEvents to true.
  • To disable detailedEvents, set detailedEvents to false.
  • The default value of detailedEvents is false.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
subscribedRequiredBoolean

If it is subscribed, subscribed will contain true.
If it is not subscribed, subscribed will contain false.

errorCodeOptionalNumber (int64_t)

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

adoptedOptionalBoolean

adopted indicates a successful or failed adoption.

If the app or service adopts the Activity, adopted will contain true.
If the app or service does not adopt the Activity, adopted will contain false.

Subscription Returns

Name

Required

Type

Description

activityIdRequiredNumber (uint64_t)

Created Activity ID.

eventRequiredString

Note: These events may be changed, as the activity state has been redefined.

Indicate what the created Activity just has been done. The Activity Manager will generate the following events when the corresponding requirements are met:

  • "start"
  • "cancel"
  • "stop"
  • “pause”
  • "complete”
  • “orphan”
  • “adopted”
  • "update" (available only when detailedEvents is set to true)

The following JSON object is a subscription example that shows the created activity just started:

{
    "activityId": 10813,
    "event": "start",
    "returnValue": true
}

$activityOptionalObject: Activity

Acitivity object.

subscribedRequiredBoolean

If it is subscribed, subscribed will contain true.
If it is not subscribed, subscribed will contain false.

returnValueOptionalBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.

Example

# luna-send -i -f luna://com.webos.service.activitymanager/adopt '{
  "activityId": 90,
  "wait": true,
  "subscribe": true,
  "detailedEvents": false
}'

Response:

{
  "returnValue": true,
  "subscribed": true,
  "adopted": false
}

Subscription Response: If parent of the activity did not release the activity

{
  "adopted": false,
  "returnValue": true,
  "subscribed": true
}

Subscription Response: When the activity is released and current app or service adopts the activity. Only one adopter receives this result and it becomes the parent of the activity. Other adopter candidates remain as adopter continuously. (First in, First out)

{
  "event": "orphan",
  "activityId": 90,
  "returnValue": true,
  "subscribed": true
}

Subscription Response: When the activity is transferred to another adopter.

{
  "adopted": true,
  "returnValue": true,
  "subscribed": true
}

release

Description

Allow a parent to free an Activity and notify other subscribers. The Activity is cancelled unless one of its non-parent subscribers adopts it and becomes the new parent. For a completely safe transfer, a subscribing app or service, prior to the release, should already have called the adopt method.

Parameters

Name

Required

Type

Description

activityIdRequiredNumber (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityNameRequiredString

Activity name.Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCodeOptionalNumber (int64_t)

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -a test -f luna://com.webos.service.activitymanager/release '{"activityId" : 98}'

pause

Description

Suspend the work on the specified Activity and place the Activity in pause state.

Parameters

Name

Required

Type

Description

activityIdOptionalNumber (uint64_t)

Activity ID.

Note: Either activityId or activityName is a REQUIRED field.

activityNameOptionalString

Activity name. Only the creator of the Activity can specify activityName.

Note: Either activityId or activityName is a REQUIRED field.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

If the pause method succeeds, returnValue will contain true. The method succeeds only if the Activity is in unsatisfied state.

If the pause method fails, returnValue will contain false. The method fails the Activity has ended (and is waiting for its subscribers to unsubscribe before cleaning up) or has been cancelled.

errorCodeOptionalNumber (int64_t)

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -f luna://com.webos.service.activitymanager/pause '{"activityId":58}'

getActivityInfo

Description

Gets information of Activities.

If activityId or activityName is given, getActivityInfo only returns information about that activity.

Conversely, if activityId or activityName is not given, getActivityInfo returns all undestroyed activities.

Parameters

Name

Required

Type

Description

activityIdOptionalNumber (uint64_t)

Activity ID

activityNameOptionalString

Activity name. Only the creator of the Activity can specify activityName.

subscribersOptionalBoolean
  • To return the current parent, queued adopters, and subscribers for each Activity, set subscribers to true.
  • To not return the current parent, queued adopters, and subscribers for each Activity, set subscribers to false.
detailsOptionalBoolean
  • To return detailed information for each Activity, set details to true.
  • To return brief information for each Activity, set details to false.
currentOptionalBoolean
  • To return the state of the Activity prerequisites (e.g., whether the Activity is scheduled or not, whether the trigger is invoked or not), set current to true.
  • Otherwise, set current to false.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCodeOptionalNumber (int64_t)

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

activityOptionalObject: Activity

The Activity object.

If activityId or activityName is given, getActivityInfo will contain the property.

activitiesOptionalObject array: Activity

Array with Activity objects.

If activityId or activityName is not given, getActivityInfo will contain this property.

Example

Example 1:

# luna-send -n 1 -f luna://com.webos.service.activitymanager/getActivityInfo '{
      "activityId":36,
      "current":false,
      "internal":false
  }'

Response:

{
    "activity": {
        "type": {
            "bus": "private",
            "foreground": true,
            "power": true,
            "persist": true
        },
        "name": "myactivity",
        "adopters": [],
        "callback": {
            "method": "luna://com.webos.service.test/callback"
        },
        "focused": true,
        "subscribers": [],
        "creator": {
            "serviceId": "com.webos.service.test"
        },

        "state": "waiting",
        "schedule": {
            "interval": "1d",
            "local": true,
            "lastFinished": "2015-03-20 00:37:38"
        },
        "description": "my test activity",
        "activityId": 36
    },
    "returnValue": true
}

 

Example 2:

# luna-send -n 1 -f -a "creator" luna://com.webos.service.activitymanager/getActivityInfo '{
    "current": true,
    "internal": true,
    "activityName": "sdet"
}'

Response:

{
    "activity": {
        "type": {
            "bus": "private",
            "foreground": true
        },
        "parent": {
            "appId": "creator"
        },
        "internal": {
            "m_userInitiated": false,
            "m_powerDebounce": false,
            "m_explicit": false,
            "m_released": false,
            "m_ready": true,
            "m_requeue": false,
            "m_sentCommand": "start",
            "m_intCommand": "null",
            "m_terminate": false,
            "m_initialized": true,
            "m_continuous": false,
            "m_id": 80,
            "m_extCommand": "start",
            "m_running": true,
            "m_priority": 3,
            "m_useSimpleType": true,
            "m_scheduled": true,
            "m_yielding": false,
            "m_immediate": true,
            "m_focused": false,
            "m_persistent": false,
            "m_restart": false,
            "m_ending": false,
            "m_bus": 1
        },
        "name": "sdet",
        "adopters": [],
        "focused": false,
        "subscribers": [{
            "appId": "creator"
        }],
        "creator": {
            "appId": "creator"
        },
        "state": "running",
        "description": "Test create",
        "activityId": 80
    },
    "returnValue": true
}

 

Example 3:

# luna-send -n 1 -f luna://com.webos.service.activitymanager/getActivityInfo '{
    "details":false,
    "subscribers":false,
    "current":false,
    "internal":false
}'

Response:

{
    "activities": [
        {
            "state": "queued",
            "description": "my test activity",
            "focused": false,
            "activityId": 2,
            "creator": { "serviceId": "com.webos.service.test" },
            "name": "test"
        }
    ],
    "returnValue": true
}

getManagerInfo

Description

Gets Activity Manager related information such as:

  • Activity Manager state - queued and leaked activities
  • List of activities for which power is currently locked
  • Supported requirements

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
queuesOptionalObject: InfoQueue

Queued Activity information.

requirementsOptionalObject array: InfoRequirement

Supported requirement

errorCodeOptionalNumber (int64_t)

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

# luna-send -n 1 -f luna://com.webos.service.activitymanager/getManagerInfo '{}'

Response:

{
  "queues": [
    {
      "activities": [
        { "activityId": 20, "name": "mojotempdbspace", "creator": { "serviceId": "com.webos.service.db" } },
        ...
      ]
    },
    ...
  ],
  "requirements": [
    { "name": "bootup", "type-schema": {"type": "boolean"} },
    { "name": "internet", "type-schema": {"type": "boolean"} },
    { "name": "wifi", "type-schema": {"type": "boolean"} }
  ]
}

Objects

Activity

Represent everything about an Activity-name, type, state, requirements, schedule, trigger, callback, id,creator, adopters, processes, flows, and associations. 

Name

Required

Type

Description

nameRequiredString

Activity name. Must be unique for creator. Applies to both persistent and non-persistent Activities. The create call will fail if this field is not unique unless the "replace" field is true.

descriptionRequiredString

Activity description.

typeRequiredObject: Type

Indicates how the Activity is handled. Principally, it is used to denote the Activity as either foreground or background, and whether it is continuous or not.

scheduleOptionalObject: Schedule

Time-based requirements for Activity.

triggerOptionalObject: TriggerEvent that must occur for Activity to run.
requirementsOptionalObject: Requirement

Conditions that must satisfy for Activity to run.

callbackOptionalObject: Callback

Call to invoke when Activity runs. This object should be defined when activity is needed to start immediately.

metadataOptionalObject

Opaque object the Activity Manager stores and returns in the callback parameters.

activityIdOptionalNumber (uint64_t)

Activity ID

creatorOptionalObject: Parent

NOTE: The 'creator' in Activity object can be set only by configurator.

parentOptionalObject: Parent

Activity parent

adoptersOptionalObject array: Parent

Activity adopters (parent object array)

stateOptionalString

NOTE: These states are deprecated. These will be replaced with new states in the next version.

Activity state. Property that represents current activity state with following strings:

  • init : Activity has been created and is waiting for Activity's associations and initial app and service subscriptions to be in place.
  • waiting: Activity is waiting for a trigger to fire or its scheduled time to begin running.
  • blocked: Activity is waiting for its specified Requirements to be met.
  • queued: The Activity is queued and ready to run.
  • running: The Activity is running.
  • pause: The Activity is paused.
  • cancelling: The Activity has been cancelled and waiting for potential adopters to take over as the parent.
  • cancelled: The Activity is cancelled.
  • stopping: The Activity is in the process of stopping.
  • stopped: The Activity has been stopped.
  • complete: The Activity is complete and has stopped.

Callback

The Callback object specifies a method to be called, and optionally arguments that should be passed to that method when the activity moves from 'satisfied' state to 'expiring'.

If the callback method fails::

  • For normal (non-continuous) activity: activity is moved to 'failed' state.
  • For continuous activity: activity moved to 'unsatisfied' state.

To change the behavior when callback fails, use the 'ignoreReturn' property.

Name

Required

Type

Description

methodRequiredStringCallback URI.
paramsOptionalany

Parameters to be passed to the callback method.

ignoreReturnOptionalBoolean

Keeps the activity alive when the activity callback fails. Possible values are:

  • true : Activity manager does not cancel the activity but moves it to the next step.
    • For normal (non-continuous) activity: waits for client to complete (or cancel)
    • For continuous activity: restarts activity
  • false :Activity manager moves the activity to failed state and ultimately cancels it.

Default values:

  • false : For non-continuous (normal) activity. (because backward compatibility should be maintained)
  • true : For continuous activity.

InfoActivity

Activity information

Name

Required

Type

Description

activityIdRequiredNumber (uint64_t)

Activity ID

creatorRequiredObject: InfoCreator

Indicates creator

nameRequiredString

Activity name

InfoCreator

Creator information

Name

Required

Type

Description

serviceIdRequiredString

Service ID

InfoQueue

List of Activities for which power is currently locked.

Name

Required

Type

Description

activitiesRequiredObject array: InfoActivity

Activities array

nameRequiredString

Queued status

InfoRequirement

Supported requirement information

Name

Required

Type

Description

nameOptionalString

requirement name

type-schemaOptionalObject

requirement type

Parent

The Parent (or potential parent) of an Activity specified as an app ID or service ID. The Activity Manager automatically obtains this value when the app or service invokes the create() or adopt()

Name

Required

Type

Description

appIdOptionalStringApplication ID. Either this or serviceId must be specified.
serviceIdOptionalStringService ID. Either this or appId must be specified.

Requirement

The Requirements are preconditions that the Activity Manager will ensure are met before an Activity will be run. Any number of requirements may be specified for a single Activity, and all must be met in order for the Activity to move to the satisfied state. Requirements can transition from the met state back to unmet if the condition the particular requirement is monitoring for no longer holds true.

The Requirements available on the system can be queried using getManagerInfo method.

Example :
luna-send -n 1 -f luna://com.webos.service.activitymanager/create '{
    "activity": {
        "requirements": {"bootup": true, "internet": true},
        "name": "browser-restart", "description": "", "type": {"foreground": true},
        "callback": {"method": "luna://com.webos.service.applicationmanager/launch", "params": {"id": "com.webos.app.enactbrowser"}},
        "trigger": {"method":"luna://com.webos.service.applicationmanager/getAppLifeStatus", "params": {"subscribe": true},
                      "where": {"and":[{"op": "=", "prop": "appId", "val": "com.webos.app.enactbrowser"}, {"op": "=", "prop": "status", "val":"stop"}]}}
    },
    "replace": true,
    "start": true
}'

 

Name

Required

Type

Description

bootupOptionalBoolean

bootup

internetOptionalBoolean

internet

wifiOptionalBoolean

wifi

Schedule

The Schedule object will define the time-based requirements for an Activity. If Schedule is specified, the schedule must be met before the Activity move to satisfied state.

NOTE : Some properties of Schedule may be changed.

1. Basic schedule

"schedule": {
    // Start time. Time format is a subset of ISO 8601.
    // That is, "YYYY-MM-DD HH:MM:SS" for local, or "YYYY-MM-DD HH:MM:SSZ" for UTC.
    "start": "2017-03-01 21:00:00",
}

 

2. Smart interval

Smart intervals align all Activities operating with that period to the same start times, allowing them to batch up and avoid unnecessary device wakeups, potentially saving significant amounts of power.

"schedule": {
    // Time between events, in seconds.
    // For a smart interval, the interval must be an even multiple of days,
    // or one of the following: 12h, 6h, 3h, 1h, 30m, 15m, 10m, or 5m.
    "interval": "5m"
}

 

3. Precise interval

"schedule": {
    // Specifies that the Interval should occur at the precisely specified start time, and every given interval thereafter.
    "precise": true,

    // Start time. Time format is a subset of ISO 8601.
    // That is "YYYY-MM-DD HH:MM:SS" for local, and "YYYY-MM-DD HH:MM:SSZ" for UTC.
    "start": "2017-03-01 21:00:00",

    // End time for the interval (NOTE. This does not work currently.)
    [ "end": "2017-03-01 22:00:00", ]

    // Time between events, in seconds.
    // Specifies the number of days, hours, minutes, and seconds between executions of the Activity.
    // They must be specified in order, but any can be left out.  Any interval is valid.
    "interval": "1m",
}

 

Name

Required

Type

Description

startOptionalString

start is required for basic schedue or precise interval.

endOptionalString

end time

preciseOptionalBoolean

precise is required for precise interval

intervalOptionalString

interval is required for smart or precise interval

skipOptionalBoolean

skip

localOptionalBoolean

local

relativeOptionalBoolean

relative

lastFinishedOptionalString

lastFinished

Trigger

Activities with Triggers do not become runnable until an event occurs on a subscribed method. In addition, other requirements or scheduling constraints may also need to be met before the Activity is runnable. When the Activity starts, the specified method is called with "subscribe=true", and any additional arguments the Activity creator provides. If another Activity has previously been created and started with an identical Trigger, with the same method and arguments, then the Activity Manager may utilize its existing subscription to monitor the Triggering event, unless "unique" is true in the Trigger specification.

NOTE: Key Trigger and Compare Trigger are deprecated.

1. Key Trigger is triggered when the specified key exists.

"trigger": {
    "method": "luna://com.webos.service.applicationmanager/getForegroundAppInfo",
    "params": { "subscribe": true, "extraInfo": true },
    "key": "foregroundAppInfo"
}

 

2. Compare Trigger is triggered when the specified key & value pair in compare are matched.

"trigger": {
    "method": "luna://com.webos.service.applicationmanager/getForegroundAppInfo",
    "params": { "subscribe": true },
    "compare": { "appId": "com.webos.app.enactbrowser" }
}

 

3. Where Trigger is triggered when the conditions of where clauses are satisfied.

3-1. Single Trigger

"trigger": {
    "method": "luna://com.webos.service.connectionmanager/getstatus",
    "params": { "subscribe": true },
    "where": { "prop": "isInternetConnectionAvailable", "op": "=", "val": true }
}

3-2. Multiple Trigger can be combined by 'and' or 'or'

"trigger": {
    "and": [
        {
            ....
        },
        {
            "method": "luna://com.webos.service.applicationmanager/getAppLifeStatus",
            "params": { "subscribe": true },
            "where": { "and": [
                { "op": "=", "prop": "appId", "val": "com.webos.app.enactbrowser" },
                { "op": "=", "prop": "status", "val": "close" }
            ]}
        },
        {
            ....
        },
    ]
}

 

The Activity Manager will unsubscribe all subscriptions of Triggers, if the Activity arrives 'satisfied' state, and re-subscribe Triggers when 'restarting'.

WARNING

Do NOT ignore the trigger information returned in a callback. If an error is returned to the method specified for a Trigger, then the Trigger fires immediately. This could happen if, for example, the parameters passed to the method were invalid or wrong. If the Trigger callback re-starts the Activity, i.e., in the case of a db8 watch, then the potential exists for an infinite loop. Check for errors.

NOTE. As the 'failed' state is added, if an error is returned from the Trigger method, the Activity will move to 'failed' state without calling Callback in the next version.

Keep the mutual exclusion among the "key", "compare", and "where" properties. They are incompatible with each other.

Name

Required

Type

Description

methodRequiredStringName of callback method.
paramsOptionalObjectParameters for subscription or watch.
whereOptionalObject

Single db8 where clause or array of db8 where clauses.

compareOptionalObject

Object that holds key and value properties. Trigger will query with the key and compare old value with specified value.

keyOptionalString

Key property name. Activity Manager looks for this field in callback response, i.e., "fired" from db8 watch where query results have changed.

andOptionalObject array: Trigger

The and field is used when combining multiple triggers to be combined with an 'and' condition.

orOptionalObject array: Trigger

The or field is used when combining multiple triggers to be combined with an 'or' condition.

API Error Codes Reference

Error Code

Error Text

Error Description

2No such file or directory

No such file or directory

11Operation blocked

Operation blocked

12Out of memory

Out of memory

13Permission denied

Permission denied

17File already exists

File already exists

22Invalid argument

Invalid argument

38Function not implemented

Function not implemented

-1000Internal error

Internal error

Contents