From 78719b4391f438a6e7a930442782d865e3fc66da Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 4 May 2023 10:45:19 +0100 Subject: [PATCH] Add new reason codes to hangup & reject --- data/event-schemas/schema/m.call.hangup.yaml | 37 ++++++++++++++++---- data/event-schemas/schema/m.call.reject.yaml | 18 +++++++--- 2 files changed, 43 insertions(+), 12 deletions(-) diff --git a/data/event-schemas/schema/m.call.hangup.yaml b/data/event-schemas/schema/m.call.hangup.yaml index 14d03f98..5471abfd 100644 --- a/data/event-schemas/schema/m.call.hangup.yaml +++ b/data/event-schemas/schema/m.call.hangup.yaml @@ -1,7 +1,25 @@ --- type: object -description: Sent by either party to signal their termination of the call. This can +description: | + Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call. + + The meanings of the `reason` field are as follows: + * `ice_timeout`: The connection failed after some media was exchanged (as opposed to current + * `ice_failed` which means no media connection could be established). Note that, in the case of + an ICE renegotiation, a client should be sure to send `ice_timeout` rather than `ice_failed` if + media had previously been received successfully, even if the ICE renegotiation itself failed. + * `invite_timeout`: The other party did not answer in time. + * `user_hangup`: Clients must now send this code when the user chooses to end the call, although + for backwards compatability with version 0, a clients should treat an absence of the `reason` + field as `user_hangup`. + * `user_media_failed`: The client was unable to start capturing media in such a way that it is unable + to continue the call. + * `user_busy`: The user is busy. Note that this exists primarily for bridging to other networks such + as the PSTN. A Matrix client that receives a call whilst already in a call would not generally reject + the new call unless the user had specifically chosen to do so. + * `unknown_error`: Some other failure occurred that meant the client was unable to continue the call + rather than the user choosing to end it. allOf: - "$ref": core-event-schema/room_event.yaml properties: @@ -20,22 +38,27 @@ properties: 0. party_id: type: string - description: 'This identifies the party that sent this event. A client may + description: This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value - of this field. ' + of this field. reason: type: string - description: Optional error reason for the hangup. This should not be provided - when the user naturally ends or rejects the call. When there was an error - in the call negotiation, this should be `ice_failed` for when ICE negotiation - fails or `invite_timeout` for when the other party did not answer in time. + description: Reason for the hangup. Note that this was optional in + previous previous versions of the spec, so a missing value should be + treated as `user_hangup`. enum: + - ice_timeout - ice_failed - invite_timeout + - user_hangup + - user_media_failed + - user_busy + - unknown_error required: - call_id - version - party_id + - reason type: type: string enum: diff --git a/data/event-schemas/schema/m.call.reject.yaml b/data/event-schemas/schema/m.call.reject.yaml index d06f7a57..7a027379 100644 --- a/data/event-schemas/schema/m.call.reject.yaml +++ b/data/event-schemas/schema/m.call.reject.yaml @@ -1,6 +1,7 @@ --- type: object -description: If the `m.call.invite` event has `version` `"1"`, a client wishing to +description: | + If the `m.call.invite` event has `version` `"1"`, a client wishing to reject the call sends an `m.call.reject` event. This rejects the call on all devices, but if the calling device sees an `answer` before the `reject`, it disregards the reject event and carries on. The reject has a `party_id` just like an answer, and @@ -9,6 +10,8 @@ description: If the `m.call.invite` event has `version` `"1"`, a client wishing of its answer, it ends the call. If the `m.call.invite` event has `version` `0`, the callee sends an `m.call.hangup` event. If the calling user chooses to end the call before setup is complete, the client sends `m.call.hangup` as previously. + + The meanings of the `reason` codes are the same as in [`m.call.hangup`](#mcallhangup). allOf: - "$ref": core-event-schema/room_event.yaml properties: @@ -32,17 +35,22 @@ properties: of this field. ' reason: type: string - description: Optional error reason for the hangup. This should not be provided - when the user naturally ends or rejects the call. When there was an error - in the call negotiation, this should be `ice_failed` for when ICE negotiation - fails or `invite_timeout` for when the other party did not answer in time. + description: Reason for the hangup. Note that this was optional in + previous previous versions of the spec, so a missing value should be + treated as `user_hangup`. enum: + - ice_timeout - ice_failed - invite_timeout + - user_hangup + - user_media_failed + - user_busy + - unknown_error required: - call_id - version - party_id + - reason type: type: string enum: