diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/specification.rst | 61 |
1 files changed, 51 insertions, 10 deletions
diff --git a/docs/specification.rst b/docs/specification.rst index 4f6c000505..3288aac019 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -282,24 +282,64 @@ Permissions ----------- - TODO : Room permissions / config / power levels. What they are. How do they work. Examples. +Joining rooms +------------- +- What is joining? What permissions / access does it give you? How does this affect /initialSync? +- API to hit (``/join/$alias or id``). Explain how alias joining works (auto-resolving). See "Room events" for more info. +- What does the home server have to do? +- Rooms that DON'T need an invite to join. This follows through onto inviting users section. +- Outline invite join dance? + + Inviting users -------------- -- API to hit (``$roomid/invite``) with ``user_id`` key. Needs FQ user ID, explain why. -- Outline invite join dance +- Can invite users to a room if the room config key TODO is set to TODO. Must have required power level. +- Outline invite join dance. What is it? Why is it required? How does it work? +- What does the home server have to do? + +The purpose of inviting users to a room is to notify them that the room exists +so they can choose to become a member of that room. Some rooms require that all +users who join a room are previously invited to it (an "invite-only" room). +Whether a given room is an "invite-only" room is determined by the room config +key ``TODO``. It can have one of the following values: + + - TODO Room config invite only value explanation + - TODO Room config free-to-join value explanation + +Only users who have a membership state of ``join`` in a room can invite new +users to said room. The person being invited must not be in the ``join`` state +in the room. The fully-qualified user ID must be specified when inviting a user, +as the user may reside on a different home server. To invite a user, send the +following request to ``/rooms/<room id>/invite``, which will manage the +entire invitation process:: -Joining rooms -------------- -- API to hit (``/join/$alias or id``). Explain how alias joining works (auto-resolving). -- Outline invite join dance + { + "user_id": "<user id to invite>" + } + +Alternatively, the membership state for this user in this room can be modified +directly by sending the following request to +``/rooms/<room id>/state/m.room.member/<url encoded user id>``:: + + { + "membership": "invite" + } + +See the "Room events" section for more information on ``m.room.member``. + +- TODO: In what circumstances will this NOT be equivalent to ``/invite``? Leaving rooms ------------- -- API to hit (``$roomid/leave``). +- API to hit (``$roomid/leave``). See "Room events" for more info. +- Must be joined to leave. How does this affect /initialSync? +- Not ever being in a room is NOT equivalent to have left it (due to membership: leave). +- Need to be re-invited if invite-only room. - If no more HSes in room, can delete room? - Is there a dance? -Room events ------------ +Events in a room +---------------- - Split into state and non-state data - Explain what they are, semantics, give examples of clobbering / not, use cases (msgs vs room names). Not too much detail on the actual event contents. @@ -331,7 +371,8 @@ State messages - m.room.config - m.room.invite_join -What are they, when are they used, what do they contain, how should they be used +What are they, when are they used, what do they contain, how should they be used. +Link back to explanatory sections (e.g. invite/join/leave sections for m.room.member) Non-state messages ------------------ |