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

Merge pull request #9 from matrix-org/v2-presence

Browse source 
Presence modifications from MatrixPresence notes.
This commit is contained in:
Kegsay 2015-05-18 14:02:09 +01:00
commit bfec7752cb
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

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