Call API

Call API — это программный интерфейс приложения (API), разработанный специально для интеграции сторонних коммуникационных приложений в ОС Аврора. Он предоставляет разработчикам возможность интегрировать функции сигнализации и управления звонками в ОС Аврора наравне с звонками сотовой сети для переиспользования графического интерфейса ОС Аврора и корректного управления ресурсами при конкурирующих звонках.

При использовании Call API управление состоянием устройства в режиме звонка (режим экрана, реакция на датчик приближения, управление маршрутом звука) происходит автоматически, аудио- и графические уведомления возможны при заблокированном экране устройства и обрабатываются теми же сервисами, что и при звонках через сотовую сеть.

Объект Call в рамках Call API предоставляет несколько интерфейсов для взаимодействия.

Интерфейс D-Bus	Назначение
Call.Service1	Регистрация провайдера звонков в ОС
Call.Call1	Управление конкретным вызовом
Call.DTMF1	Вызывается ОС после событий клавиатуры
Call.AudioControl1	Управление устройствами ввод и вывода звука
Call.IconProvider1	Передача иконки, которая отображается на кнопке возвращения

• Функциональность Call API
  • Регистрация в системе
  • Уведомление системы о входящем или исходящем звонке
  • Управление звонком
  • Завершение звонка
  • Информация в уведомлении от приложения
  • Уведомления при проигрывании мультимедиа
  • Экран входящего звонка
  • Эхоподавление
  • Маршрутизация звука
  • Поддержка событий клавиатуры

Функциональность Call API

Регистрация в системе

Для работы с Call API необходимо иметь разрешение Call в манифесте (desktop-файле) приложения.

Для начала работы с Call API необходимо создать на сессионной шине объект CallManager типа org.freedesktop.DBus.ObjectManager и сообщить о его наличии с помощью вызова ru.auroraos.Call.Service1.RegisterCallManager. При успешной регистрации ответ будет пустым без ошибки. Приложение может зарегистрировать несколько CallManager, например, для разных активных аккаунтов.

Уведомление системы о входящем или исходящем звонке

Для уведомления ОС о входящем звонке приложение должно испустить сигнал org.freedesktop.DBus.ObjectManager.InterfacesAdded от объекта зарегистрированного в сервисе ru.auroraos.Call.Service1. В сигнале должны быть перечислены добавляемые объекты, их интерфейсы и свойства. Псевдокод кода сообщения об активном звонке:

var signal = new DBusSignal(
    "/path/to/call_manager",   // путь объекта, зарегистрированного в ru.auroraos.Call.Service1
    "org.freedesktop.DBus.ObjectManager"  // интерфейс
    "InterfacesAdded",  // имя сигнала
    {
        "/path/to/call1": {
            "ru.auroraos.Call.Call1": {
                "Incoming": true, // входящий
                "Status": 3, // Ringing — неотвеченный входящий вызов
                "RemoteName": calleeNumber
            }
        }
    });
user_bus.emit(signal);

Если у звонка есть дополнительные свойства, то вместе с регистрацией звонка можно перечислить дополнительные интерфейсы:

var signal = new DBusSignal(
    "/path/to/call_manager",   // путь объекта, зарегистрированного в ru.auroraos.Call.Service1
    "org.freedesktop.DBus.ObjectManager"  // интерфейс
    "InterfacesAdded",  // имя сигнала
    {
        "/path/to/call1": {
            "ru.auroraos.Call.Call1": {
                "Status": 2, // Dialing — исходящий несоединённый вызов
                "RemoteName": calleeNumber },
            "ru.auroraos.Call.DTMF1": {}
        }
    });
user_bus.emit(signal);

Либо добавить их после регистрации звонка ещё одним сигналом InterfacesAdded:

var signal = new DBusSignal(
    "/path/to/call_manager",   // путь объекта, зарегистрированного в ru.auroraos.Call.Service1
    "org.freedesktop.DBus.ObjectManager"  // интерфейс
    "InterfacesAdded",  // имя сигнала
    {
        "/path/to/call1": {
            "ru.auroraos.Call.DTMF1": {}
        }
    });
user_bus.emit(signal);

ОС управляет звонком путём вызова методов ru.auroraos.Call.Call1. При изменении статуса звонка приложение сообщает об этом операционной системе сигналом ru.auroraos.Call.Call1.StatusChanged. Для удаления звонка нужно вызвать сигнал org.freedesktop.DBus.ObjectManager.InterfacesRemoved:

var signal = new DBusSignal(
    "/path/to/call_manager",   // путь объекта, зарегистрированного в ru.auroraos.Call.Service1
    "org.freedesktop.DBus.ObjectManager"  // интерфейс
    "InterfacesRemoved",  // имя сигнала
    {
        "/path/to/call1": [
            "ru.auroraos.Call.Call1",
            "ru.auroraos.Call.DTMF1"
        ]
    });
user_bus.emit(signal);

Приложение также должно корректно перечислять принадлежащие ему объекты и их интерфейсы при вызове org.freedesktop.DBus.ObjectManager.GetManagedObjects().

Когда приложение решает уведомить пользователя о входящем вызове, оно создаёт на сессионной шине D-Bus объект ru.auroraos.Call.Call1 и сигнализирует об этом через CallManager испустив сигнал org.freedesktop.DBus.ObjectManager.InterfacesAdded. В качестве параметров должны быть указаны путь на D-Bus и свойства (Property) объекта типа ru.auroraos.Call.Call1. Операционная система отображает интерфейс приложения Телефон согласно свойством объекта звонка. В системе может быть одновременно несколько звонков, но только один из них может быть активным. При его переходе в состоянии Active другие активные переводятся на удержание или отклоняются.

Управление звонком

Управление звонком осуществляется вызовом сигналов и методов объекта ru.auroraos.Call.Call1. Нажатия кнопок графического интерфейса Телефона приводит к вызовам методов; изменения свойства Status меняют состояние графического интерфейса.

Завершение звонка

Для завершения звонка необходимо изменить статус соответствующего объекта Call.Call1 на Disconnected, затем сообщить об удалении объекта звонка сигналом org.freedesktop.DBus.ObjectManager.InterfacesRemoved через CallManager.

Информация в уведомлении от приложения

В уведомлении от приложения предоставляется следующая информация:

• аватар (опционально);
• возможность удержания звонка;
• поддержка конференции (добавление абонентов в звонок);
• поддержка DTMF.

Уведомления при проигрывании мультимедиа

Функциональность Call API предоставляет возможность автоматической паузы проигрывания мультимедиа при получении уведомлений о входящих или исходящих звонках. Этот функционал также позволяет сохранить слышимость уведомлений, которые приходят во время проигрывания мультимедиа.

Экран входящего звонка

Функциональность Call API реализует системный экран входящего звонка и звуковое/тактильное оповещение с учётом системных настроек. При входящем звонке, экран показывается независимо от того, заблокировано или разблокировано устройство.

Экран входящего звонка имеет приоритет, как у обычного экрана звонка. На этом экране отображается следующая информация:

• Название и/или иконка VoIP-приложения, от имени учетной записи которого поступил звонок. В конфигурации можно выбрать одно или оба поля.
• Название учетной записи (это поле может быть отключено в конфигурации).
• Отклонить входящий звонок.
• Принять входящий звонок.
• Показать диалоговое окно подтверждения для завершения активного звонка и переключения на входящий звонок.
• В некоторых случаях информация на экране входящего звонка может быть недоступной.

Также Call API предоставляет звуковое или тактильное уведомление с учётом системных настроек (режимы "Не беспокоить" и "Бесшумный", настройки звука/вибрации). При новых входящих звонках во время непринятого входящего звонка сохраняется возможность ответить на входящий звонок, для которого активен системный экран входящего звонка.

По нажатию на иконку приложения — действие, аналогичное запуску приложения из экрана приложений. Если приложения VoIP было запущено в виде фоновой задачи, то оно показывает экран звонка перед извещением системы о звонке.

Эхоподавление

Эхоподавление — важная функция, которая обеспечивает более чистый и четкий звук во время звонка. С помощью Call API разработчики имеют возможность интегрировать функциональность эхоподавления в свои приложения, чтобы обеспечивать наивысшее качество звука для пользователей.

В Call API предусмотрено автоматическое включение эхоподавления при включении громкой связи или при определённой комбинации устройств ввода-вывода. При наличии рекомендации по устранению/избежания эха добавить их в документацию сторонних разработчиков

Маршрутизация звука

Система маршрутизации звука — это механизм, который позволяет управлять потоком звука в операционной системе. Он определяет, какой звуковой источник будет проигрываться через какое аудиоустройство.

Приложение может синхронизировать своё отображение выбранного устройства вывода звука с приложением "Телефон" с помощью интерфейса ru.auroraos.Call.AudioControl1 у объекта звонка.

Для корректной маршрутизации звука необходимо отключить автоматическое управление ресурсами и управлять ими вручную через библиотеку libresource-qt5. Для этого необходимо установить переменную окружения как можно раньше, до запуска любого аудиопотока, лучше в main():

setenv("NEMO_RESOURCE_DISABLE", "1", true);

В режиме звонка перед созданием звуковых потоков должен быть захвачен ресурс aliencall с помощью библиотеки libresource-qt5:

auto resourceSet = new ResourceSet("aliencall", q, false, false);

ResourcePolicy::AudioResource *audioResource = new ResourcePolicy::AudioResource;
audioResource->setProcessID(QCoreApplication::applicationPid());        
audioResource->setStreamTag("media.name", "*");

resourceSet->addResourceObject(audioResource);
resourceSet->addResourceObject(new ResourcePolicy::AudioRecorderResource);

Аудиопотоки можно создавать после получения сигнала ResourceSet::resourcesGranted. После завершения звонка resourceSet должен быть освобождён.

Поддержка событий клавиатуры

В случае необходимости получения сигналов от цифровой клавиатуры на экране Телефона во время звонка можно сообщить системе о поддержке интерфейса DTMF с помощью сигнала org.freedesktop.DBus.ObjectManager.InterfacesAdded. Это можно сделать одновременно с созданием звонка или позже, в последнем случае путь объекта должен совпадать с путём объекта Call1, к которому подключается интерфейс DTMF1.