# Copyright 2018 New Vector Ltd
# Copyright 2020 The Matrix.org Foundation C.I.C.
#
# 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. This event will also be
  sent when an existing device gets a new cross-signing signature.

# 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
# 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