Define the client and server APIs for Presence
This commit is contained in:
parent
ee447abcad
commit
c5757a0266
|
@ -1536,15 +1536,6 @@ might decide:
|
||||||
- ``busy`` : accept from anyone in this "important people" group in my
|
- ``busy`` : accept from anyone in this "important people" group in my
|
||||||
address book list
|
address book list
|
||||||
|
|
||||||
Transmission
|
|
||||||
------------
|
|
||||||
.. NOTE::
|
|
||||||
This section is a work in progress.
|
|
||||||
|
|
||||||
.. TODO-doc:
|
|
||||||
- Transmitted as an EDU.
|
|
||||||
- Presence lists determine who to send to.
|
|
||||||
|
|
||||||
Presence List
|
Presence List
|
||||||
-------------
|
-------------
|
||||||
Each user's home server stores a "presence list" for that user. This stores a
|
Each user's home server stores a "presence list" for that user. This stores a
|
||||||
|
@ -1571,6 +1562,108 @@ user, either:
|
||||||
In the latter case, this allows for clients to display some minimal sense of
|
In the latter case, this allows for clients to display some minimal sense of
|
||||||
presence information in a user list for a room.
|
presence information in a user list for a room.
|
||||||
|
|
||||||
|
Client API
|
||||||
|
----------
|
||||||
|
The client API for presence is on the following set of REST calls.
|
||||||
|
|
||||||
|
Fetching basic status::
|
||||||
|
|
||||||
|
GET $PREFIX/presence/:user_id/status
|
||||||
|
|
||||||
|
Returned content: JSON object containing the following keys:
|
||||||
|
presence: "offline"|"unavailable"|"online"|"free_for_chat"
|
||||||
|
status_msg: (optional) string of freeform text
|
||||||
|
last_active_ago: miliseconds since the last activity by the user
|
||||||
|
|
||||||
|
Setting basic status::
|
||||||
|
|
||||||
|
PUT $PREFIX/presence/:user_id/status
|
||||||
|
|
||||||
|
Content: JSON object containing the following keys:
|
||||||
|
presence and status_msg: as above
|
||||||
|
|
||||||
|
When setting the status, the activity time is updated to reflect that activity;
|
||||||
|
the client does not need to specify the ``last_active_ago`` field.
|
||||||
|
|
||||||
|
Fetching the presence list::
|
||||||
|
|
||||||
|
GET $PREFIX/presence/list
|
||||||
|
|
||||||
|
Returned content: JSON array containing objects; each object containing the
|
||||||
|
following keys:
|
||||||
|
user_id: observed user ID
|
||||||
|
presence: "offline"|"unavailable"|"online"|"free_for_chat"
|
||||||
|
status_msg: (optional) string of freeform text
|
||||||
|
last_active_ago: miliseconds since the last activity by the user
|
||||||
|
|
||||||
|
Maintaining the presence list::
|
||||||
|
|
||||||
|
POST $PREFIX/presence/list
|
||||||
|
|
||||||
|
Content: JSON object containing either or both of the following keys:
|
||||||
|
invite: JSON array of strings giving user IDs to send invites to
|
||||||
|
drop: JSON array of strings giving user IDs to remove from the list
|
||||||
|
|
||||||
|
.. TODO-spec
|
||||||
|
- Define how users receive presence invites, and how they accept/decline them
|
||||||
|
|
||||||
|
Server API
|
||||||
|
----------
|
||||||
|
The server API for presence is based entirely on exchange of the following
|
||||||
|
EDUs. There are no PDUs or Federation Queries involved.
|
||||||
|
|
||||||
|
Performing a presence update and poll subscription request::
|
||||||
|
|
||||||
|
EDU type: m.presence
|
||||||
|
|
||||||
|
Content keys:
|
||||||
|
push: (optional): list of push operations.
|
||||||
|
Each should be an object with the following keys:
|
||||||
|
user_id: string containing a User ID
|
||||||
|
presence: "offline"|"unavailable"|"online"|"free_for_chat"
|
||||||
|
status_msg: (optional) string of freeform text
|
||||||
|
last_active_ago: miliseconds since the last activity by the user
|
||||||
|
|
||||||
|
poll: (optional): list of strings giving User IDs
|
||||||
|
|
||||||
|
unpoll: (optional): list of strings giving User IDs
|
||||||
|
|
||||||
|
The presence of this combined message is two-fold: it informs the recipient
|
||||||
|
server of the current status of one or more users on the sending server (by the
|
||||||
|
``push`` key), and it maintains the list of users on the recipient server that
|
||||||
|
the sending server is interested in receiving updates for, by adding (by the
|
||||||
|
``poll`` key) or removing them (by the ``unpoll`` key). The ``poll`` and
|
||||||
|
``unpoll`` lists apply *changes* to the implied list of users; any existing IDs
|
||||||
|
that the server sent as ``poll`` operations in a previous message are not
|
||||||
|
removed until explicitly requested by a later ``unpoll``.
|
||||||
|
|
||||||
|
On receipt of a message containing a non-empty ``poll`` list, the receiving
|
||||||
|
server should immediately send the sending server a presence update EDU of its
|
||||||
|
own, containing in a ``push`` list the current state of every user that was in
|
||||||
|
the orginal EDU's ``poll`` list.
|
||||||
|
|
||||||
|
Sending a presence invite::
|
||||||
|
|
||||||
|
EDU type: m.presence_invite
|
||||||
|
|
||||||
|
Content keys:
|
||||||
|
observed_user: string giving the User ID of the user whose presence is
|
||||||
|
requested (i.e. the recipient of the invite)
|
||||||
|
observer_user: string giving the User ID of the user who is requesting to
|
||||||
|
observe the presence (i.e. the sender of the invite)
|
||||||
|
|
||||||
|
Accepting a presence invite::
|
||||||
|
|
||||||
|
EDU type: m.presence_accept
|
||||||
|
|
||||||
|
Content keys - as for m.presence_invite
|
||||||
|
|
||||||
|
Rejecting a presence invite::
|
||||||
|
|
||||||
|
EDU type: m.presence_deny
|
||||||
|
|
||||||
|
Content keys - as for m.presence_invite
|
||||||
|
|
||||||
|
|
||||||
Voice over IP
|
Voice over IP
|
||||||
=============
|
=============
|
||||||
|
|
Loading…
Reference in New Issue