Closed Bug 983002 Opened 11 years ago Closed 11 years ago

[Stingray][Gaia] IAC protocol for widget

Categories

(Firefox OS Graveyard :: Gaia, defect)

Product:
Firefox OS Graveyard
Component:
Gaia
Platform:
x86
macOS
Type:
defect
Priority:
Not set
Severity:
normal

Tracking

(Not tracked)

Status:
RESOLVED INVALID

People

(Reporter: johnhu, Assigned: dwi2)

References

Details

(Whiteboard: [FT:Stream3]) 

To have widget working, we need to design the IAC protocol for the communication between system app and homescreen app.
Blocks: 983001
Blocks: 983006
Blocks: 983007
For IAC protocol, I propose to use array of action object. An action object is a widget operation action from homescreen app to system app. The minimum set of actions contains: add, remove, and update. Each of them with different arguments. Example may be found here:

homescreen to system (request message)
[{
  request-id: ‘request-id1’,  // the request id which is generated by homescreen app
  action: ‘add’,
  args: {
    x: 10,
    y: 10,
    w: 200,
    h: 150,
    widgetOrigin: ‘app://widget.gaiamobile.org/'
  }
}, {
  request-id: ‘request-id2’,
  action: ‘add’,
  args: {
    x: 220,
    y: 10,
    w: 200,
    h: 150,
    widgetOrigin: ‘app://widget.gaiamobile.org/'    // the second instance of the same widget.
  }
}, {
  request-id: ‘request-id3’,
  action: ‘add’,
  args: {
    x: 430,
    y: 10,
    w: 200,
    h: 150,
    widgetOrigin: ‘app://widget2.gaiamobile.org/'
  }
}, {
  request-id: ‘request-id4’,
  action: ‘update’,
  args: {
    x: 430,
    y: 400,
    w: 200,
    h: 150,
    widgetId: ‘widget-id3'
  }
}]

The sequence of request message is meaningful. System app should process them one by one sequentially. The followings are definitions of action object:

Action and arguments:
1. add: to create a widget
    args: x, y, width, height, widgetOrigin
2. remove: to remove a widget
    args: widgetId
3. update: to update the position/size of a widget
    args: widgetId, x, y, width, height, visible

For action "add", system app should reply the creation result to homescreen app with widgetId:
system to homescreen (reply message)
[{
  request-id: ‘request-id1’,
  action: ‘add’,
  widgetId: ‘widget-id1’
}, {
  request-id: ‘request-id2’,
  action: ‘add’,
  widgetId: ‘widget-id2’
}, {
  request-id: ‘request-id3’,
  action: ‘add’,
  widgetId: ‘widget-id3’
}]

Homescreen app should use the widgetId replied by system app to do further operations, like update or remove.

The sequence of reply message may NOT be the same as the sequence of request message because of async execution. We need to use request-id to get the mapping between request and reply messages.
I agree with the design. However, since the sequence of request message is meaningful, do we need to make request-id to be sequential too in order to reflect the fact?
I don't think we need to make the request-id be sequential. Because it is an ID for mapping and I don't think we need to restrict the format of this ID.

BTW, system app can reply the two messages for one request message, like:

reply message 1:
[{
  request-id: ‘request-id1’,
  action: ‘add’,
  widgetId: ‘widget-id1’
}, {
  request-id: ‘request-id3’,
  action: ‘add’,
  widgetId: ‘widget-id3’
}]

reply message 2:
[{
  request-id: ‘request-id2’,
  action: ‘add’,
  widgetId: ‘widget-id2’
}]
Also, I think system app should reply all action, including 'remove' and 'update'. Homescreen app will definitely need to know all status of widgets.
Sure. I agree with that. And I forgot to add the result property to reply message, the following is an example:

For add action:
[{
  request-id: ‘request-id2’,
  action: ‘add’,
  args: {
    x: 220,
    y: 10,
    w: 200,
    h: 150,
    widgetOrigin: ‘app://widget.gaiamobile.org/'    // the second instance of the same widget.
  }
}]
replies ======>
[{
  request-id: ‘request-id2’,
  action: ‘add’,
  result: true,
  widgetId: ‘widget-id2’
}]
----------------------------------------
For remove action: 
[{
  request-id: ‘request-id’,
  action: ‘remove’,
  args: {
    widgetId: ‘widget-idX'
  }
}]
replies ======>
[{
  request-id: ‘request-id’,
  action: ‘remove’,
  result: true,
  widgetId: ‘widget-idX’
}]
----------------------------------------
For update action: 
[{
  request-id: ‘request-id’,
  action: ‘update’,
  args: {
    visible: true,
    widgetId: ‘widget-idY'
  }
}]
replies ======>
[{
  request-id: ‘request-id’,
  action: ‘update’,
  result: true,
  widgetId: ‘widget-idY’
}]
More about arguments of each action
1. add's args:
    x (required): the left position, in pixel, at the coordination system of homescreen app,
    y (required): the top position, in pixel, at the coordination system of homescreen app,
    width (required): the width of widget, in pixel,
    height (required): the height of widget in pixel,
    visible (optional): the widget's visibility. Default is true.
    widgetOrigin (required): the origin url of widget app.
2. remove's args:
    widgetId (required): the widget id.
3. update's args:
    widgetId (required): the widget id.
    x (optional): the left position, in pixel, at the coordination system of homescreen app. Default is its original value,
    y (optional): the top position, in pixel, at the coordination system of homescreen app. Default is its original value,
    width (optional): the width of widget, in pixel. Default is its original value,
    height (optional): the height of widget in pixel. Default is its original value,
    visible (optional): the widget's visibility. Default is its original value,
Assignee: nobody → tzhuang
We should not mix two types of variable naming conventions. I suggest we use camel only. So, the replying message from system should be:
[{
  requestId: ‘request-id’,
  action: ‘update’,
  result: true,
  widgetId: ‘widget-idY’
}]
This proposal looks great!

Currently I have only one suggestion: The system app needs the "entry_point" to identify some apps (e.g. dialer or contacts) so I think the protocol in add action should be:

[{
  request-id: ‘request-id2’,
  action: ‘add’,
  args: {
    x: 220,
    y: 10,
    w: 200,
    h: 150,
    widgetOrigin: 'app://widget.gaiamobile.org/',
    widgetEntryPoint: 'entry'
  }
}]
We may need 'show' and 'hide' action for switching between applist and widget list. Suggesting the following format for now:

Hide
==
Request:
[{
  request-id: 'id001',
  action: 'hide'
  args: {
    widgetId: ‘widget-idX'
  }
}]

Response:
[{
  request-id: 'id001',
  action: 'hide',
  result: true,
  widgetId: ‘widget-idX'
}]


Show
==
Request:
[{
  request-id: 'id002',
  action: 'show'
  args: {
    widgetId: ‘widget-idY'
  }
}]

Response:
[{
  request-id: 'id002',
  action: 'show',
  result: true,
  widgetId: ‘widget-idY'
}]
Sorry, forget comment 9 :/ although it could be useful but what we need for now would be 'showall' and 'hideall'.

But this is a little bit contradict with current IAC library for they don't need widget id. Let me write down the detail:


Hideall
==
Request:
[{
  request-id: 'id001',
  action: 'hideall'
}]

Response:
[{
  request-id: 'id001',
  action: 'hideall',
  result: true
}]


Showall
==
Request:
[{
  request-id: 'id002',
  action: 'showall'
}]

Response:
[{
  request-id: 'id002',
  action: 'showall',
  result: true,
}]
Since 'showall' and 'hideall' are sending from homescreen to system, I think it won't be contradict with current IAC library.
Show/hide actions can be replaced by update action. And we already have the same mechanism at comment 6.
for show/hide, I think the following could cover the cases
[{
  requestId: ‘request-id’,
  action: ‘update’,
  args: {
    visible: true,
    widgetId: ‘widget-idY'
  }
}]
replies ======>
[{
  requestId: ‘request-id’,
  action: ‘update’,
  result: true,
  widgetId: ‘widget-idY’
}]

[{
  requestId: ‘request-id’,
  action: ‘update’,
  args: {
    visible: false,
    widgetId: ‘widget-idY'
  }
}]
replies ======>
[{
  requestId: ‘request-id’,
  action: ‘update’,
  result: true,
  widgetId: ‘widget-idY’
}]

But I think showall and hideall must be different message
Flags: needinfo?(ehsan)
I've provided all of the requested information in an email thread with Gene, Evelyn, Gary, Marco et al.  Please let me know if I can help further.
Flags: needinfo?(ehsan)
Since the prototype of 2-layered doesn't land to master, we need invalid this bug.

The prototype of 2-layered can be found at: https://github.com/luke-chang/gaia/tree/TV_arch1

We will build a hybrid model which won't use IAC anymore.
Status: NEW → RESOLVED
Closed: 11 years ago
Resolution: --- → INVALID
Whiteboard: [FT:Stream3]
You need to log in before you can comment on or make changes to this bug.