diff --git a/code/API_definitions/webrtc-call-handling.yaml b/code/API_definitions/webrtc-call-handling.yaml index 93b4613..a009b50 100644 --- a/code/API_definitions/webrtc-call-handling.yaml +++ b/code/API_definitions/webrtc-call-handling.yaml @@ -198,6 +198,14 @@ info: As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + # Emergency Calling + - Introduces a new `callType` attribute with values `REGULAR` or `EMERGENCY`. + - When `callType` is `EMERGENCY`, the client **MAY** include `locationDetails` + describing the caller's location. + - `locationDetails` follows PIDF-LO concepts (3GPP TS 24.229, RFC 4119, RFC 5139, + RFC 5491) with either a circle or ellipsoid shape. + - If `callType` is omitted, it defaults to `REGULAR`. + license: name: Apache 2.0 url: 'https://www.apache.org/licenses/LICENSE-2.0.html' @@ -239,6 +247,8 @@ paths: examples: Media session request: $ref: '#/components/examples/exampleMediaSessionRequest' + EmergencyMediaSessionRequest: + $ref: '#/components/examples/exampleEmergencyMediaSessionRequest' responses: '201': description: Created @@ -258,6 +268,31 @@ paths: $ref: "#/components/responses/Generic401" '403': $ref: '#/components/responses/Generic403' + '501': + description: Not Implemented + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ErrorInfo' + - type: object + properties: + status: + enum: + - 501 + code: + enum: + - CALLTYPE_EMERGENCY_NOT_SUPPORTED + examples: + 501_CALLTYPE_EMERGENCY_NOT_SUPPORTED: + description: The implementation of API provider does not support the `callType` of `EMERGENCY`. + value: + status: 501 + code: CALLTYPE_EMERGENCY_NOT_SUPPORTED + message: Server does not support call type EMERGENCY. /sessions/{mediaSessionId}: get: tags: @@ -457,6 +492,14 @@ components: included in POST requests by the client, but must be included in the notifications from the network to the client device. example: 0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EF + callType: + type: string + description: Type of call. When set to EMERGENCY, the client MAY provide locationDetails. If omitted, treated as REGULAR. + enum: + - REGULAR + - EMERGENCY + locationDetails: + $ref: '#/components/schemas/LocationDetails' WrtcSDPDescriptor: type: object description: |- @@ -513,8 +556,121 @@ components: Address: type: string description: Subscriber address (Sender or Receiver) - pattern: '^(tel:\+[0-9]{5,15}|sip:[A-Za-z0-9_.!%+\-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,})$' + pattern: '^(tel:\+[0-9]{5,15}|sip:[A-Za-z0-9_.!%+\-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}|urn:service:sos(?:\.[a-z0-9](?:[a-z0-9\-]{0,30}[a-z0-9])?)*)$' example: 'tel:+11234567899' + LocationDetails: + type: object + description: Details about the caller's location and related information. This + object adheres to 3GPP TS 24.229, RFC 4119, RFC 5139, and RFC 5491 for PIDF-LO + compatibility. + properties: + shape: + type: string + enum: + - Circle + - Ellipsoid + description: The shape representing the caller's location (Circle or Ellipsoid). + coordinates: + oneOf: + - $ref: '#/components/schemas/CircleCoordinates' + - $ref: '#/components/schemas/EllipsoidCoordinates' + description: The coordinates of the caller's location, specific to the chosen + shape. + method: + type: string + enum: + - GPS + - DBH + - DBH_HELO + - Other + description: 'The method used to obtain the location information. + + * **GPS:** Global Positioning System (highly accurate) + + * **DBH:** Device-Based Hybrid + + * **DBH_HELO:** Device-Based Hybrid using Apple Hybridized Emergency Location + + * **Other:** Other methods (e.g., landmarks, IP Based etc.) + + ' + confidence: + type: object + description: The confidence level of the location information. + properties: + pdf: + type: string + enum: + - normal + - uniform + description: The probability density function (PDF) associated with the + confidence value. + value: + type: number + minimum: 0 + maximum: 100 + description: The confidence value (percentage). + timestamp: + type: string + format: date-time + description: The timestamp (in ISO 8601 format) indicating when the location + information was Calculated. \nThis is crucial for emergency services to + assess the timeliness of the data. if not provided current timestamp will + be used by default" + CircleCoordinates: + type: object + required: + - latitude + - longitude + - radius + properties: + latitude: + type: number + format: float + description: Latitude of the center point in decimal degrees (WGS84). + longitude: + type: number + format: float + description: Longitude of the center point in decimal degrees (WGS84). + radius: + type: number + format: float + description: Radius of the circle in meters, indicating the uncertainty. + EllipsoidCoordinates: + type: object + required: + - latitude + - longitude + - zAxis + - semiMajorAxis + - semiMinorAxis + - verticalAxis + - orientation + properties: + latitude: + type: number + format: float + description: Latitude in the WGS 84 geocentric coordinate system. + longitude: + type: number + format: float + description: Longitude in the WGS 84 geocentric coordinate system. + zAxis: + type: number + format: float + description: Altitude (optional) in the WGS 84 geocentric coordinate system. + semiMajorAxis: + type: number + description: Length of the semi-major axis of the ellipsoid in meters. + semiMinorAxis: + type: number + description: Length of the semi-minor axis of the ellipsoid in meters. + verticalAxis: + type: number + description: Length of the vertical axis of the ellipsoid in meters. + orientation: + type: number + description: Orientation of the ellipsoid in degrees. examples: exampleMediaSessionRequest: value: @@ -616,6 +772,28 @@ components: status: Resume answer: sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n" + exampleEmergencyMediaSessionRequest: + summary: Emergency call initiation with location details + value: + originatorAddress: 'tel:+17085852753' + originatorName: Alice + receiverAddress: 'urn:service:sos' + receiverName: PSAP + offer: + type: offer + sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n" + callType: EMERGENCY + locationDetails: + shape: Circle + coordinates: + latitude: 47.6062 + longitude: -122.3321 + radius: 35 + method: GPS + confidence: + pdf: normal + value: 92 + timestamp: '2025-10-06T19:31:25Z' responses: Generic400: description: Bad Request