com.webos.service.intent

Note
com.webos.service.intent is available since webOS OSE 2.8.0.

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

    $ 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

IntentAction and URIExamples (snippet of 'appinfo.json' file)
View URI (browser)
  • action: view
  • uri (format): http://

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)
  • action: view
  • uri (format): geo://

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

Methods

query

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

# 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": [
            ]
        }
    ]
}

# luna-send -f -n 1 luna://com.webos.service.intent/query '{
   "sessionId":"b51ca1c7-8d20-4ac0-87e1-62b41162d1da"
}'

Response:

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

# 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"
                    ]
                }
            ]
        }
    ]
}

# 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"
                    ]
                }
            ]
        }
    ]
}

# luna-send -f -n 1 luna://com.webos.service.intent/query '{
   "sessionId" : "34117815-8721-4370-9cd3-ba74ff7349f5",
   "intent": { "action": "action_test"}
}'

Response:

{
    "returnValue": true,
    "handlers": [
        {
            "sessionId": "34117815-8721-4370-9cd3-ba74ff7349f5",
            "name": "bareapp",
            "intentFilters": [
                {
                    "actions": [
                        "action_test"
                    ]
                }
            ]
        }
    ]
}

start

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

# luna-send -n 1 -f luna://com.webos.service.intent/start '{
   "sessionId": "34117815-8721-4370-9cd3-ba74ff7349f5",
   "intent": { "action": "action_test" }
}'

Response:

{
   "intentId": 28,
   "returnValue": true,
   "sessionId": "34117815-8721-4370-9cd3-ba74ff7349f5"
}

# luna-send -i -f luna://com.webos.service.intent/start '{
   "sessionId": "34117815-8721-4370-9cd3-ba74ff7349f5",
   "intent": { "action": "action_test" },
   "subscribe": true
}'

Response:

{
   "subscribed": true,
   "intentId": 14,
   "returnValue": true,
   "sessionId": "34117815-8721-4370-9cd3-ba74ff7349f5"
}

Subscription Response:

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

subscribeResult

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

# 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
}

sendResult

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

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

Response:

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

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

Response:

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

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.

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.

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.

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