com.webos.service.activitymanager

Note
This API has been available since API level 11.

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

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.

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.

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. 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.
subscribe	Required	Boolean	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.
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. 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
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed.
subscribed	Required	Boolean	If it is subscribed, subscribed will contain true. If it is not subscribed, subscribed 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.
adopted	Optional	Boolean	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
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: "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 }
$activity	Optional	Object: Activity	Acitivity object.
subscribed	Required	Boolean	If it is subscribed, subscribed will contain true. If it is not subscribed, subscribed will contain false.
returnValue	Optional	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed.

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
}

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.

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	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.
callback	Optional	Object: 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.
schedule	Optional	Object: 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.
trigger	Optional	Object: 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.
metadata	Optional	Object	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

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

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

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. 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.
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. To enable detailedEvents, set detailedEvents to true. To disable detailedEvents, set detailedEvents to false. The default value of detailedEvents is false.
start	Optional	Boolean	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.
replace	Optional	Boolean	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
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed.
activityId	Optional	Number (uint64_t)	Activity ID.
subscribed	Optional	Boolean	If it is subscribed, subscribed will contain true. If it is not subscribed, subscribed 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.

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: "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 }
$activity	Optional	Object: Activity	Acitivity object.
subscribed	Required	Boolean	If it is subscribed, subscribed will contain true. If it is not subscribed, subscribed will contain false.
returnValue	Optional	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed.

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. To enable unlimited, set unlimited to true. To disable unlimited, set unlimited to false. The default value of unlimited is false.

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.

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

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.

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	To evict all Activities from the background queue, set evictAll to true. To disable evictAll, set evictAll to false. The default value of evictAll is false.

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.

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	To enable priority control, set enabled to true. To disable priority control, set enabled to false. The default value of enabled is false.

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.

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 To run all activities which are in ready status, set runAll to true. To not run all activites, set runAll to false.

Name

Required

Type

Description

activityId

Optional

Number (uint64_t)

The ID of the ready activity to run.

runAll

Optional

Boolean

Run all ready Activities

To run all activities which are in ready status, set runAll to true.
To not run all activites, set runAll to false.

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.

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.

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.

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.

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	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.
details	Optional	Boolean	To return detailed information for each Activity, set details to true. To return brief information for each Activity, set details to false.
current	Optional	Boolean	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
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed.
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	To return the state of the Activity prerequisites, set current to true. Otherwise, set current to false.
internal	Required	Boolean	To include internal state information for debugging, set internal to true. Otherwise, set internal to false.

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:

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: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
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:

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. To enable subscribe, set subscribe to true. To disable subscribe, set subscribe to false. The default value of subscribe is false. 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. 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
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. If it is not subscribed, subscribed 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.

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: "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 }
subscribed	Required	Boolean	If it is subscribed, subscribed will contain true. If it is not subscribed, subscribed will contain false.
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	To return detailed information for each Activity, set details to true. To return brief information for each Activity, set details to false.
subscribers	Required	Boolean	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.
current	Required	Boolean	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.
internal	Required	Boolean	To include internal state information for debugging, set internal to true. Otherwise, set internal to false.

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. To enable subscribe, set subscribe to true. To disable subscribe, set subscribe to false. The default value of subscribe is false.
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. 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
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. "init" "waiting" "blocked" "queued" "starting" "running" "paused" "complete" "stopping" "stopped" "cancelling" "cancelled" "unknown"
subscribed	Optional	Boolean	If it is subscribed, subscribed will contain true. If it is not subscribed, subscribed will contain false.

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: "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 }
subscribed	Required	Boolean	If it is subscribed, subscribed will contain true. If it is not subscribed, subscribed will contain false.
returnValue	Optional	Boolean	If the monitor method succeeds, returnValue will contain true. If the monitor method fails, returnValue will contain false.
$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.

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.

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:

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

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:

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

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:

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

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.

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: creating created starting unsatisfied pausing paused satisfying satisfied expiring expired restarting failing failed destroying destroyed

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: 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.

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:

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
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. NOTE: If set persist as true, make sure to call cancel to destroy the Activity when the activity is no longer needed. If not, the garbage Activity keeps on DB8 and can run unintentionally. NOTE: If an Activity is located in '/etc/palm/activities', set persist as false if possible. Because configurator creates them automatically, whenever the Activity Manager starts.
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. It is recommended that do not keep subscription of the parent rather than set explicit as true.
continuous	Optional	Boolean	Activity does not have a well defined ending point and could run indefinitely. Activity that satisfies all requirements calls a Callback and moves to the expired state. If continuous is true, the Activity moves to unsatisfied state as soon as the response of the Callback is received. At this point, if all requirements of the Activity are still satisfied, the Activity can loop quickly activity cycles. Therefore, continuous is very useful, but it should be used very carefully. If not, the Activity Manager may detect infinite loops and move the activity to failed state.
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
-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