Note
This API has been available since API level 11.
This API has been available since API level 11.
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.
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
addFocus
ACG: activity.operation
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Add a focus to the target Activity and remove a focus from source Activity. If a focus is added successfully, addFocus will generate "focus" events for subscribers of the target Activity.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | The ID of source Activity to remove a focus from. Either this, or activityName is required. |
| activityName | Required | String | The Name of source Activity to remove a focus from. Either this, or activityID is required. Only the creator of the Activity can specify activityName. |
| targetActivityId | Required | Number (uint64_t) | The ID of target activity to add a focus to. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the addFocus method succeeds, returnValue will contain true. If the addFocus method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
Example
Example code
Example response for a successful call:
# luna-send -n 1 -f luna://com.webos.service.activitymanager/addFocus '{ "activityId":36, "targetActivityId":38 }'
{
"returnValue": true
}
# luna-send -n 1 -a "creator" -f luna://com.webos.service.activitymanager/addFocus '{ "activityName":"test1", "targetActivityId":38 }'
{
"returnValue": true
}
Example response for a failed call:
{
"errorCode": 2,
"returnValue": false,
"errorText": "activityId not found"
}
adopt
ACG: activity.operation
- Added:
API level 11
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 |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID. Note: Either activityId or activityName is a REQUIRED field. |
| activityName | Required | String | Activity name. Only the creator of the Activity can specify activityName. Note: Either activityId or activityName is a REQUIRED field. |
| wait | Required | Boolean | Flag that enables whether to wait until the Activity is available to be adopted or not.
|
| subscribe | Required | Boolean | Flag that enables whether to get informed when status of the created activity has been changed or not.
|
| detailedEvents | Optional | Boolean | Flag that enables to return detailed Activity information in a subscription response. It needs to be used when subscribe is set to true.
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| subscribed | Required | Boolean | If it is subscribed, subscribed will contain true. |
| errorCode | Optional | Number (int64_t) | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
| adopted | Optional | Boolean | adopted indicates a successful or failed adoption. If the app or service adopts the Activity, adopted will contain true. |
Subscription Returns
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Created Activity ID. |
| event | Required | String | 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:
The following JSON object is a subscription example that shows the created activity just started: { |
| $activity | Optional | Object: Activity | Acitivity object. |
| subscribed | Required | Boolean | If it is subscribed, subscribed will contain true. |
| returnValue | Optional | Boolean | Indicates the status of operation. Possible values are:
|
Example
Example code
# 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
}
callback/scheduledwakeup
ACG: activity.wakeup
- Added:
API level 26
Description
A callback method indicating the scheduled time of the activities.
Note: Do not use this method in your application or service. This method is only called by sleepd (com.webos.service.alarm) service.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the scheduledwakeup method succeeds, returnValue will contain true. If the scheduledwakeup method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/callback/scheduledwakeup '{}'
cancel
ACG: activity.operation
- Added:
API level 11
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 |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID. Note: Either activityId or activityName is a REQUIRED field. |
| activityName | Required | String | 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 |
|---|---|---|---|
| returnValue | Required | Boolean | If the cancel method succeeds, returnValue will contain true. If the cancel method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/cancel '{"activityId" : 93}'
complete
ACG: activity.operation
- Added:
API level 11
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 |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID. Note: Either activityId or activityName is a REQUIRED field. |
| activityName | Required | String | Activity name.Only the creator of the Activity can specify activityName. Note: Either activityId or activityName is a REQUIRED field. |
| restart | Optional | Boolean |
Note: If restart is false, this is equivalent to cancel. Therefore, it is recommended to always set restart to true to avoid confusion. |
| callback | Optional | Object: Callback | Callback to use when the specified Activity is restarted.
|
| schedule | Optional | Object: Schedule | Schedule to use when Activity is restarted.
|
| trigger | Optional | Object: Trigger | Trigger to use when the specified Activity is restarted.
|
| metadata | Optional | Object | Opaque object the Activity Manager stores and returns in the callback parameters.
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number (int64_t) | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
Example code
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
}
create
ACG: activity.operation
- Added:
API level 11
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 |
|---|---|---|---|
| activity | Required | Object: Activity | Activity object. |
| subscribe | Optional | Boolean | Flag that enables whether to subscribe or not.
|
| detailedEvents | Optional | Boolean | Flag that enables to return detailed Activity information in a subscription response. It needs to be used when subscribe is set to true.
|
| start | Optional | Boolean | Start Activity immediately flag.
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. |
| replace | Optional | Boolean |
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 |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| activityId | Optional | Number (uint64_t) | Activity ID. |
| subscribed | Optional | Boolean | If it is subscribed, subscribed will contain true. |
| errorCode | Optional | Number (int64_t) | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Subscription Returns
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Created Activity ID. You could get a subscription when there's status updates. |
| event | Required | String | 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:
The following JSON object is a subscription example that shows the created activity just started: { |
| $activity | Optional | Object: Activity | Acitivity object. |
| subscribed | Required | Boolean | If it is subscribed, subscribed will contain true. |
| returnValue | Optional | Boolean | Indicates the status of operation. Possible values are:
|
Example
Example code
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
}
devel/concurrency
ACG: activity.operation
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Set background Activity concurrency level for the Activity Manager.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| level | Required | Number (uint32_t) | Number of concurrent background Activities. |
| unlimited | Optional | Boolean | Set to true to allow unlimited amount of concurrent background Activities.
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the concurrency method succeeds, returnValue will contain true. If the concurrency method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/devel/concurrency '{"level":1}'
devel/evict
ACG: activity.operation
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Evict one or all Activities from the background queue.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Optional | Number (uint64_t) | The ID of the background activity to evict. |
| evictAll | Optional | Boolean |
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnVaule | Required | String | If the evict method succeeds, returnValue will containtrue. If the evict method fails, returnValue will contain false. |
| errorCode | Optional | String | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/devel/evict '{"activityId":45}'
devel/priorityControl
ACG: activity.operation
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Enable or disable priority control.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| enabled | Required | Boolean |
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the priorityControl method succeeds, returnValue will contain true. If the priorityControl method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/devel/priorityControl '{"enabled":true}'
devel/run
ACG: activity.operation
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Run one or all Activities that are in ready queue.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Optional | Number (uint64_t) | The ID of the ready activity to run. |
| runAll | Optional | Boolean | Run all ready Activities
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the run method succeeds, returnValue will contain true. If the run method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/devel/run '{"activityId":2}'
disable
ACG: activity.operation
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Disable scheduling new Activities.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the disable method succeeds, returnValue will contain true. If the disable method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
Example
Example code
Example response for a successful call:
# luna-send -n 1 -f luna://com.webos.service.activitymanager/disable '{}'
{
"returnValue": true
}
Example response for a failed call:
# luna-send -n 1 -f -P luna://com.webos.service.activitymanager/disable '{}'
{
"errorCode": 13,
"returnValue": false,
"errorText": "Only callers on the private bus are allowed to enable or disable Activity dispatch"
}
enable
ACG: activity.operation
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Enable scheduling new Activities.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the enable method succeeds, returnValue will contain true. If the enable method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
Example
Example code
Example response for a successful call:
# luna-send -n 1 -f luna://com.webos.service.activitymanager/enable '{}'
{
"returnValue": true
}
Example response for a failed call:
# luna-send -n 1 -f -P luna://com.webos.service.activitymanager/enable '{}'
{
"errorCode": 13,
"returnValue": false,
"errorText": "Only callers on the private bus are allowed to enable or disable Activity dispatch"
}
focus
ACG: activity.operation
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Focus to target Activity. All currently focused Activities will be lost their focus. If requester is not privileged, this call will fail. Appropriate "focused" and "unfocused" events will be generated to subscribers of Activities which gain or lose focus.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | ID of the activity to grant a focus to. |
| activityName | Required | String | Activity name, required if activityId is not provided. Only the creator of the Activity can specify activityName. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the focus method succeeds, returnValue will contain true. If the focus method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
Example
Example code
Example response for a successful call:
# luna-send -n 1 -f luna://com.webos.service.activitymanager/focus '{"activityId":36}'
{
"returnValue": true
}
Example response for a failed call:
{
"errorCode": 2,
"returnValue": false,
"errorText": "activityId not found"
}
getActivityInfo
ACG: activity.query
- Added:
API level 11
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 |
|---|---|---|---|
| activityId | Optional | Number (uint64_t) | Activity ID |
| activityName | Optional | String | Activity name. Only the creator of the Activity can specify activityName. |
| subscribers | Optional | Boolean |
|
| details | Optional | Boolean |
|
| current | Optional | Boolean |
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number (int64_t) | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
| activity | Optional | Object: Activity | The Activity object. If activityId or activityName is given, getActivityInfo will contain the property. |
| activities | Optional | Object array: Activity | Array with Activity objects. If activityId or activityName is not given, getActivityInfo will contain this property. |
Example
Example code
Example 1:
# luna-send -n 1 -f luna://com.webos.service.activitymanager/getActivityInfo '{
"activityId":36,
"current":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,
"activityName": "sdet"
}'
Response:
{
"activity": {
"type": {
"bus": "private",
"foreground": true
},
"parent": {
"appId": "creator"
},
"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
}'
Response:
{
"activities": [
{
"state": "queued",
"description": "my test activity",
"focused": false,
"activityId": 2,
"creator": { "serviceId": "com.webos.service.test" },
"name": "test"
}
],
"returnValue": true
}
getDetails
ACG: activity.query
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Gets details of an activity.
Note: Use the 'getActivityInfo' method instead.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID. Either this, or activityName is required. |
| activityName | Required | String | Activity name. Either this, or activityId is required. Only the creator of the Activity can specify activityName. |
| current | Required | Boolean |
|
| internal | Required | Boolean |
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the getDetails method succeeds, returnValue will contain true. If the getDetails method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
| activity | Optional | Object: Activity | The Activity object. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/getDetails '{
"activityId":36,
"current":false,
"internal":false
}'
Example response for a successful call:
{
"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 response for a failed call:
{
"errorCode": 2,
"returnValue": false,
"errorText": "activityId not found"
}
# luna-send -i -f -a "creator" luna://com.webos.service.activitymanager/create '{
"start": true,
"activity": {
"type": {
"foreground": true
},
"name": "sdet",
"description": "Test create"
},
"subscribe": true,
"detailedEvents": true,
"replace": true
}'
Example response for a successful call:
# luna-send -n 1 -f -a "creator" luna://com.webos.service.activitymanager/getDetails '{
"current": true,
"internal": true,
"activityName": "sdet"
}'
{
"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 response for a failed call:
# luna-send -n 1 -f luna://com.webos.service.activitymanager/getDetails '{
"current": true,
"internal": true,
"activityName": "sdet"
}'
{
"errorCode": 2,
"errorText": "Activity name/creator pair not found",
"returnValue": false
}
getManagerInfo
ACG: activity.query
- Added:
API level 11
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 |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| queues | Optional | Object: InfoQueue | Queued Activity information. |
| requirements | Optional | Object array: InfoRequirement | Supported requirement |
| errorCode | Optional | Number (int64_t) | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details. |
Example
Example code
# 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"} }
]
}
info
ACG: activity.query
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Get Activity Manager related information such as Activity Manager state - queued and leaked Activities, list of Activities for which power is currently locked, and supported requirements.
Note: Use the 'getManagerInfo' method instead.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the info method succeeds, returnValue will contain true. If the info method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
| queues | Optional | Object array: InfoQueue | Queued Activity information. |
| requirements | Optional | Object: InfoResourceManager | Supported requirement |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/info '{}'
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"} }
]
}
join
ACG: activity.operation
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Subscribe to receive events from the specified Activity.
Note: Use the 'am-monitor' tool instead.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID. Either this, or activityName is required. |
| activityName | Required | String | Activity name. Either this, or activityId is required. Only the creator of the Activity can specify activityName. |
| subscribe | Required | Boolean | Flag that enables whether to subscribe or not.
Note. This parameter must be true for this call to succeed. |
| detailedEvent | Optional | Boolean | Flag that enables to return detailed Activity information in a subscription response. It needs to be used when subscribe is set to true.
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the join method succeeds, returnValue will contain true. If the join method fails, returnValue will contain false. |
| subscribed | Required | Boolean | If it is subscribed, subscribed will contain true. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
Subscription Returns
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID. |
| event | Required | String | 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:
The following JSON object is a subscription example that shows the created activity just started: { |
| subscribed | Required | Boolean | If it is subscribed, subscribed will contain true. |
| returnValue | Optional | Boolean | If the join method succeeds, returnValue will contain true. If the join method fails, returnValue will contain false. |
Example
Example code
# luna-send -i -f luna://com.webos.service.activitymanager/join '{
"activityId":36,
"subscribe":true
}'
list
ACG: activity.query
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
List Activities that are in running or waiting state.
Note: Use the 'getActivityInfo' method instead.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| details | Required | Boolean |
|
| subscribers | Required | Boolean |
|
| current | Required | Boolean |
|
| internal | Required | Boolean |
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the list method succeeds, returnValue will contain true. If the list method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
| activities | Optional | Object: Activity | Array with Activity objects. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/list '{
"details":false,
"subscribers":false,
"current":false,
"internal":false
}'
Example response for a successful call:
{
"activities": [
{
"state": "queued",
"description": "my test activity",
"focused": false,
"activityId": 2,
"creator": { "serviceId": "com.webos.service.test" },
"name": "test"
}
],
"returnValue": true
}
Example response for a failed call:
{
"errorCode": 22,
"returnValue": false,
"errorText": "'internal flag' must be specified"
}
monitor
ACG: activity.query
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Return a current status of the specified Activity. If the caller chooses to subscribe, the method returns the Activity's state when it is changed.
Note: Use the 'am-monitor' tool instead.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID. Either this, or activityName is required. |
| activityName | Required | String | Activity name. Either this, or activityId is required. Only the creator of the Activity can specify activityName. |
| subscribe | Optional | Boolean | Flag that enables whether to subscribe activity changes or not.
|
| detailedEvents | Optional | Boolean | Flag that enables to return detailed Activity information in a subscription response. It needs to be used when subscribe is set to true.
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the monitor method succeeds, returnValue will contain true. If the monitor method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
| state | Optional | String | NOTE: These states are deprecated. These will be replaced with new states in the next version. Activity state. One of the followings returns as an Activity state.
|
| subscribed | Optional | Boolean | If it is subscribed, subscribed will contain true. |
Subscription Returns
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID. |
| event | Required | String | 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:
The following JSON object is a subscription example that shows the created activity just started: { |
| subscribed | Required | Boolean | If it is subscribed, subscribed will contain true. |
| returnValue | Optional | Boolean | If the monitor method succeeds, returnValue will contain true. |
| $activity | Optional | Object: Activity | Activity object. |
Example
Example code
# luna-send -i -f luna://com.webos.service.activitymanager/monitor '{
"activityId":36,
"subscribe":true,
"detailedEvents":true
}'
Example response for a successful call:
{
"state": "waiting",
"returnValue": true,
"subscribed": true
}
Example response for a failed call:
{
"errorCode": 2,
"returnValue": false,
"errorText": "activityId not found"
}
pause
ACG: activity.operation
- Added:
API level 11
Description
Suspend the work on the specified Activity and place the Activity in pause state.
NOTE: An activity can be paused only if it is in the unsatisfied state. Use the getActivityInfo method to check the state of an activity.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Optional | Number (uint64_t) | Activity ID. Note: Either activityId or activityName is a REQUIRED field. |
| activityName | Optional | String | 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 |
|---|---|---|---|
| returnValue | Required | Boolean | 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. |
| errorCode | Optional | Number (int64_t) | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
Example code
Create activity
# luna-send -f -i luna://com.webos.service.activitymanager/create '{
"activity": {
"description": "","name": "test activity",
"trigger": {
"method": "luna://com.webos.service.config/getConfigs",
"params": {"configNames": ["com.webos.service.activitymanager.p2test.trigger"],"subscribe": true},
"where": {"op":"=","prop":["configs","com.webos.service.activitymanager.p2test.trigger"],"val":true}
},"type": {"foreground": true}
},"replace": true,"start": true, "subscribe":true
}'
Response:
{
"subscribed": true,
"activityId": 11,
"returnValue": true
}
Pause activity
# luna-send -n 1 -f luna://com.webos.service.activitymanager/pause '{"activityId": 11}'
Response:
{
"returnValue": true
}
release
ACG: activity.operation
- Added:
API level 11
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 |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID. Note: Either activityId or activityName is a REQUIRED field. |
| activityName | Required | String | 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 |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number (int64_t) | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
Example code
# luna-send -n 1 -a test -f luna://com.webos.service.activitymanager/release '{"activityId" : 98}'
start
ACG: activity.operation
- Added:
API level 11
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 |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID. Note: Either activityId or activityName is a REQUIRED field. |
| activityName | Required | String | 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 |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number (int64_t) | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/start '{"activityId" : 93}'
stop
ACG: activity.operation
- Added:
API level 11
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 |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID. Note: Either activityId or activityName is a REQUIRED field. |
| activityName | Required | String | 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 |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number (int64_t) | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/stop '{"activityId" : 95}'
unfocus
ACG: activity.operation
Retired
- Added:
API level 23 - Deprecated:
API level 23 - Retired:
API level 23
Description
Remove a focus from the specified Activity.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | ID of the activity to remove focus from |
| activityName | Required | String | Activity name, required if activityId is not provided. Only the creator of the Activity can specify activityName. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | If the unfocus method succeeds, returnValue will contain true. If the unfocus method fails, returnValue will contain false. |
| errorCode | Optional | Number (int64_t) | errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details. |
| errorText | Optional | String | errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.activitymanager/unfocus '{"activityId":36}'
Example response for a successful call:
{
"returnValue": true
}
Example response for a failed call:
{
"errorCode": 2,
"returnValue": false,
"errorText": "activityId not found"
}
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 |
|---|---|---|---|
| name | Required | String | 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. |
| description | Required | String | Activity description. |
| type | Required | Object: 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. |
| schedule | Optional | Object: Schedule | Time-based requirements for Activity. |
| trigger | Optional | Object: Trigger | Event that must occur for Activity to run. |
| requirements | Optional | Object: Requirement | Conditions that must satisfy for Activity to run. |
| callback | Optional | Object: Callback | Call to invoke when Activity runs. This object should be defined when activity is needed to start immediately. |
| metadata | Optional | Object | Opaque object the Activity Manager stores and returns in the callback parameters. |
| activityId | Optional | Number (uint64_t) | Activity ID |
| creator | Optional | Object: Parent | NOTE: The 'creator' in Activity object can be set only by configurator. |
| parent | Optional | Object: Parent | Activity parent |
| adopters | Optional | Object array: Parent | Activity adopters (parent object array) |
| state | Optional | String | Activity state. Property that represents current activity state with following strings:
|
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 |
|---|---|---|---|
| method | Required | String | Callback URI. |
| params | Optional | any | Parameters to be passed to the callback method. |
| ignoreReturn | Optional | Boolean | Keeps the activity alive when the activity callback fails. Possible values are:
Default values:
|
InfoActivity
Activity information
Name | Required | Type | Description |
|---|---|---|---|
| activityId | Required | Number (uint64_t) | Activity ID |
| creator | Required | Object: InfoCreator | Indicates creator |
| name | Required | String | Activity name |
InfoCreator
Creator information
Name | Required | Type | Description |
|---|---|---|---|
| serviceId | Required | String | Service ID |
InfoQueue
List of Activities for which power is currently locked.
Name | Required | Type | Description |
|---|---|---|---|
| activities | Required | Object array: InfoActivity | Activities array |
| name | Required | String | Queued status |
InfoRequirement
Supported requirement information
Name | Required | Type | Description |
|---|---|---|---|
| name | Optional | String | requirement name |
| type-schema | Optional | Object | 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 |
|---|---|---|---|
| appId | Optional | String | Application ID. Either this or serviceId must be specified. |
| serviceId | Optional | String | Service 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 |
|---|---|---|---|
| bootup | Optional | Boolean | bootup |
| internet | Optional | Boolean | internet |
| wifi | Optional | Boolean | 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 |
|---|---|---|---|
| start | Optional | String | start is required for basic schedue or precise interval. |
| end | Optional | String | end time |
| precise | Optional | Boolean | precise is required for precise interval |
| interval | Optional | String | interval is required for smart or precise interval |
| skip | Optional | Boolean | skip |
| local | Optional | Boolean | local |
| relative | Optional | Boolean | relative |
| lastFinished | Optional | String | 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 |
|---|---|---|---|
| method | Required | String | Name of callback method. |
| params | Optional | Object | Parameters for subscription or watch. |
| where | Optional | Object | Single db8 where clause or array of db8 where clauses. |
| compare | Optional | Object | Object that holds key and value properties. Trigger will query with the key and compare old value with specified value. |
| key | Optional | String | Key property name. Activity Manager looks for this field in callback response, i.e., "fired" from db8 watch where query results have changed. |
| and | Optional | Object array: Trigger | The and field is used when combining multiple triggers to be combined with an 'and' condition. |
| or | Optional | Object array: Trigger | The or field is used when combining multiple triggers to be combined with an 'or' condition. |
Type
Indicate how the Activity is handled.
Forground or Background
Default attributes are associated with background and foreground Activities:
Foreground Activities are high priority and immediate- They cannot be queued and begin running when their prerequisites are met.
Background Activities are low priority and not immediate- They are runnable, but queued until necessary resources become available.
Whether an activity is foreground or background should only be set once. The default is foreground. If your app specifies foreground or background, do NOT set the advanced attributes like "immediate" and "priority". If you set them, the Activity Manager will NOT create the Activity. If you do not set either foreground or background, then you MUST set "immediate" and "priority".
NOTE. Do not use background. If background is set, the Activity may not run at all.
Persistent Activity
If "persist" is true, the Activity continues across device reboots. These Activities are atomically updated and re-scheduled across version updates and device or services crashes. However, note that the Activity Manager does not have any visibility into what your activity is actually doing, so if your app is in the middle of doing something in response to a fired activity, the Activity Manager has no awareness of that. In other words, the state of an activity, such as "paused", is not saved; instead, what happens is that activity specifications are reloaded as if you had just called "create" for it.
Explicit Activity
If "explicit" is true, the Activity can only be terminated with a stop, cancel, or complete call. If the parent of an explicit Activity unsubscribes, and no other adopter is available, then, instead of being cancelled (the default) the Activity is moved back to the ready state and its callback is invoked.
Schema
Note: All fields are optional, but if you do not set "foreground" or "background", then you must set "immediate" and "priority".
Name | Required | Type | Description |
|---|---|---|---|
| foreground | Optional | Boolean | Activity runs in the foreground and starts running when its prerequisites are met. Set either this or immediate as true. |
| background | Optional | Boolean | Not currently used. |
| immediate | Optional | Boolean | Activity should run immediately. Set either this or foreground as true. |
| priority | Optional | String | Not currently used. |
| userInitiated | Optional | Boolean | Not currently used. |
| persist | Optional | Boolean | Stores Activity state in db so it can span reboots, loss of service, or updates. |
| explicit | Optional | Boolean | Activity with a parent is canceled when the subscription of the parent is unsubscribed. However, if explicit is true, the activity is not canceled. |
| continuous | Optional | Boolean | Activity does not have a well defined ending point and could run indefinitely. |
| power | Optional | Boolean | Activity requires device remain powered while it is running. |
| powerDebounce | Optional | Boolean | Events associated with this Activity are due to complete shortly. Set this flag to keep the device from having to suspend/restart in the meantime. |
API Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| -1990 | json: error parsing prop name at | It indicates that json parsing error: json: error parsing prop name |
| -1000 | Internal error | Internal error |
| 2 | No such file or directory | No such file or directory |
| 11 | Operation blocked | Operation blocked |
| 12 | Out of memory | Out of memory |
| 13 | Permission denied | Permission denied |
| 17 | File already exists | File already exists |
| 22 | Invalid argument | Invalid argument |
| 38 | Function not implemented | Function not implemented |