You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/api/server-server/definitions/event-schemas/m.device_list_update.yaml

90 lines
3.6 KiB
YAML

# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: m.device_list_update
description: |-
An EDU that lets servers push details to each other when one of their users
adds a new device to their account, required for E2E encryption to correctly
target the current set of devices for a given user.
# FIXME: It's very unclear why we have this API surface for synchronising
# device lists, rather than just using a room (which could also be used for
# presence lists, profile info, etc). But documenting what we have for now...
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.device_list_update']
description: The string ``m.device_list_update``.
example: "m.device_list_update"
content:
type: object
description: The description of the device whose details has changed.
title: Device List Update
properties:
user_id:
type: string
description: The user ID who owns this device.
example: "@john:example.com"
device_id:
type: string
description: The ID of the device whose details are changing.
example: "QBUAZIFURK"
device_display_name:
type: string
description: |-
The public human-readable name of this device. Will be absent
if the device has no name.
example: "Mobile"
stream_id:
type: integer
description: |-
An ID sent by the server for this update, unique for a given
user_id. Used to identify any gaps in the sequence of ``m.device_list_update``
EDUs broadcast by a server.
example: 6
prev_id:
type: array
description: |-
The stream_ids of any prior m.device_list_update EDUs sent for this user
which have not been referred to already in an EDU's prev_id field. If the
receiving server does not recognise any of the prev_ids, it means an EDU
has been lost and the server should query a snapshot of the device list
via ``/user/keys/query`` in order to correctly interpret future ``m.device_list_update``
EDUs. May be missing or empty for the first EDU in a sequence.
items:
type: integer
description: |-
The stream_id of a prior EDU in this sequence which has not been referred
to already in an EDU's prev_id field.
example: 5
deleted:
type: boolean
description: |-
True if the server is announcing that this device has been deleted.
example: false
keys:
description: |-
The updated identity keys (if any) for this device. May be absent if the
device has no E2E keys defined.
$ref: ../../../client-server/definitions/device_keys.yaml
required:
- user_id
- device_id
- stream_id