From 0e2a3a892f8cdb79d9d7ed26a30516c6789ce2dc Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Thu, 22 Jan 2015 09:46:25 +0000 Subject: [PATCH] Presence modifications from MatrixPresence notes. - 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. --- drafts/general_api.rst | 60 +++++++++++++++++++++++++----------------- 1 file changed, 36 insertions(+), 24 deletions(-) diff --git a/drafts/general_api.rst b/drafts/general_api.rst index 5a027d15..682edfe4 100644 --- a/drafts/general_api.rst +++ b/drafts/general_api.rst @@ -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. - -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. +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. 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]``