archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update v1 /initialSync + /events examples to use r0 /sync instead

Browse Source
pull/977/head
Paul "LeoNerd" Evans 9 years ago
parent 079a963bc5
commit a064d37f64
1 changed files with 160 additions and 415 deletions
Show Stats Download Patch File Download Diff File

493
supporting-docs/howtos/client-server.rst
Unescape Escape View File

@ -195,138 +195,57 @@ Getting all state
If the client doesn't know any information on the rooms the user is If the client doesn't know any information on the rooms the user is
invited/joined on, they can get all the user's state for all rooms:: invited/joined on, they can get all the user's state for all rooms::
curl -XGET "https://localhost:8008/_matrix/client/api/v1/initialSync?access_token=YOUR_ACCESS_TOKEN" curl -XGET "https://localhost:8008/_matrix/client/r0/sync?access_token=YOUR_ACCESS_TOKEN"
{ {
"end": "s39_18_0", "account_data": {
"presence": [ "events": [
{ {
"content": { ...
"last_active_ago": 1061436,
"user_id": "@example:localhost"
},
"type": "m.presence"
} }
], ]
"rooms": [
{
"membership": "join",
"messages": {
"chunk": [
{
"content": {
"@example:localhost": 10,
"default": 0
},
"event_id": "wAumPSTsWF",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.power_levels",
"user_id": "@example:localhost"
}, },
"next_batch": "s9_3_0_1_1_1",
"presence": {
"events": [
{ {
"content": { "content": {
"join_rule": "public" "currently_active": true,
"last_active_ago": 19,
"presence": "online"
}, },
"event_id": "jrLVqKHKiI", "sender": "@example:localhost:8080",
"required_power_level": 10, "type": "m.presence"
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost", }
"state_key": "", ]
"ts": 1409665585188,
"type": "m.room.join_rules",
"user_id": "@example:localhost"
},
{
"content": {
"level": 10
}, },
"event_id": "WpmTgsNWUZ", "rooms": {
"required_power_level": 10, "invite": {},
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost", "join": {
"state_key": "", "!asfLdzLnOdGRkdPZWu:localhost:8080": {
"ts": 1409665585188, "account_data": {
"type": "m.room.add_state_level", "events": []
"user_id": "@example:localhost"
}, },
{ "ephemeral": {
"content": { "events": []
"level": 0
}, },
"event_id": "qUMBJyKsTQ", "state": {
"required_power_level": 10, "events": []
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.send_event_level",
"user_id": "@example:localhost"
}, },
"timeline": {
"events": [
{ {
"content": { "content": {
"ban_level": 5, "creator": "@example:localhost:8080"
"kick_level": 5
}, },
"event_id": "YAaDmKvoUW", "event_id": "$14606534990LhqHt:localhost:8080",
"required_power_level": 10, "origin_server_ts": 1460653499699,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost", "sender": "@example:localhost:8080",
"state_key": "", "state_key": "",
"ts": 1409665585188, "type": "m.room.create",
"type": "m.room.ops_levels", "unsigned": {
"user_id": "@example:localhost" "age": 239192
}, }
{
"content": {
"avatar_url": null,
"displayname": null,
"membership": "join"
},
"event_id": "RJbPMtCutf",
"membership": "join",
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "@example:localhost",
"ts": 1409665586730,
"type": "m.room.member",
"user_id": "@example:localhost"
},
{
"content": {
"body": "hello",
"hsob_ts": 1409665660439,
"msgtype": "m.text"
},
"event_id": "YUwRidLecu",
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"ts": 1409665660439,
"type": "m.room.message",
"user_id": "@example:localhost"
},
{
"content": {
"membership": "invite"
},
"event_id": "YjNuBKnPsb",
"membership": "invite",
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "@myfriend:localhost",
"ts": 1409666426819,
"type": "m.room.member",
"user_id": "@example:localhost"
},
{
"content": {
"avatar_url": null,
"displayname": null,
"membership": "join",
"prev": "join"
},
"event_id": "KWwdDjNZnm",
"membership": "join",
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "@example:localhost",
"ts": 1409666551582,
"type": "m.room.member",
"user_id": "@example:localhost"
}, },
{ {
"content": { "content": {
@ -334,300 +253,126 @@ invited/joined on, they can get all the user's state for all rooms::
"displayname": null, "displayname": null,
"membership": "join" "membership": "join"
}, },
"event_id": "JFLVteSvQc", "event_id": "$14606534991nsZKk:localhost:8080",
"membership": "join", "membership": "join",
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost", "origin_server_ts": 1460653499727,
"state_key": "@example:localhost", "sender": "@example:localhost:8080",
"ts": 1409666587265, "state_key": "@example:localhost:8080",
"type": "m.room.member", "type": "m.room.member",
"user_id": "@example:localhost" "unsigned": {
"age": 239164
} }
],
"end": "s39_18_0",
"start": "t1-11_18_0"
},
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state": [
{
"content": {
"creator": "@example:localhost"
},
"event_id": "dMUoqVTZca",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.create",
"user_id": "@example:localhost"
},
{
"content": {
"@example:localhost": 10,
"default": 0
},
"event_id": "wAumPSTsWF",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.power_levels",
"user_id": "@example:localhost"
},
{
"content": {
"join_rule": "public"
},
"event_id": "jrLVqKHKiI",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.join_rules",
"user_id": "@example:localhost"
},
{
"content": {
"level": 10
},
"event_id": "WpmTgsNWUZ",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.add_state_level",
"user_id": "@example:localhost"
},
{
"content": {
"level": 0
},
"event_id": "qUMBJyKsTQ",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.send_event_level",
"user_id": "@example:localhost"
},
{
"content": {
"ban_level": 5,
"kick_level": 5
},
"event_id": "YAaDmKvoUW",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.ops_levels",
"user_id": "@example:localhost"
}, },
{ ...
"content": { ],
"membership": "invite" "limited": false,
}, "prev_batch": "s9_3_0_1_1_1"
"event_id": "YjNuBKnPsb",
"membership": "invite",
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "@myfriend:localhost",
"ts": 1409666426819,
"type": "m.room.member",
"user_id": "@example:localhost"
},
{
"content": {
"avatar_url": null,
"displayname": null,
"membership": "join"
}, },
"event_id": "JFLVteSvQc", "unread_notifications": {}
"membership": "join",
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "@example:localhost",
"ts": 1409666587265,
"type": "m.room.member",
"user_id": "@example:localhost"
} }
] },
"leave": {}
} }
]
} }
This returns all the room information the user is invited/joined on, as well as This returns all the room information the user is invited/joined on, as well as
all of the presences relevant for these rooms. This can be a LOT of data. You all of the presences relevant for these rooms. This can be a LOT of data. You
may just want the most recent event for each room. This can be achieved by may just want the most recent event for each room. This can be achieved by
applying query parameters to ``limit`` this request:: applying a filter that asks for a limit of 1 timeline event per room::
curl -XGET "https://localhost:8008/_matrix/client/api/v1/initialSync?limit=1&access_token=YOUR_ACCESS_TOKEN" curl --globoff -XGET "https://localhost:8008/_matrix/client/r0/sync?filter={'room':{'timeline':{'limit':1}}}&access_token=YOUR_ACCESS_TOKEN"
{ {
"end": "s39_18_0", ...
"presence": [ "rooms": {
"invite": {},
"join": {
"!asfLdzLnOdGRkdPZWu:localhost:8080": {
...
"timeline": {
"events": [
{ {
"content": { "content": {
"last_active_ago": 1279484, "body": "hello",
"user_id": "@example:localhost" "msgtype": "m.text"
}, },
"type": "m.presence" "event_id": "$14606535757KCGXo:localhost:8080",
"origin_server_ts": 1460653575105,
"sender": "@example:localhost:8080",
"type": "m.room.message",
"unsigned": {
"age": 800348
} }
],
"rooms": [
{
"membership": "join",
"messages": {
"chunk": [
{
"content": {
"avatar_url": null,
"displayname": null,
"membership": "join"
},
"event_id": "JFLVteSvQc",
"membership": "join",
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "@example:localhost",
"ts": 1409666587265,
"type": "m.room.member",
"user_id": "@example:localhost"
} }
], ],
"end": "s39_18_0", "limited": true,
"start": "t10-30_18_0" "prev_batch": "t8-8_7_0_1_1_1"
},
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state": [
{
"content": {
"creator": "@example:localhost"
},
"event_id": "dMUoqVTZca",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.create",
"user_id": "@example:localhost"
},
{
"content": {
"@example:localhost": 10,
"default": 0
},
"event_id": "wAumPSTsWF",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.power_levels",
"user_id": "@example:localhost"
},
{
"content": {
"join_rule": "public"
}, },
"event_id": "jrLVqKHKiI", "unread_notifications": {}
"required_power_level": 10, }
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.join_rules",
"user_id": "@example:localhost"
},
{
"content": {
"level": 10
},
"event_id": "WpmTgsNWUZ",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.add_state_level",
"user_id": "@example:localhost"
},
{
"content": {
"level": 0
},
"event_id": "qUMBJyKsTQ",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.send_event_level",
"user_id": "@example:localhost"
},
{
"content": {
"ban_level": 5,
"kick_level": 5
},
"event_id": "YAaDmKvoUW",
"required_power_level": 10,
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "",
"ts": 1409665585188,
"type": "m.room.ops_levels",
"user_id": "@example:localhost"
}, },
"leave": {}
}
}
(additionally we have to ask ``curl`` not to try to interpret any ``{}``
characters in the URL, which is what the ``--globoff`` option is for)
Getting live state
------------------
In the response to this ``sync`` request the server includes a token that can
be used to obtain updates since this point under the object key ``next_batch``.
To use this token, specify its value as the ``since`` parameter to another
``/sync`` request.::
curl -XGET "https://localhost:8008/_matrix/client/r0/sync?since=s9_7_0_1_1_1&access_token=YOUR_ACCESS_TOKEN"
{ {
"content": { "account_data": {
"membership": "invite" "events": []
},
"event_id": "YjNuBKnPsb",
"membership": "invite",
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "@myfriend:localhost",
"ts": 1409666426819,
"type": "m.room.member",
"user_id": "@example:localhost"
}, },
"next_batch": "s9_9_0_1_1_1",
"presence": {
"events": [
{ {
"content": { "content": {
"avatar_url": null, "currently_active": true,
"displayname": null, "last_active_ago": 12,
"membership": "join" "presence": "online"
}, },
"event_id": "JFLVteSvQc", "sender": "@example:localhost:8080",
"membership": "join", "type": "m.presence"
"room_id": "!MkDbyRqnvTYnoxjLYx:localhost",
"state_key": "@example:localhost",
"ts": 1409666587265,
"type": "m.room.member",
"user_id": "@example:localhost"
} }
] ]
},
"rooms": {
"invite": {},
"join": {},
"leave": {}
} }
]
} }
Getting live state By default this request will not wait in the server, always returning a value
------------------ even if nothing interesting happened. However, by applying the ``timeout``
Once you know which rooms the client has previously interacted with, you need to query parameter, which gives a duration in miliseconds, we can ask the server
listen for incoming events. This can be done like so:: to wait for up to that amount of time before it returns. If no interesting
events have happened since then, the response will be relatively empty.::
curl -XGET "https://localhost:8008/_matrix/client/api/v1/events?access_token=YOUR_ACCESS_TOKEN"
curl -XGET "https://localhost:8008/_matrix/client/r0/sync?since=s9_13_0_1_1_1&access_token=YOUR_ACCESS_TOKEN"
{ {
"chunk": [], "account_data": {
"end": "s39_18_0", "events": []
"start": "s39_18_0" },
"next_batch": "s9_13_0_1_1_1",
"presence": {
"events": []
},
"rooms": {
"invite": {},
"join": {},
"leave": {}
}
} }
This will block waiting for an incoming event, timing out after several seconds.
Even if there are no new events (as in the example above), there will be some
pagination stream response keys. The client should make subsequent requests
using the value of the ``"end"`` key (in this case ``s39_18_0``) as the ``from``
query parameter e.g. ``https://localhost:8008/_matrix/client/api/v1/events?access
_token=YOUR_ACCESS_TOKEN&from=s39_18_0``. This value should be stored so when the
client reopens your app after a period of inactivity, you can resume from where
you got up to in the event stream. If it has been a long period of inactivity,
there may be LOTS of events waiting for the user. In this case, you may wish to
get all state instead and then resume getting live state from a newer end token.
NB: The timeout can be changed by adding a ``timeout`` query parameter, which is
in milliseconds. A timeout of 0 will not block.
Example application Example application
------------------- -------------------

Write Preview
Loading…
Cancel
Save