From 5d53d67efe2764426f7f4de7cd34441e7f217b4a Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 17 May 2023 14:28:21 +0100 Subject: [PATCH] Move common VoIP fields into a call event type. --- .../client-server-api/modules/voip_events.md | 6 +++++ .../schema/core-event-schema/call_event.yaml | 26 +++++++++++++++++++ data/event-schemas/schema/m.call.answer.yaml | 16 ++---------- .../schema/m.call.candidates.yaml | 16 ++---------- data/event-schemas/schema/m.call.hangup.yaml | 20 +------------- data/event-schemas/schema/m.call.invite.yaml | 16 ++---------- .../schema/m.call.negotiate.yaml | 20 +------------- data/event-schemas/schema/m.call.reject.yaml | 21 ++------------- .../schema/m.call.select_answer.yaml | 16 ++---------- 9 files changed, 44 insertions(+), 113 deletions(-) create mode 100644 data/event-schemas/schema/core-event-schema/call_event.yaml diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index b8ed2f2c..b15c4220 100644 --- a/content/client-server-api/modules/voip_events.md +++ b/content/client-server-api/modules/voip_events.md @@ -122,6 +122,12 @@ or not there have been any changes to the Matrix spec. #### Events +##### Common Fields + +{{% event-fields event_type="call_event" %}} + +##### Events + {{% event-group group_name="m.call" %}} #### Client behaviour diff --git a/data/event-schemas/schema/core-event-schema/call_event.yaml b/data/event-schemas/schema/core-event-schema/call_event.yaml new file mode 100644 index 00000000..4fcb833d --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/call_event.yaml @@ -0,0 +1,26 @@ +allOf: +- "$ref": room_event.yaml + description: "All call events share a set of common fields: those of room events + and some additional VoIP specific fields." +properties: + call_id: + type: string + description: The ID of the call this event relates to. + version: + type: string + description: The version of the VoIP specification this message adheres to. + This specification is version 1. This field is a string such that experimental + implementations can use non-integer versions. This field was an integer + in the previous spec version and implementations must accept an integer + 0. + party_id: + type: string + 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. ' +required: +- call_id +- version +- party_id +title: CallEvent +type: object diff --git a/data/event-schemas/schema/m.call.answer.yaml b/data/event-schemas/schema/m.call.answer.yaml index 7037f254..58accd9d 100644 --- a/data/event-schemas/schema/m.call.answer.yaml +++ b/data/event-schemas/schema/m.call.answer.yaml @@ -2,16 +2,12 @@ "type": "object", "description": "This event is sent by the callee when they wish to answer the call.", "allOf": [{ - "$ref": "core-event-schema/room_event.yaml" + "$ref": "core-event-schema/call_event.yaml" }], "properties": { "content": { "type": "object", "properties": { - "call_id": { - "type": "string", - "description": "The ID of the call this event relates to." - }, "answer": { "type": "object", "title": "Answer", @@ -28,17 +24,9 @@ } }, "required": ["type", "sdp"] - }, - "version": { - "type": "string", - "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0" - }, - "party_id": { - "type": "string", - "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. " } }, - "required": ["call_id", "answer", "version", "party_id"] + "required": ["answer"] }, "type": { "type": "string", diff --git a/data/event-schemas/schema/m.call.candidates.yaml b/data/event-schemas/schema/m.call.candidates.yaml index 8937fc1b..4412dd1c 100644 --- a/data/event-schemas/schema/m.call.candidates.yaml +++ b/data/event-schemas/schema/m.call.candidates.yaml @@ -2,16 +2,12 @@ "type": "object", "description": "This event is sent by callers after sending an invite and by the callee after answering. Its purpose is to give the other party additional ICE candidates to try using to communicate.", "allOf": [{ - "$ref": "core-event-schema/room_event.yaml" + "$ref": "core-event-schema/call_event.yaml" }], "properties": { "content": { "type": "object", "properties": { - "call_id": { - "type": "string", - "description": "The ID of the call this event relates to." - }, "candidates": { "type": "array", "description": "Array of objects describing the candidates.", @@ -34,17 +30,9 @@ }, "required": ["candidate", "sdpMLineIndex", "sdpMid"] } - }, - "party_id": { - "type": "string", - "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. " - }, - "version": { - "type": "string", - "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0." } }, - "required": ["call_id", "candidates", "version", "party_id"] + "required": ["candidates"] }, "type": { "type": "string", diff --git a/data/event-schemas/schema/m.call.hangup.yaml b/data/event-schemas/schema/m.call.hangup.yaml index 72b20c75..25e7b153 100644 --- a/data/event-schemas/schema/m.call.hangup.yaml +++ b/data/event-schemas/schema/m.call.hangup.yaml @@ -22,26 +22,11 @@ description: | * `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 +- "$ref": core-event-schema/call_event.yaml properties: content: type: object properties: - call_id: - type: string - description: The ID of the call this event relates to. - version: - type: string - description: The version of the VoIP specification this message adheres to. - This specification is version 1. This field is a string such that experimental - implementations can use non-integer versions. This field was an integer - in the previous spec version and implementations must accept an integer - 0. - party_id: - type: string - 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. reason: type: string description: Reason for the hangup. Note that this was optional in @@ -56,9 +41,6 @@ properties: - user_busy - unknown_error required: - - call_id - - version - - party_id - reason type: type: string diff --git a/data/event-schemas/schema/m.call.invite.yaml b/data/event-schemas/schema/m.call.invite.yaml index d9f0b442..07dc5aff 100644 --- a/data/event-schemas/schema/m.call.invite.yaml +++ b/data/event-schemas/schema/m.call.invite.yaml @@ -2,16 +2,12 @@ "type": "object", "description": "This event is sent by the caller when they wish to establish a call.", "allOf": [{ - "$ref": "core-event-schema/room_event.yaml" + "$ref": "core-event-schema/call_event.yaml" }], "properties": { "content": { "type": "object", "properties": { - "call_id": { - "type": "string", - "description": "A unique identifier for the call." - }, "offer": { "type": "object", "title": "Offer", @@ -29,14 +25,6 @@ }, "required": ["type", "sdp"] }, - "version": { - "type": "string", - "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0." - }, - "party_id": { - "type": "string", - "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. " - }, "lifetime": { "type": "integer", "description": "The time in milliseconds that the invite is valid for. Once the invite age exceeds this value, clients should discard it. They should also no longer show the call as awaiting an answer in the UI." @@ -46,7 +34,7 @@ "description": "The ID of the user being called. If omitted, any user in the room can answer.", } }, - "required": ["call_id", "offer", "version", "lifetime", "party_id"] + "required": ["offer", "lifetime"] }, "type": { "type": "string", diff --git a/data/event-schemas/schema/m.call.negotiate.yaml b/data/event-schemas/schema/m.call.negotiate.yaml index 83012966..14efcbe2 100644 --- a/data/event-schemas/schema/m.call.negotiate.yaml +++ b/data/event-schemas/schema/m.call.negotiate.yaml @@ -34,26 +34,11 @@ description: | attempt to validate the `type` field, but simply pass the object into the WebRTC API. allOf: -- "$ref": core-event-schema/room_event.yaml +- "$ref": core-event-schema/call_event.yaml properties: content: type: object properties: - call_id: - type: string - description: The ID of the call this event relates to. - version: - type: string - description: The version of the VoIP specification this message adheres to. - This specification is version 1. This field is a string such that experimental - implementations can use non-integer versions. This field was an integer - in the previous spec version and implementations must accept an integer - 0. - party_id: - type: string - 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. offer: type: object title: Offer @@ -77,9 +62,6 @@ properties: They should also no longer show the call as awaiting an answer in the UI. required: - - call_id - - version - - party_id - offer - lifetime type: diff --git a/data/event-schemas/schema/m.call.reject.yaml b/data/event-schemas/schema/m.call.reject.yaml index eb682c69..bd745132 100644 --- a/data/event-schemas/schema/m.call.reject.yaml +++ b/data/event-schemas/schema/m.call.reject.yaml @@ -13,26 +13,11 @@ description: | The meanings of the `reason` codes are the same as in [`m.call.hangup`](#mcallhangup). allOf: -- "$ref": core-event-schema/room_event.yaml +- "$ref": core-event-schema/call_event.yaml properties: content: type: object properties: - call_id: - type: string - description: The ID of the call this event relates to. - version: - type: string - description: The version of the VoIP specification this message adheres to. - This specification is version 1. This field is a string such that experimental - implementations can use non-integer versions. This field was an integer - in the previous spec version and implementations must accept an integer - 0. - party_id: - type: string - 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. ' reason: type: string description: Reason for the hangup. Note that this was optional in @@ -47,9 +32,7 @@ properties: - user_busy - unknown_error required: - - call_id - - version - - party_id + - reason type: type: string enum: diff --git a/data/event-schemas/schema/m.call.select_answer.yaml b/data/event-schemas/schema/m.call.select_answer.yaml index a28a7465..8a9b6877 100644 --- a/data/event-schemas/schema/m.call.select_answer.yaml +++ b/data/event-schemas/schema/m.call.select_answer.yaml @@ -2,30 +2,18 @@ "type": "object", "description": "This event is sent by the caller's client once it has decided which other client to talk to, by selecting one of multiple possible incoming `m.call.answer` events. Its `selected_party_id` field indicates the answer it's chosen. The `call_id` and `party_id` of the caller is also included. If the callee's client sees a `select_answer` for an answer with party ID other than the one it sent, it ends the call and informs the user the call was answered elsewhere. It does not send any events. Media can start flowing before this event is seen or even sent. Clients that implement previous versions of this specification will ignore this event and behave as they did before.", "allOf": [{ - "$ref": "core-event-schema/room_event.yaml" + "$ref": "core-event-schema/call_event.yaml" }], "properties": { "content": { "type": "object", "properties": { - "call_id": { - "type": "string", - "description": "The ID of the call this event relates to." - }, - "version": { - "type": "string", - "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0." - }, - "party_id": { - "type": "string", - "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. " - }, "selected_party_id": { "type": "string", "description": "The `party_id` field from the answer event that the caller chose." }, }, - "required": ["call_id", "version"] + "required": ["selected_party_id"] }, "type": { "type": "string",