Menu

Reference

com.webos.surfacemanager

Note
This API has been available since API level 11.

API Summary

Handles the UX, animations of windows. It manages all system and application input handling.

Overview of the API

Provides information about applications surfaces and a limited set of controls for them.

Methods

captureCompositorOutput

ACG: arescli.interface
  • Added: API level 11

Description

Takes a screenshot of the content that the compositor generates. The content can be either a frame that contains the graphics composition result or an application surface that is being composited.

Note:

  • This method can be used when a privileged webOS component wants to take a screenshot for its own purpose. It should not be allowed for public use since the screenshot may contain security-sensitive information.
  • As this method is provided by LSM (Luna Surface Manager), the content is limited to what LSM is able to composite. It may not be possible to take video area with this method due to this technical limitation.
  • Scaling is not supported.

Parameters

Name

Required

Type

Description

outputRequiredString

Indicates the absolute path of the output image file.

appIdOptionalString

Indicates the id of the application.

Note: If not specified, then the entire composited frame will be captured.

formatOptionalString

Indicates the output image format. 

Possible values are:

  • BMP: bitmap (default)
  • JPG: JPEG compressed
  • PNG: PNG compressed
displayIdOptionalNumber

Indicates the id of display to be captured.

Call Returns

Name

Required

Type

Description

outputOptionalString

Indicates the absolute path of output image file.

resolutionOptionalString

Indicates the resolution of the output image in the form of <width>x<height>.

Example: 1920x1080

formatOptionalString

Indicates the output image format.

Possible values are: 

  • BMP: bitmap (default)
  • JPG: JPEG compressed
  • PNG: PNG compressed
returnValueRequiredBoolean

Indicates the status of the 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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

Error Codes Reference

Error Code

Error Text

Error Description

101ERR_MISSING_OUTPUT

The input parameter named "output" is required but it is not passed. 

102ERR_INVALID_PATH

Unable to write a file with a given path due to filesystem related errors. (Non-existent base directory or access denied.)

103ERR_NO_SURFACE

No surface exists associated with a given appId.

104ERR_INVALID_FORMAT

No matching format found. Format must be "BMP", "JPG", or "PNG" (Case sensitive).

105ERR_UNABLE_TO_SAVE

Fail to save a file. 

106ERR_INVALID_DISPLAY

Invalid display id.

107ERR_HAS_SECURED_CONTENT

Surface to be captured has secure content.

Example

Example : Without displayId

# luna-send -n 1 luna://com.webos.surfacemanager/captureCompositorOutput '{
   "output":"/tmp/test.bmp",
   "appId":"com.webos.app.test",
   "format":"BMP"
}'

Response:

{
   "format":"BMP",
   "output":"/tmp/test.bmp",
   "resolution":"1920x1080",
   "returnValue":true
}

# luna-send -n 1 luna://com.webos.surfacemanager/captureCompositorOutput '{
   "output":"/tmp/test.jpg",
   "appId":"com.webos.app.test",
   "format":"JPG"
}'

Response:

{

   "format":"JPG",
   "output":"/tmp/test.jpg",
   "resolution":"1920x1080",
   "returnValue":true
}

# luna-send -n 1 luna://com.webos.surfacemanager/captureCompositorOutput '{
   "output":"/tmp/test.png",
   "appId":"com.webos.app.test",
   "format":"PNG"
}'

Response:

{
   "format":"PNG",
   "output":"/tmp/test.png",
   "resolution":"1920x1080",
   "returnValue":true
}

# luna-send -n 1 luna://com.webos.surfacemanager/captureCompositorOutput '{
   "output":"/tmp/test.jpg",
   "appId":"",
   "format":"JPG"
}'

Response:

{
   "format":"JPG",
   "output":"/tmp/test.jpg",
   "resolution":"1920x1080",
   "returnValue":true
}

# luna-send -n 1 luna://com.webos.surfacemanager/captureCompositorOutput '{
 "output":"/tmp/test.jpg",
 "format":"JPG"
}'

Response:

{
   "format":"JPG",
   "output":"/tmp/test.jpg",
   "resolution":"1920x1080",
   "returnValue":true
}

# luna-send -n 1 luna://com.webos.surfacemanager/captureCompositorOutput '{
   "output":"/tmp/test.bmp",
   "appId":"com.webos.app.test"
}'

Response:

{
   "format":"BMP",
   "output":"/tmp/test.bmp",
   "resolution":"1920x1080",
   "returnValue":true
}

# luna-send -n 1 luna://com.webos.surfacemanager/captureCompositorOutput '{
   "output":"/tmp/test.bmp"
}'

Response: 

{
   "format":"BMP",
   "output":"/tmp/test.bmp",
   "resolution":"1920x1080",
   "returnValue":true
}

Example : With displayId specified

# luna-send -n 1 luna://com.webos.surfacemanager/captureCompositorOutput '{
   "output":"/tmp/test.bmp",
   "appId":"com.webos.app.test",
   "format":"BMP",
   "displayId":0
}'

Response:

{
   "format":"BMP",
   "output":"/tmp/test.bmp",
   "resolution":"1920x1080",
   "returnValue":true
}

# luna-send -n 1 luna://com.webos.surfacemanager/captureCompositorOutput '{
   "output":"/tmp/test.jpg", 
   "format":"JPG",
   "displayId":1
}'

Response:

{
   "format":"JPG",
   "output":"/tmp/test.jpg",
   "resolution":"1920x1080",
   "returnValue":true
}

closeByAppId

ACG: surfacemanager.operation
Retired
  • Added: API level 11
  • Deprecated: API level 11
  • Retired: API level 22

Description

Close an application's surface with given appId.

In most cases, closing the surface leads the application to quit. But with this method, the compositor doesn't discard its surface item (a container of the surface). It is useful when the compositor wants to keep the application's context from the compositor side even when the application is not running anymore. A typical use case of this method is to reclaim the memory by Memory Manager.

Parameters

Name

Required

Type

Description

idRequiredString

Application ID

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false. The method may fail because of one of the error conditions described in the API Error Codes Reference of this service. See the API Error Codes Reference for more information.
errorCodeOptionalNumber

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

errorTextOptionalString

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.

Error Codes Reference

Error Code

Error Text

Error Description

1"APP_ID" is not running

There is no surface item associated with the given appId.

Example

Example code

# luna-send -n 1 luna://com.webos.surfacemanager/closeByAppId '{"id":"com.webos.app.test"}'

Response:

{
   "returnValue": true
}

getAppMirroring

ACG: surfacemanager.query
  • Added: API level 11

Description

Gets the status of the app mirroring.

Parameters

Name

Required

Type

Description

subscribeOptionalBoolean

Indicates if subscribed to get notifications.

Possible values are:

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

Default: false

Call Returns

Name

Required

Type

Description

mirroringInfoRequiredObject array: mirroringInfo

Indicates the mirroring status of each display.

returnValueRequiredBoolean

Indicates the status of operation.

Possible values are:

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

Note: returnValue is always true.

Subscription Returns

Name

Required

Type

Description

mirroringInfoRequiredObject array: mirroringInfo

Indicates mirroring status of each display.

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

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

Note: returnValue is always true.

subscribedOptionalBoolean

Indicates if subscribed to get notifications.

Possible values are:

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

Example

Example: Without subscription

# luna-send -n 1 -f luna://com.webos.surfacemanager/getAppMirroring '{}'

Response: 

{
   "mirroringInfo":[
      {
         "mirroringStatus":"inactive",
         "displayId":0
      },
      {
         "mirroringStatus":"inactive",
         "displayId":1
      }
   ],
   "returnValue":true
}

Example: With subscription

# luna-send -i -f luna://com.webos.surfacemanager/getAppMirroring '{"subscribe":true}'

Response: 

{ 
   "mirroringInfo":[ 
      { 
         "mirroringStatus":"sender",
         "displayId":0
      },
      { 
         "mirroringStatus":"receiver",
         "displayId":1
      }
   ],
   "returnValue":true,
   "subscribed":true
}

getForegroundAppInfo

ACG: surfacemanager.query
  • Added: API level 11

Description

Provides the list of applications that are currently visible in the foreground.

Note:

  • This is a private method that can be used by SAM only.
  • For public use, refer to the com.webos.applicationManager/getForegroundAppInfo method.

Parameters

Name

Required

Type

Description

subscribeOptionalBoolean

Indicates if subscribed to get notifications.

Possible values are:

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

Default: false

Call Returns

Name

Required

Type

Description

foregroundAppInfoOptionalObject array: foregroundAppInfo

Information about a surface that is shown in the foreground.

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

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

Note: returnValue will always contain true.

subscribedOptionalBoolean

Indicates if subscribed to get notifications.

Possible values are:

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

Default: false

Subscription Returns

Name

Required

Type

Description

foregroundAppInfoOptionalObject array: foregroundAppInfo

Information about a surface that is shown in the foreground.

returnValueRequiredBoolean

Indicates the status of the operation.

Possible values are:

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

Note: returnValue will always contain true.

subscribedOptionalBoolean

Indicates if subscribed to get notifications.

Possible values are:

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

Default: false

Error Codes Reference

Error Code

Error Text

Error Description

-1001Invalid parameter type

Indicates that parameter is invalid.

-1000Json parse error

Indicates that JSON format is invalid

Example

Example: Without subscription

# luna-send -n 1 luna://com.webos.surfacemanager/getForegroundAppInfo '{}'

Response:

{
   "foregroundAppInfo":[
      {
         "appId":"com.webos.app.test",
         "processId":"6983",
         "windowGroup":true,
         "windowGroupOwner":true,
         "windowGroupOwnerId":"",
         "windowId":"",
         "windowType":"_WEBOS_WINDOW_TYPE_CARD"
      }
   ],
   "returnValue":true
}

Example: With subscription

# luna-send -f -i luna://com.webos.surfacemanager/getForegroundAppInfo '{"subscribe":true}'

Response:

{
   "subscribed":true,
   "foregroundAppInfo":[
      {
         "appId":"com.webos.app.test",
         "processId":"6983",
         "windowGroup":true,
         "windowGroupOwner":true,
         "windowGroupOwnerId":"",
         "windowId":"",
         "windowType":"_WEBOS_WINDOW_TYPE_CARD"
      }
   ],
   "returnValue":true
}

Example: Window-group response

# luna-send -n 1 -f luna://com.webos.applicationManager/launch '{"id":"com.webos.app.test-windowgroupowner"} '

# luna-send -n 1 -f luna://com.webos.applicationManager/launch '{"id":"com.webos.app.test-windowgroupclient"} '

# luna-send -n 1 -f luna://com.webos.surfacemanager/getForegroundAppInfo '{}'

Response: 

{
   "foregroundAppInfo":[
      {
         "windowGroupOwner":true,
         "windowId":"",
         "appId":"com.webos.app.test-windowgroupowner",
         "windowGroupOwnerId":"",
         "windowType":"_WEBOS_WINDOW_TYPE_CARD",
         "processId":"4668",
         "windowGroup":true
      },
      {
         "windowGroupOwner":false,
         "windowId":"",
         "appId":"com.webos.app.test-windowgroupclient",
         "windowGroupOwnerId":"com.webos.app.test-windowgroupowner",
         "windowType":"_WEBOS_WINDOW_TYPE_CARD",
         "processId":"4750",
         "windowGroup":true
      }
   ],
   "returnValue":true
}

Example: Multiview (side-by-side)

# luna-send -n 1 luna://com.webos.surfacemanager/getForegroundAppInfo '{}'
{
    "foregroundAppInfo": [
        {
            "appId": "com.webos.app.livetv",
            "displayId": 0,
            "multiview": true,
            "params": {
            },
            "pip": false,
            "primary": true,
            "processId": "2419",
            "viewType": "mvsxs",
            "windowGroup": true,
            "windowGroupOwner": true,
            "windowGroupOwnerId": "",
            "windowType": "_WEBOS_WINDOW_TYPE_CARD"
        },
        {
            "appId": "com.webos.app.browser",
            "displayId": 0,
            "multiview": true,
            "params": {
            },
            "pip": false,
            "primary": false,
            "processId": "22382",
            "viewType": "mvsxs",
            "windowGroup": false,
            "windowType": "_WEBOS_WINDOW_TYPE_CARD"
        }
    ],
    "mode": "multiview",
    "returnValue": true
}

Example: Multiview (picture-in-picture)

# luna-send -n 1 luna://com.webos.surfacemanager/getForegroundAppInfo '{}'
{
    "foregroundAppInfo": [
        {
            "appId": "com.webos.app.livetv",
            "displayId": 0,
            "multiview": true,
            "params": {
            },
            "pip": false,
            "primary": true,
            "processId": "2419",
            "viewType": "mvpip",
            "windowGroup": true,
            "windowGroupOwner": true,
            "windowGroupOwnerId": "",
            "windowType": "_WEBOS_WINDOW_TYPE_CARD"
        },
        {
            "appId": "com.webos.app.browser",
            "displayId": 0,
            "multiview": true,
            "params": {
            },
            "pip": true,
            "primary": false,
            "processId": "22382",
            "viewType": "mvpip",
            "windowGroup": false,
            "windowType": "_WEBOS_WINDOW_TYPE_CARD"
        }
    ],
    "mode": "multiview",
    "returnValue": true
}

setAppMirroring

ACG: surfacemanager.operation
  • Added: API level 11

Description

Starts or stops app mirroring for a given display pair.

Parameters

Name

Required

Type

Description

mirrorRequiredBoolean

Indicates whether to mirror the app.

Possible values are:

  • true: Start mirroring
  • false: Stop mirroring
fromRequiredNumber

Indicates id of the display from which the app is mirrored.

toRequiredNumber

Indicates id of the display mirrored by the app.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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

The error code for the failed operation.

errorTextOptionalString

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

Error Codes Reference

Error Code

Error Text

Error Description

1ERR_INVALID_COMMAND

Missing or invalid parameters

2ERR_NO_APP

No app to mirror

3ERR_INVALID_DISPLAY

Invalid display ID

4ERR_NO_MIRRORING

No mirroring matched to given display IDs

5ERR_ALREADY_MIRRORING

Mirroring is already set for given display ID pair

6ERR_SAME_DISPLAY

Same display IDs are used for pairing

7ERR_MIRRORING_DISABLED

Mirroring disabled for given display ID

10INTERNAL_ERROR

Internal error

Example

Example code

# luna-send -n 1 -f luna://com.webos.surfacemanager/setAppMirroring '{
   "mirror":true,
   "from":0,
   "to":1
}'

Response:

{ 
   "returnValue":true
}

Example code

# luna-send -n 1 -f luna://com.webos.surfacemanager/setAppMirroring '{
   "mirror":false,
   "from":0,
   "to":1
}'

Response: 

{ 
   "returnValue":true
}

Objects

foregroundAppInfo

Provides information about a surface that is shown in the foreground.

Name

Required

Type

Description

appIdRequiredString

Indicates id of the application associated with the surface.

windowTypeRequiredString

Indicates window type associated with the surface.

Example:  _WEBOS_WINDOW_TYPE_CARD

processIdRequiredString

Indicates process id (PID) of the surface.

windowIdRequiredString

Indicates windowId associated with the surface.

Note: windowId will always contain " " (empty string).

windowGroupOptionalBoolean

Indicates windowGroup associated with the surface.

Note:

  • windowGroup will always contain true.
  • windowGroup is returned only if the application is part of a "window-group" (or "surface-group").
windowGroupOwnerOptionalBoolean

Indicates if the application is owner/client of a window-group (surface-group).

Possible values are:

  • true: Application is owner of a window-group ( surface-group ).
  • false: Application is client of a window-group ( surface-group ).

Note: 

  • windowGroupOwner will not be returned if the application is not part of a window-group ( surface-group ).
windowGroupOwnerIdOptionalString

Indicates id of the window-group ( surface-group ) for surface-group-client applications.

Note: If the application is surface-group-owner, it will return " " (empty string).

primaryOptionalBoolean

Indicates if it is a "main" app as determined by UX policy.

Default: false

multiviewOptionalBoolean

Indicate whether multivew executes or not. 

default: false

pipOptionalBoolean

Indicate whether the multi-view mode is pip or not.

default: false

viewTypeOptionalString

Indicates additional information about multiview.

Possible Values are:  

  • normal - fullscreen normal view
  • mvsxs - multiview and side-by-side
  • mvpip - multiview and picture-in-picture

default: normal

displayIdOptionalNumber

Indicates the id of display associated with the surface.

paramsOptionalObject

Indicates the object parameter associated with the surface.

Note: Empty object(={}) if it has no value.

mirroringInfo

Indicates mirroring status of each display.

Name

Required

Type

Description

mirroringStatusRequiredString

Indicates status of mirroring.

Possible values are: 

  • inactive: Available for mirroring
  • sender: Mirroring as a sender
  • receiver: Mirroring as a receiver
  • disabled: Unavailable for mirroring
displayIdRequiredNumber

Indicates the id of the display from which the app is mirrored to/from.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 and sample code is licensed under the Apache License 2.0.

Contents