diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/client-server/model/presence.rst | 100 | ||||
| -rw-r--r-- | docs/specification-NOTHAVE.rst | 10 | ||||
| -rw-r--r-- | docs/specification.rst | 14 |
3 files changed, 24 insertions, 100 deletions
diff --git a/docs/client-server/model/presence.rst b/docs/client-server/model/presence.rst index 7e54505364..811bac3fab 100644 --- a/docs/client-server/model/presence.rst +++ b/docs/client-server/model/presence.rst @@ -1,103 +1,3 @@ -======== -Presence -======== - -A description of presence information and visibility between users. - -Overview -======== - -Each user has the concept of Presence information. This encodes a sense of the -"availability" of that user, suitable for display on other user's clients. - - -Presence Information -==================== - -The basic piece of presence information is an enumeration of a small set of -state; such as "free to chat", "online", "busy", or "offline". The default state -unless the user changes it is "online". Lower states suggest some amount of -decreased availability from normal, which might have some client-side effect -like muting notification sounds and suggests to other users not to bother them -unless it is urgent. Equally, the "free to chat" state exists to let the user -announce their general willingness to receive messages moreso than default. - -Home servers should also allow a user to set their state as "hidden" - a state -which behaves as offline, but allows the user to see the client state anyway and -generally interact with client features such as reading message history or -accessing contacts in the address book. - -This basic state field applies to the user as a whole, regardless of how many -client devices they have connected. The home server should synchronise this -status choice among multiple devices to ensure the user gets a consistent -experience. - -Idle Time ---------- - -As well as the basic state field, the presence information can also show a sense -of an "idle timer". This should be maintained individually by the user's -clients, and the homeserver can take the highest reported time as that to -report. Likely this should be presented in fairly coarse granularity; possibly -being limited to letting the home server automatically switch from a "free to -chat" or "online" mode into "idle". - -When a user is offline, the Home Server can still report when the user was last -seen online, again perhaps in a somewhat coarse manner. - -Device Type ------------ - -Client devices that may limit the user experience somewhat (such as "mobile" -devices with limited ability to type on a real keyboard or read large amounts of -text) should report this to the home server, as this is also useful information -to report as "presence" if the user cannot be expected to provide a good typed -response to messages. - - -Presence List -============= - -Each user's home server stores a "presence list" for that user. This stores a -list of other user IDs the user has chosen to add to it (remembering any ACL -Pointer if appropriate). - -To be added to a contact list, the user being added must grant permission. Once -granted, both user's HS(es) store this information, as it allows the user who -has added the contact some more abilities; see below. Since such subscriptions -are likely to be bidirectional, HSes may wish to automatically accept requests -when a reverse subscription already exists. - -As a convenience, presence lists should support the ability to collect users -into groups, which could allow things like inviting the entire group to a new -("ad-hoc") chat room, or easy interaction with the profile information ACL -implementation of the HS. - - -Presence and Permissions -======================== - -For a viewing user to be allowed to see the presence information of a target -user, either - - * The target user has allowed the viewing user to add them to their presence - list, or - - * The two users share at least one room in common - -In the latter case, this allows for clients to display some minimal sense of -presence information in a user list for a room. - -Home servers can also use the user's choice of presence state as a signal for -how to handle new private one-to-one chat message requests. For example, it -might decide: - - "free to chat": accept anything - "online": accept from anyone in my addres book list - "busy": accept from anyone in this "important people" group in my address - book list - - API Efficiency ============== diff --git a/docs/specification-NOTHAVE.rst b/docs/specification-NOTHAVE.rst index 6ed8298cd9..369594f6ae 100644 --- a/docs/specification-NOTHAVE.rst +++ b/docs/specification-NOTHAVE.rst @@ -18,3 +18,13 @@ a sense of an "idle timer". This should be maintained individually by the user's clients, and the home server can take the highest reported time as that to report. When a user is offline, the home server can still report when the user was last seen online. + +Device Type +----------- + +Client devices that may limit the user experience somewhat (such as "mobile" +devices with limited ability to type on a real keyboard or read large amounts of +text) should report this to the home server, as this is also useful information +to report as "presence" if the user cannot be expected to provide a good typed +response to messages. + diff --git a/docs/specification.rst b/docs/specification.rst index 22c55ad861..ada40bdbe3 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -1527,6 +1527,15 @@ in the other direction will not). This timestamp is presented via a key called ``last_active_ago``, which gives the relative number of miliseconds since the message is generated/emitted, that the user was last seen active. +Home servers can also use the user's choice of presence state as a signal for +how to handle new private one-to-one chat message requests. For example, it +might decide: + + - ``free_for_chat`` : accept anything + - ``online`` : accept from anyone in my addres book list + - ``busy`` : accept from anyone in this "important people" group in my + address book list + Transmission ------------ .. NOTE:: @@ -1545,6 +1554,11 @@ granted, both user's HS(es) store this information. Since such subscriptions are likely to be bidirectional, HSes may wish to automatically accept requests when a reverse subscription already exists. +As a convenience, presence lists should support the ability to collect users +into groups, which could allow things like inviting the entire group to a new +("ad-hoc") chat room, or easy interaction with the profile information ACL +implementation of the HS. + Presence and Permissions ------------------------ For a viewing user to be allowed to see the presence information of a target |