com.webos.service.unifiedsearch

API Summary

Searches various items (intents) by using keyword.

Overview of the API

Unified search service handles various search targets and allows to find it's items.

Note: This service works tightly with the com.webos.service.intent service.

 

Search Targets

  • Application: Search by title
     
  • Application contents: Search by string mapping what app has specified (e.g. Settings). See the "Configuring Application Contents Search" section below.
    Note: Currently, only supports "web" type applications that follow the webOs i18n structure. 
     
  • Plugins: Search by plugin (e.g. audio, video, image, contact) 

Note: The service has internal database (sqlite3 FTS3) to index items of application and application contents. For plugins, the service generally searches items from the database (DB8) directly.

 

Configuring Application Contents Search

To search within the contents of an app, you need to:.

  1. Create a mapping JSON file. Check below example.

    search.json

    {
        "items": [{
            "path": "/..../....",    <------------- intent path (search key = uri + path)
            "extra": { ...  },       <------------- extra field of intent (optional)
            "labels": [              <------------- list of resource key
                "Language",
                ...
            ]
        }, ...]
    }

  2. In the appinfo.json file, specify the path of the mapping JSON file and the intentFilters.

    appinfo.json

    {
       "....",
       "searchIndex":"search.json",    <------------- mapping JSON file
       "intentFilters":[
          {
             "actions":[
                "view"
             ],
             "uris":[
                "app://$APP_ID$"
             ]
          }
       ],
       "...."
    }

  • resources/ilibmanifest.json : will read '*/strings.json' on 'files' array.

  • resources/*/strings.json : will load entire key:value into the sqlite3 FTS database.

Since the search API returns the search result as "Intent"s, the app should be able to handle the intent also.

The parameters will come as part of "webOSSystem.launchParams". You can use this to move app page to show the searched content. For example:

var params = JSON.parse(webOSSystem.launchParams);
params.parsedUri.path // <--- what you created on items's path in search.json
params.extra                // (optional) items's extra in search.json

 


Developing plugins

We support the C++ implementation only. Please refer "./plugins/media" as a  plugin template first.

To implement yours, add "com.webos.service.unifiedsearch" to DEPENDS of your component recipe file.
And place the result shared object (.so) file on /usr/lib/plugins/unifiedsearch folder.

The unified search core has following classes to implement plugin.
You need to inherit at least 3 classes (bold items), and need to implement virtual functions.

  • Object
    • SearchItem (.h) : a common data format to save/load items
    • Intent (.h) : a format to handle intent, and also display the items on screen
  • Controller
    • LunaClient (.h) : to access LS2 as com.webos.service.unifiedsearch contact
    • Category (.h) : a set of item, generating "Intent" from "SearchItem"
    • DataSource (.h) : item store, store/search the "SearchItem" internally
  • Bridge
    • SearchSet (.h) : have a DataSource and multiple Category
    • Plugin (.h) : pass a SearchSet to the unified search service

- Plugin workflow
plugin workflow

- Implementation steps

  1. Inherit & implement DataSource class
    • override "search" function: search your datasource(e.g. DB8) and create SearchItem vector & return it by using callback.
      • Should return all category items that matched with 'searchKey' as async
        (if you handle multiple categories on your plugin)
      • The callback: function<void(string, vector<SearchItemPtr>)>
  2. Inherit & implement Category class
    • override "generateIntent" function to convert SearchItem to Intent
      • Generally, you will set 'Action', 'URI' and 'Display' on this stage.
  3. Inherit & implement Plugin class
    • create a DataSource and categories
    • create a SearchSet with the DataSource and add created categories
    • override "getSearchSet" to return upper SearchSet
    • create 'extern "C" Plugin* create_plugin()' function to return a pointer of your Plugin (as singleton)
       

- Using LunaClient class to easy LS2 implementation

  1. Inherit & implement LunaClient class
    • It will use the context of 'com.webos.service.unifiedsearch'.
      • So if you want to connect LS2 as another context, please re-implement your own LS2 class.
      • And also, if you want to connect another ACG group, please contact 'jb.seo@lge.com' to update client permissions.
    • Create a function to get your data
      • Use follow function to call, implement as async
        LunaClient::call(string method, string payload, function<bool(LSMessage *message)> cb, bool subscribe)
         

- About the Async implementation

  • The unifiedsearch's search API will response after all data sources' search function were done.
    Because it requires some async targets (e.g. LS2)
  • It's designed 
    1. passing shared_ptr of some 'Task' which has the callback to the lambda function as capture
    2. because of lambda holds the shared_ptr, it will keep the Task until the function ended
    3. and if all lambda functions are done, the Task will be destroyed.
    4. On the destructor of Task, it will call the callback.

Methods

search

Description

Searches with keyword and return intents of items.

Note: Returning intent can be implicit or explicit intent and have display property to show this on screen.

Parameters

Name

Required

Type

Description

keyRequiredString

Indicates the keyword to find items.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Method execution is successful
  • false: Method executed with errors. Check the errorCode and errorText for details.
resultsOptionalObject array: groupedIntents

Indicates the results that are grouped intents by categories.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the Error Codes section for more details.

errorCodeOptionalNumber

The error code for the failed operation.

Error Codes Reference

Error Code

Error Text

Error Description

101The 'key' isn't specified.

The 'key' does not exist in the request payload.

102The 'key' is empty or too short. (needs >= 2 bytes)

Need to type more than 2 bytes on 'key'.

Example

# luna-send -n 1 -f luna://com.webos.service.unifiedsearch/search '{"key":"pro"}'

Response:

{
   "results":[
      {
         "items":[
            {
               "intent":{
                  "action":"view",
                  "uri":"app://com.webos.app.avn.settings/Settings/Profiles"
               },
               "display":{
                  "title":"Profiles",
                  "icon":"/usr/palm/applications/com.webos.app.avn.settings/icon.png"
               }
            }
         ],
         "categoryId":"com.webos.app.avn.settings"
      },
      {
         "items":[
            {
               "intent":{
                  "name":"com.webos.app.androidauto"
               },
               "display":{
                  "title":"Android Auto Projection",
                  "icon":"/usr/palm/applications/com.webos.app.androidauto/icon.png"
               }
            }
         ],
         "categoryId":"sam.apps"
      }
   ],
   "returnValue":true
}

getCategories

Description

Gets an ordered list of enabled and disabled categories.

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Method execution is successful
  • false: Method executed with errors. Check the errorCode and errorText for details.
enabledRequiredObject array: category

Indicates the ordered array of enabled categories.

disabledRequiredObject array: category

Indicates the array of disabled categories.

Example

Get list of categories

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

Response:

{
   "disabled":[
      {
         "id":"com.webos.app.avn.settings",
         "name":"Enact AVN Settings"
      }
   ],
   "enabled":[
      {
         "id":"mediaindexer.audio",
         "name":"Audio Files"
      },
      {
         "id":"sam.apps",
         "name":"Applications"
      }
   ],
   "returnValue":true
}

updateCategory

Description

Allows enabling or disabling of a category and change the order of the category.

Parameters

Name

Required

Type

Description

idRequiredString

Specifies the category to be updated.

enabledOptionalBoolean

Indicates if the category is enabled.

Possible values are:

  • true: The category is enabled
  • false: the category is disabled
rankOptionalNumber

Indicates the position in which the specific category is returned by the getCategories() API.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

  • true: Method execution is successful
  • false: Method executed with errors. Check the errorCode and errorText for details..
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

Error Codes Reference

Error Code

Error Text

Error Description

201The 'id' isn't specified.

The ID is a mandatory parameter. It must be specified.

202Needs to add at least one of 'rank' or 'enabled'.

Updating category means change rank or enable/disable. So, you should add one of them.

203Needs 'rank' if its enabled.

When you 'enable' the category, you should set 'rank' to order.

204Shouldn't insert 'rank' when its disabled.

When it goes disable, the 'rank' is useless.

205Internal database error.

Failed to update the internal database.

Example

Change rank of a category and verify in the category list

1. Change the rank of a category.

# luna-send -n 1 -f luna://com.webos.service.unifiedsearch/updateCategory '{
    "id":"com.webos.app.avn.settings",
    "rank":1
}'

Response:

{
    "returnValue": false
}

 

2. Get the list of categories.

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

Response:

{
   "disabled":[
      
   ],
   "enabled":[
      {
         "id":"com.webos.app.avn.settings",
         "name":"Enact AVN Settings"
      },
      {
         "id":"mediaindexer.audio",
         "name":"Audio Files"
      },
      {
         "id":"sam.apps",
         "name":"Applications"
      }
   ],
   "returnValue":true
}

Disable a category and verify in the category list

1. Disable a category.

# luna-send -n 1 -f luna://com.webos.service.unifiedsearch/updateCategory '{
    "id":"com.webos.app.avn.settings",
    "enabled":false
}'

Response:

{
    "returnValue": false
}

 

2. Get the list of categories.

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

Response:

{
   "disabled":[
      {
         "id":"com.webos.app.avn.settings",
         "name":"Enact AVN Settings"
      }
   ],
   "enabled":[
      {
         "id":"mediaindexer.audio",
         "name":"Audio Files"
      },
      {
         "id":"sam.apps",
         "name":"Applications"
      }
   ],
   "returnValue":true
}

Enable a category with a rank 2 order and verify in the category list

1. Enable a category with rank 2.

# luna-send -n 1 -f luna://com.webos.service.unifiedsearch/updateCategory '{
    "id":"com.webos.app.avn.settings",
    "enabled":true,
    "rank":2
}'

Response:

{
    "returnValue": false
}

 

2. Get a list of categories.

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

Response:

{
   "disabled":[
      
   ],
   "enabled":[
      {
         "id":"mediaindexer.audio",
         "name":"Audio Files"
      },
      {
         "id":"com.webos.app.avn.settings",
         "name":"Enact AVN Settings"
      },
      {
         "id":"sam.apps",
         "name":"Applications"
      }
   ],
   "returnValue":true
}

Objects

groupedIntents

Indicates the categorized intents

Name

Required

Type

Description

categoryIdOptionalString

Indicates the ID of the category.

itemsOptionalObject array: item

Indicates the list of items.

item

Provide a detailed description of the object. Limit to 2-3 paragraphs.

Name

Required

Type

Description

intentRequiredObject: intent

Indicates the intent of the item.

displayRequiredObject: display

Indicates the display information of the item.

intent

Contains intent that has 'display' attribute on 'extra' field internally.

Name

Required

Type

Description

actionOptionalString

Indicates the action name.

uriOptionalString

Indicates the uri pattern list.

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

nameOptionalString

Indicates the handler name (used for explicit intent)

extraOptionalObject

Indicates the additional parameter for the handler.

display

Indicates the display information to show on screen.

Name

Required

Type

Description

titleRequiredString

Indicates the title to display on screen.

iconOptionalString

Indicates the icon (thumbnail) path to be displayed on the screen.

category

Indicates the category information.

Name

Required

Type

Description

idRequiredString

Indicates the category ID.

nameRequiredString

Indicates the category name to be displayed on the screen.

Contents