API Call proposal

[Aleksander Morgado]

Hey Riccardo,

> in refer to opened bug https://bugs.freedesktop.org/show_bug.cgi?id=84981
> I propose the attached patch, to implement voice or data call in MM core.
> 
> Please let me know what you think.
> 

Thanks for moving this forward :)

>From my POV, this API should be managed very similar to how the
Messaging/SMS API works, clearly separating the modem actions (in the
Messaging interface) with the objects (in the SMS interface). In this
specific case, I'd suggest to have a new
"org.freedesktop.ModemManager1.Modem.Voice" interface for the modem
object, plus then a new "org.freedesktop.ModemManager1.Call" interface
for new "/org/freedesktop/ModemManager1/Call" objects.

Some of the methods defined already assume this, but I don't think it's
clearly explained. Having 2 separate interfaces would make more sense.

Also, I'd have also added the new enums in the
include/ModemManager-enums.h file already, and avoid explaining them in
the API file.

See my other comments inline.

> 
> From 6cb13d8396c4e6fa3e6fc8d1e10c73664f3bfd12 Mon Sep 17 00:00:00 2001
> From: Riccardo Vangelisti <riccardo.vangelisti at sadel.it>
> Date: Mon, 20 Apr 2015 12:58:16 +0200
> Subject: [PATCH] Added API proposal of voice/data call handling
> 
> ---
>  .../org.freedesktop.ModemManager1.Modem.Call.xml   | 118 +++++++++++++++++++++
>  1 file changed, 118 insertions(+)
>  create mode 100644 introspection/org.freedesktop.ModemManager1.Modem.Call.xml
> 
> diff --git a/introspection/org.freedesktop.ModemManager1.Modem.Call.xml b/introspection/org.freedesktop.ModemManager1.Modem.Call.xml
> new file mode 100644
> index 0000000..3d8e08b
> --- /dev/null
> +++ b/introspection/org.freedesktop.ModemManager1.Modem.Call.xml
> @@ -0,0 +1,118 @@
> +<?xml version="1.0" encoding="UTF-8" ?>
> +
> +<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
> +
> +  <!--
> +      org.freedesktop.ModemManager1.Modem.Call:
> +      @short_description: The ModemManager Call interface.
> +
> +      The Call interface handles sending calls and notification of new
> +      incoming calls.
> +  -->
> +  <interface name="org.freedesktop.ModemManager1.Modem.Call">
> +
> +    <!--
> +        Start:
> +        @number: phone number
> +        @type: The type of call, same as "Type" property

Why @type? This would all be voice calls.

> +        @result: The call object path.
> +
> +        Start a new call to specified number
> +    -->
> +    <method name="Start">
> +      <arg name="number" type="s" direction="in" />
> +      <arg name="type" type="i" direction="in" />
> +      <arg name="result" type="o" direction="out" />
> +    </method>
> +

When does this method exactly return? Will the method return even if the
call hasn't been accepted/rejected yet?

> +    <!--
> +        Answer:
> +        @call: call object path
> +
> +        Answer to specified call
> +    -->
> +    <method name="Answer">
> +      <arg name="call" type="o" direction="in" />
> +    </method>
> +
> +    <!--
> +        HangUp:
> +        @call: call object path
> +
> +        Hangup specified call
> +    -->
> +    <method name="HangUp">
> +      <arg name="call" type="o" direction="in" />
> +    </method>
> +

What would happen to calls that have been hungup? Will the DBus object
still be around with state "terminated"?

Shouldn't we have a method in the Modem-specific interface to list all
Call objects managed by the modem?

> +    <!--
> +        Incoming:
> +        @path: Object path of the new Call.
> +
> +        Emitted when a new Call has been received.
> +
> +        Check the "Type" property to determine if the call is data or voice type.
> +    -->
> +    <signal name="Incoming">
> +      <arg name="path" type="o" />
> +    </signal>
> +
> +    <!--
> +        StateChanged:
> +        @old: Old object "State"
> +        @new: New object "State"
> +
> +        Emitted when a message has been deleted.
> +    -->
> +    <signal name="StateChanged">
> +      <arg name="old" type="i" />
> +      <arg name="new" type="i" />
> +    </signal>
> +

What's this StateChanged here?

> +    <!--
> +        State:
> +
> +        The state of Call object paths.
> +
> +        MMCallState:
> +          - MM_MODEM_CALL_STATE_INCOMING Incoming
> +          - MM_MODEM_CALL_STATE_ACCEPTED Accepted
> +          - MM_MODEM_CALL_STATE_TERMINATED Terminated
> +          - MM_MODEM_CALL_STATE_REFUSED Refused
> +          - MM_MODEM_CALL_STATE_ERROR Error
> +          - MM_MODEM_CALL_STATE_INACTIVE Inactive

When does inactive happen?

> +    -->
> +    <property name="State" type="i" access="read" />
> +

This state would belong in the "Call" object interface, not in the Modem
interface.

> +    <!--
> +        Type:
> +
> +        The call type.
> +
> +        MMCallType:
> +          - MM_MODEM_CALL_TYPE_DATA Data call

Should we care about data calls here?

> +          - MM_MODEM_CALL_TYPE_VOICE Voice call
> +    -->
> +    <property name="Type" type="i" access="read" />
> +

This state would belong in the "Call" object interface, not in the Modem
interface.

> +    <!--
> +        Number:
> +
> +        The remote phone number.
> +    -->
> +    <property name="Number" type="s" access="read" />
> +

This state would belong in the "Call" object interface, not in the Modem
interface.

> +    <!--
> +        Audio:
> +
> +        The audio device.
> +
> +        Example list:
> +          - "analog" (PCM analog)
> +          - "/dev/ttyUSB2" (sound device)
> +          - "others?"
> +    -->
> +    <property name="Audio" type="s" access="read" />
> +
> +  </interface>
> +</node>
> -- 
> 2.1.4
> 





-- 
Aleksander
https://aleksander.es