com.webos.service.intent

Note
This API has been available since API level 12.

API Summary

An intent is an abstract description of an operation to be performed. Intent manager is a native service to handle the intent.

There are two types of intent:

  • Implicit Intent : Does not specify a component
  • Explicit Intent : Specifies a component

Overview of the API

Intent manager has roles to handle intents and manage handlers.

  • Intent: An abstract description of an operation to be performed.
  • Handler: System components which can handle specific type of intents.
  • Requester: System components which want to start an intent.

When the requester calls the start API with an intent, intent manager finds the suitable handler in the handler pool. Normally, handler is an app, so intent manager calls the launch API in the SAM to launch the (handler) app. The intent object is passed to application through launch params object

Sometimes, requester wants to get result from the handler. In such case, requester should subscribe to the start API to get the subscription message from the handler. Intent manager sends subscription message when the handler calls the sendResult API.

Requester can subscribe to the result by using the subscribeResult API also.

 

Steps to support intent - application

  1. Modify appinfo.json first to support intent. Here is a simple example for enact browser. Lines highlighted in the below json code are newly added.

    $ vi /usr/palm/applications/com.webos.app.enactbrowser/appinfo.json
    {
             ....
             "mimeTypes": [                                             
                    {                                   
                            "mime": "text/html",
                            "extension": "html",                       
                            "stream": true              
                    },                          
                    {                                                  
                            "scheme": "http"            
                    },                          
                    {                                                  
                            "scheme": "https"           
                    }                           
            ],                                                         
            "intentFilters": [               
                {                               
                    "actions": ["action_url", "action_uri"],
                    "uris": ["http://youtube.com", "http://", "https://"]
                }                               
            ],

            ....
    }

  2. To apply the changes, restart the SAM module and intent manager.

    $ restart sam
    $ restart com.webos.service.intent

  3. Verify the changes:
    • On the SAM module:

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

      Response:

      {
          "appId": "com.webos.app.enactbrowser",
          "returnValue": true,
          "appInfo": {
              ....
              "intentFilters": [
                  {
                      "uris": [
                          "http://youtube.com",
                          "http://",
                          "https://"
                      ],
                      "actions": [
                          "action_url",
                          "action_uri"
                      ]
                  }
              ],
              ....
          }
      }

    • On intent manager:

      # luna-send -f -n 1 luna://com.webos.service.intent/query '{ "intent": { "action": "action_url", "uri":"http://google.com"}}'

      Response:

      {
          "returnValue": true,
          "handlers": [
              {
                  "name": "com.webos.app.enactbrowser",
                  "intentFilters": [
                      {
                          "uris": [
                              "http://youtube.com",
                              "http://",
                              "https://"
                          ],
                          "actions": [
                              "action_url",
                              "action_uri"
                          ]
                      }
                  ]
              }
          ]
      }

  4. Start 'intent' and verify the handler.

    $ luna-send -f -n 1 luna://com.webos.service.intent/start '{ "intent": { "action": "action_url", "uri":"http://google.com"}}'

    Response:

    {
        "intentId": 10,
        "returnValue": true
    }

List of intents

For a list of supported intents, see the following webOS Intents table.

Intents must be specified in the following form:

{
   "action":"{action}",
   "uri":"{uri}",
   "extra":{
      ...
   }
}

IntentActionURI (format)ExtraExamples (snippet of 'appinfo.json' file)
View URI (browser)viewhttp://{url} 

Example 1 - Ability to view all URIs starting with http and https.

"intentFilters":[
   {
      "actions":["view"],
      "uris":["http://","https://"]
   }
]

Example 2 - Ability to view the 2 URIs mentioned below.

"intentFilters":[
   {
      "actions":["view"],
      "uris":["https://google.com", "http://naver.com"]
   }
]

View map (navigation)viewgeo:// 

Example 1 - Ability to view all map locations.

"intentFilters":[
   {
      "actions":["view"],
      "uris":["geo://"]
   }
]

Example 2 - Examples of other uris:

  • geo:323482,4306480
  • geo:37.786971,-122.399677
  • geo:37.786971,-122.399677;u=35
  • geo:323482,4306480;crs=EPSG:32618;u=20
  • geo:37.786971,-122.399677;crs=Moon-2011;u=35
  • geo:0.0?q=Home

View specific page (application)

viewapp://{appId}/{path} 

Example - Ability to open specific page of settings app

"intentFilters":[
   {
      "actions":["view"],
      "uris":["app://com.palm.app.xxxx/Settings/Language"]
   }
]

Play media (video/audio)

viewfile://{absolute_path} 

Example - Ability to play specific file (works with 'mimeTypes' specified in appinfo.json file)

"intentFilters":[
   {
      "actions":["view"],
      "uris":[
         "file:///tmp/usb/sdg/sdg3/mediaIndexerContents/scan2/Miss_A.mp3"
      ]
   }
]

Methods

query

ACG: intent.operation
  • Added: API level 12

Description

Clients can get handlers by calling the API.

Parameters

Name

Required

Type

Description

intentOptionalObject: intent

Details of the intent.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed.
errorTextOptionalString

Indicates the reason for the failure of the operation.

handlersRequiredObject array: handler

Please refer the handler object in the object section.

Example

Example : See all handlers

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

Response:

{
    "returnValue": true,
    "handlers": [
        {
            "sessionId": "34117815-8721-4370-9cd3-ba74ff7349f5",
            "name": "bareapp",
            "intentFilters": [
                {
                    "actions": [
                        "action_test"
                    ]
                }
            ]
        },
        ....
        {
            "sessionId": "b51ca1c7-8d20-4ac0-87e1-62b41162d1da",
            "name": "com.webos.app.volume",
            "intentFilters": [
            ]
        }
    ]
}

Example : Explicit Intent

# luna-send -f -n 1 luna://com.webos.service.intent/query '{
   "intent":{
      "name":"bareapp"
   }
}'

Response:

{
    "returnValue": true,
    "handlers": [
        {
            "sessionId": "34117815-8721-4370-9cd3-ba74ff7349f5",
            "name": "bareapp",
            "intentFilters": [
                {
                    "actions": [
                        "action_test"
                    ]
                }
            ]
        },
        {
            "sessionId": "b51ca1c7-8d20-4ac0-87e1-62b41162d1da",
            "name": "bareapp",
            "intentFilters": [
                {
                    "actions": [
                        "action_test"
                    ]
                }
            ]
        }
    ]
}

Example : Implicit Intent

# luna-send -f -n 1 luna://com.webos.service.intent/query '{
   "intent":{
      "action":"action_test"
   }
}'

Response:

{
    "returnValue": true,
    "handlers": [
        {
            "sessionId": "34117815-8721-4370-9cd3-ba74ff7349f5",
            "name": "bareapp",
            "intentFilters": [
                {
                    "actions": [
                        "action_test"
                    ]
                }
            ]
        },
        {
            "sessionId": "b51ca1c7-8d20-4ac0-87e1-62b41162d1da",
            "name": "bareapp",
            "intentFilters": [
                {
                    "actions": [
                        "action_test"
                    ]
                }
            ]
        }
    ]
}

sendResult

ACG: intent.operation
  • Added: API level 12

Description

Enables the handlers to reply with the results.

Note: Also refer 'subscribeResult' API.

Parameters

Name

Required

Type

Description

intentIdRequiredNumber

Indicates the intent ID used in the sendResult and subscribeResult.

resultOptionalString

Indicates the result string which is provided by the handler.

intentOptionalObject: intent

Details of the intent.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed.
errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

Example : Without extra info

# luna-send -n 1 -f luna://com.webos.service.intent/sendResult '{
   "intentId":33,
   "result":"ok"
}'

Response:

{
    "returnValue": true,
    "intentId": 33
}

Example : With extra info

# luna-send -n 1 -f luna://com.webos.service.intent/sendResult '{
   "intentId":33,
   "result":"ok",
   "intent":{
      "extra":{
         "data":true
      }
   }
}'

Response:

{
    "returnValue": true,
    "intentId": 33
}

start

ACG: intent.operation
  • Added: API level 12

Description

Starts the handlers based on the intent information provided in the request payload.

Please refer 'subscribeResult' API for subscription payload.

Parameters

Name

Required

Type

Description

intentOptionalObject: intent

Details of the intent.

subscribeOptionalBoolean

Indicates if subscribed to get the notifications.

Possible values are:

  • true: Subscribed for notifications
  • false: Not subscribed

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed.
subscribedOptionalBoolean

Indicates if subscribed to get the notifications.

Possible values are:

  • true: Subscribed for notifications
  • false: Not subscribed
errorTextOptionalString

Indicates the reason for the failure of the operation.

intentIdRequiredNumber

Indicates the Intent ID.

Example

None

subscribeResult

ACG: intent.operation
  • Added: API level 12

Description

All running intents have their own 'intentId'. Of course, handlers can reply results thought 'intentId'.

Other component including requester can subscribe the results with this API.

Parameters

Name

Required

Type

Description

intentIdRequiredNumber

Indicates the intent ID.

subscribeOptionalBoolean

Indicates if subscribed to get the notifications.

Possible values are:

  • true: Subscribed for notifications
  • false: Not subscribed

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed.
subscribedOptionalString

Indicates if subscribed to get the notifications.

Possible values are:

  • true: Subscribed for notifications
  • false: Not subscribed
errorTextOptionalString

Indicates the reason for the failure of the operation.

intentIdRequiredNumber

Indicates the intent ID.

Subscription Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed.
subscribedOptionalBoolean

Indicates if subscribed to get the notifications.

Possible values are:

  • true: Subscribed for notifications
  • false: Not subscribed
errorTextOptionalString

Indicates the reason for the failure of the operation.

intentIdRequiredNumber

Indicates the intent ID which used in sendResult and subscribeResult

resultOptionalString

Indicates the result string provided by the handler.

intentOptionalObject: intent

Please refer the intent object in the object section.

fromOptionalString

Indicates the handler's luna ID.

Example

Example scenario

# luna-send -i -f luna://com.webos.service.intent/subscribeResult '{
   "intentId":14,
   "subscribe":true
}'

Response:

{
    "returnValue": true,
    "subscribed": true,
    "intentId": 14
}

Subscription response:

{
    "subscribed": true,
    "result": "ok",
    "intent": {
        "extra": {
            "data": true
        }
    },
    "from": "com.webos.lunasend-36099",
    "returnValue": true,
    "intentId": 14
}

Objects

handler

Indicates the application to handle the intent.

Name

Required

Type

Description

nameRequiredString

Indicates the handler's luna bus ID. Usually, it is application id.

Example: com.webos.service.intentmanager.

sessionIdOptionalString

Indicates the handler's session ID.

Example: navigation handler should be started under 'driver' session.

intentFiltersOptionalObject array: intentFilter

Indicates the filter for the intent.

intent

Provides details of the intent.

Name

Required

Type

Description

nameOptionalString

Indicates the handler name.

actionOptionalString

Indicates the action name.

Note: Check List of intents for supported actions and URIs.

uriOptionalString

Indicates the uri pattern list.

<scheme>://<host>:<port>/<path>

Example: https://en.wikipedia.org/wiki/File_URI_scheme

Note: Check List of intents for supported actions and URIs.

mimeTypeOptionalString

Indicates the mime type.

Possible values are:

  • video/mpeg
  • audio/mpeg
  • image/*
extraOptionalObject

Indicates the additional parameter for the handler.

intentFilter

Name

Required

Type

Description

actionsOptionalString array

Indicates the action list handled by the handler. Refer to intent object for a list of supported actions.

Note: This can be empty if handler can't handle any kinds of action.

mimeTypesOptionalString array

Indicates the mimeType list handled by the handler. Refer to intent object for a list of supported mime types.

Note: This can be empty if handler can't handle any kinds of mimeType.

urisOptionalString array

Indicates the uri list which handler can handle. Refer to intent object for a list of supported URIs.

Note: This can be empty if handler can't handle any kinds of uri.

API Error Codes Reference

Error Code

Error Text

Error Description

NoneFailed to start intent

Failed to start intent because of internal error.

NoneInvalid parameter

Invalid parameters.

NoneFailed to parse intent

Failed to parse intent because required keys do not exist.

NoneCannot find session

Cannot find session if given sessionId is not valid.

NoneCannot find handler

Cannot find handler for given intent.

None'intentId' is required parameter

Intent ID is a required parameter and must be provided.

Contents