wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Presence modifications from MatrixPresence notes.

Browse source 
- Idle is no longer a flag but a full state like online|offline.
- Clarify status examples.
- Add device ID to presence state API given it is per device.
- Add note on device specificity on event stream presence parameter.
- Add global appear-offline API.
This commit is contained in:
Kegan Dougal 2015-01-22 09:46:25 +00:00
parent 9a9d4b15d2
commit 0e2a3a892f
1 changed files with 35 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

58
drafts/general_api.rst
View file

@ -816,22 +816,23 @@ The goals of presence are to:
- Let other users know specific status information (e.g. "In a Meeting").
"Online" state can be detected by inspecting when the last time the client made
a request to the server. This could be any request, or a specific kind of request.
For connection-orientated protocols, detecting "online" state can be determined by
the state of this connection stream. For HTTP, this can be detected via requests
to the event stream.
a request to the server. This could be any request, or a specific kind of
request. For connection-orientated protocols, detecting "online" state can be
determined by the state of this connection stream. For HTTP, this can be
detected via requests to the event stream.
Online state is separate from letting other users know if someone is *likely to
respond* to messages. This introduces the concept of an "idle" flag, which is
set when the user has not done any "interaction" with the app. The definition of
"interaction" varies based on the app, so it is up to the app to set this "idle"
flag.
respond* to messages. This introduces the concept of being "idle", which is
when the user has not done any "interaction" with the app for a while. The
definition of "interaction" and "for a while" varies based on the app, so it is
up to the app to set when the user is idle.
Letting users know specific status information can be achieved via the same method
as v1. Status information should be scoped per *user* and not device as determining
a union algorithm between statuses is nonsensical. Passing status information per
device to all other users just redirects the union problem to the client, which
will commonly be presenting this information as an icon alongside the user.
Letting users know specific status information can be achieved via the same
method as v1. Status information should be scoped per *user* and not device as
determining a union algorithm between statuses is nonsensical. Passing status
information per device to all other users just redirects the union problem to
the client, which will commonly be presenting this information as an icon
alongside the user.
When a client hits the event stream, the home server can treat the user as
"online". This behaviour should be able to be overridden to avoid flicker
@ -840,11 +841,11 @@ appear offline > goes into a tunnel > server times out > device regains
connection and hits the event stream forcing the device online before the
"appear offline" state can be set). When the client has not hit the event
stream for a certain period of time, the home server can treat the user as
"offline".
"offline". The user can also set a global *per-user* appear offline flag.
The user should also be able to set their presence via a direct API, without
having to hit the event stream. The home server will set a timer when the
connection ends, after which it will set that device to offline.
The user should also be able to set their presence state via a direct API,
without having to hit the event stream. The home server will set a timer when
the connection ends, after which it will set that device to offline.
As the idle flag and online state is determined per device, there needs to be a
union algorithm to merge these into a single state and flag per user, which will
@ -858,22 +859,33 @@ Changing presence status:
Inputs:
- User ID
- Presence status (online, away, busy, do not disturb, etc)
Outputs:
- Presence status (busy, do not disturb, in a meeting, etc)
Output:
- None.
Setting the idle flag:
Setting presence state:
Inputs:
- User ID
- Is idle
Outputs:
- Device ID
- Presence state (online|idle|offline)
Output:
- None.
Setting global appear offline:
Inputs:
- User ID
- Should appear offline (boolean)
Output:
- None.
Extra parameters associated with the event stream:
Inputs:
- Presence state (online, appear offline)
- Presence state (online, idle, offline)
Notes:
- Scoped per device just like the above API, e.g. from the access_token.
Typing API ``[Final]``