Hi all,
I attach'd a new patch and schema with your latest suggestions.
Note that Voice.StateChanged signal has "reason" argument but, by the
way, I had to create the MMCallStateChangedReason property in order to
permits user to retrieve that information also from the call object.
This property is the same that indicates why and how a call terminates.
So, I've created an enum for each state trasition.
Also, I've removed Audio property as Aleksander suggested.
If you doesn't have any other suggestions, my colleague and I start to
develop in our branch:
https://bitbucket.org/riccardovangelisti/modemmanager/branch/voicecall
Riccardo Vangelisti - Sadel SpA
Software Development
Via Serenari 1, Castel Maggiore (BO)
Il 22/04/2015 11:23, Aleksander Morgado ha scritto:
Hey Dan & Riccardo,
Some comments from my side.
For states:
+ * MM_CALL_STATE_UNKNOWN: default state for a new outgoing call
Should we have a MM_CALL_STATE_DIALING in between here for outgoing
calls? The call isn't really RINGING until the dialing request is
complete, and that can sometimes take 10 seconds or more while network
capacity is being allocated and the circuit set up, especially in busy
cells.
Is this worth? I think it could be cleaner to have DIALING state
applicable only to ongoing calls (i.e. you ATD... and you wait for the
OK/NOCARRIER/BUSY/NODIALTONE response), and then RINGING only for
incoming calls (i.e. you're receiving a new call and the device should
ring).
I think we also need STATE_HELD to indicate when the call is on hold
(see +CHLD docs), and STATE_WAITING (+CCWA).
Ok, I ignored these command! I'll add these states in the next patch.
I actually would only add these whenever we support holding/waiting the call...
The "Call.Audio" property concerns me a bit, I don't think it provides
enough detail. What is /dev/ttyUSB3 supposed to be as the "Audio"
value? I know on the one Huawei that I have that supports voice, the
serial device just spits out and accepts 16-bit PCM frames, but how
would that be indicated here? I don't think apps should require a
parallel database of modem voice details. Also, what does "analog"
actually mean? Where does the audio come from or go to? I think this
part needs more specification and possibly more detail in the API.
I will reply to this as soon as possible. In the meanwhile, what are your
suggestions?
Note that in my case the modem provides an analog output that must not be
handled by software.
I would try to avoid guessing; and therefore I would just target for
now the specific device that is going to be supported first. If this
device for now doesn't need anything software-wise (i.e. the audio
circuit is totally independent), then either we add a property showing
a value which says "external" or the like, or even, we completely
ignore this and we don't even add a property. Whenever new
implementations that require other info are implemented, then we can
add new properties. What do you guys think? I'm just trying to keep it
simple.
On to Voice...
There are also some meta operations that can be done, like call
transfer, join, multiparty, etc. Ofono created a VoiceCallManager API
for that purpose, which might be useful to review for .Voice API
additions.
It's true, but maybe these methods could be added later.
My goal is to start a call as soon as possible...
I also agree with this. We should write a minimal API for now, not
targeting transfer/join/multiparty...
But looking at Ofono's API is also something that would be valuable.
Riccardo, could you take a look at this API and compare it with the
proposal we're discussing to see if there are inconsistencies?
Android's API would also be interesting to check.
DeleteCall needs more explanation; obviously it will terminate (hang up,
disconnect) the call and release any resources. Basically it's just
like Hangup() right?
I thought to use "DeleteCall" in order to remove a terminated call from the
Voice list property.
Obviously if the call is active, this method should also terminate the call.
Yeah, so the thing here is that we'd be leaving in the list of calls
managed by the Voice API all the call objects that have been generated
in this session, and this includes calls that have been terminated
with a HangUp. So, to let the users of the API clear the list or
specific objects from DBus, the DeleteCall() method would be available
(same as we do e.g. in Messaging API with non-stored sent SMS
messages).
For CallAdded, instead of a boolean, how about just re-using
MM_CALL_DIRECTION? Also, is the direction argument that interesting
here? eg, what would a client do when it receives the CallAdded signal
+ direction, if it *doesn't* retrieve the call object properties?
Possibly the argument could be removed if we expect clients to get all
the properties, since eventually we'll have CLIP, phone number,
multiparty, emergency indicator, etc.
Direction is more correct than the bool value, but I prefer to remove the
property and force user to read the call object properties.
Yes, the signal should only expose the path of the new call object
being exposed in DBus. Clients should load the properties they are
interested in, and that would include the direction.
>From ea1ec11bca6f17c8af1a14db8c3adfcebc13a476 Mon Sep 17 00:00:00 2001
From: Marco Bascetta <[email protected]>
Date: Wed, 22 Apr 2015 16:18:14 +0200
Subject: [PATCH] Added Modem.Voice and Call interfaces for voice call handling
---
include/ModemManager-enums.h | 52 ++++++++++++++
introspection/all.xml | 2 +
.../org.freedesktop.ModemManager1.Call.xml | 81 ++++++++++++++++++++++
.../org.freedesktop.ModemManager1.Modem.Voice.xml | 81 ++++++++++++++++++++++
4 files changed, 216 insertions(+)
create mode 100644 introspection/org.freedesktop.ModemManager1.Call.xml
create mode 100644 introspection/org.freedesktop.ModemManager1.Modem.Voice.xml
diff --git a/include/ModemManager-enums.h b/include/ModemManager-enums.h
index 57a2b27..b8809fa 100644
--- a/include/ModemManager-enums.h
+++ b/include/ModemManager-enums.h
@@ -1168,4 +1168,56 @@ typedef enum { /*< underscore_name=mm_oma_session_state_failed_reason >*/
MM_OMA_SESSION_STATE_FAILED_REASON_SESSION_CANCELLED = 5
} MMOmaSessionStateFailedReason;
+/**
+ * MMCallState:
+ * @MM_CALL_STATE_UNKNOWN: default state for a new outgoing call.
+ * @MM_CALL_STATE_DIALING: outgoing call started.
+ * @MM_CALL_STATE_RINGING: incoming call is waiting for an answer.
+ * @MM_CALL_STATE_ACTIVE: call is active between two peers.
+ * @MM_CALL_STATE_HELD: held call (by +CHLD AT command).
+ * @MM_CALL_STATE_WAITING: waiting call (by +CCWA AT command).
+ * @MM_CALL_STATE_TERMINATED: call is terminated.
+ *
+ * State of Call
+ */
+typedef enum { /*< underscore_name=mm_call_state >*/
+ MM_CALL_STATE_UNKNOWN = 0,
+ MM_CALL_STATE_DIALING = 1,
+ MM_CALL_STATE_RINGING = 2,
+ MM_CALL_STATE_ACTIVE = 3,
+ MM_CALL_STATE_HELD = 4,
+ MM_CALL_STATE_WAITING = 5,
+ MM_CALL_STATE_TERMINATED = 6,
+} MMCallState;
+
+/**
+ * MMCallStateChangedReason:
+ * @MM_CALL_STATE_CHANGED_REASON_UNKNOWN: Default value for a new outgoing call.
+ * @MM_CALL_STATE_CHANGED_REASON_OUTGOING_STARTED: Outgoing call is started.
+ * @MM_CALL_STATE_CHANGED_REASON_INCOMING_NEW: Received a new incoming call.
+ * @MM_CALL_STATE_CHANGED_REASON_ACCEPTED: Dialing or Ringing call is accepted.
+ * @MM_CALL_STATE_CHANGED_REASON_TERMINATED: Call is correctly terminated.
+ * @MM_CALL_STATE_CHANGED_REASON_REFUSED_OR_BUSY: Remote peer is busy or refused call
+ * @MM_CALL_STATE_CHANGED_REASON_ERROR: Wrong number or generic network error.
+ */
+typedef enum {
+ MM_CALL_STATE_CHANGED_REASON_UNKNOWN = 0,
+ MM_CALL_STATE_CHANGED_REASON_OUTGOING_STARTED = 1,
+ MM_CALL_STATE_CHANGED_REASON_INCOMING_NEW = 2,
+ MM_CALL_STATE_CHANGED_REASON_ACCEPTED = 3,
+ MM_CALL_STATE_CHANGED_REASON_TERMINATED = 4,
+ MM_CALL_STATE_CHANGED_REASON_REFUSED_OR_BUSY = 5,
+ MM_CALL_STATE_CHANGED_REASON_ERROR = 6,
+} MMCallStateChangedReason;
+
+/**
+ * MMCallDirection:
+ * @MM_CALL_DIRECTION_INCOMING : call from network.
+ * @MM_CALL_DIRECTION_OUTGOING : call to network.
+ */
+typedef enum { /*< underscore_name=mm_call_direction >*/
+ MM_CALL_DIRECTION_INCOMING = 0,
+ MM_CALL_DIRECTION_OUTGOING = 1
+} MMCallDirection;
+
#endif /* _MODEMMANAGER_ENUMS_H_ */
diff --git a/introspection/all.xml b/introspection/all.xml
index 4d277e3..57c28d0 100644
--- a/introspection/all.xml
+++ b/introspection/all.xml
@@ -6,7 +6,9 @@
<xi:include href="org.freedesktop.ModemManager1.Sim.xml"/>
<xi:include href="org.freedesktop.ModemManager1.Bearer.xml"/>
<xi:include href="org.freedesktop.ModemManager1.Sms.xml"/>
+ <xi:include href="org.freedesktop.ModemManager1.Call.xml"/>
<xi:include href="org.freedesktop.ModemManager1.Modem.xml"/>
+ <xi:include href="org.freedesktop.ModemManager1.Modem.Voice.xml"/>
<xi:include href="org.freedesktop.ModemManager1.Modem.Modem3gpp.xml"/>
<xi:include href="org.freedesktop.ModemManager1.Modem.Modem3gpp.Ussd.xml"/>
<xi:include href="org.freedesktop.ModemManager1.Modem.ModemCdma.xml"/>
diff --git a/introspection/org.freedesktop.ModemManager1.Call.xml b/introspection/org.freedesktop.ModemManager1.Call.xml
new file mode 100644
index 0000000..5954569
--- /dev/null
+++ b/introspection/org.freedesktop.ModemManager1.Call.xml
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd";>
+
+ <!--
+ org.freedesktop.ModemManager1.Call:
+ @short_description: The ModemManager Call interface.
+
+ The Call interface Defines operations and properties of a single Call.
+ -->
+ <interface name="org.freedesktop.ModemManager1.Call">
+
+ <!--
+ Start:
+
+ If the outgoing call has not yet been started, start it.
+ Applicable only if state is MM_CALL_STATE_UNKNOWN and direction is MM_CALL_DIRECTION_OUTGOING.
+ -->
+ <method name="Start" />
+
+ <!--
+ Accept:
+
+ Accept incoming call (answer).
+ Applicable only if state is MM_CALL_STATE_RINGING and direction is MM_CALL_DIRECTION_INCOMING
+ -->
+ <method name="Accept" />
+
+ <!--
+ Hangup:
+
+ Hangup the active call.
+ Applicable only if states are MM_CALL_STATE_RINGING and MM_CALL_STATE_ACCEPTED
+ -->
+ <method name="Hangup"/>
+
+ <!--
+ StateChanged:
+ @old: Old state MMCallState
+ @new: New state MMCallState
+ @reason: A <link linkend="MMCallStateChangedReason">MMCallStateChangedReason</link> value, specifying the reason for this state change.
+
+ Emitted when call changes state
+ -->
+ <signal name="StateChanged">
+ <arg name="old" type="i" />
+ <arg name="new" type="i" />
+ <arg name="reason" type="u" />
+ </signal>
+
+ <!--
+ State:
+
+ A <link linkend="MMCallState">MMCallState</link> value,
+ describing the state of the call.
+ -->
+ <property name="State" type="i" access="read" />
+
+ <!--
+ StateChangedReason:
+
+ A <link linkend="MMCallStateChangedReason">MMCallStateChangedReason</link> value, describing why the state is changed.
+ -->
+ <property name="StateChangedReason" type="i" access="read" />
+
+ <!--
+ Direction:
+
+ A <link linkend="MMCallDirection">MMCallDirection</link> value,
+ describing the direction of the call.
+ -->
+ <property name="Direction" type="i" access="read" />
+
+ <!--
+ Number:
+
+ The remote phone number.
+ -->
+ <property name="Number" type="s" access="read" />
+ </interface>
+</node>
diff --git a/introspection/org.freedesktop.ModemManager1.Modem.Voice.xml b/introspection/org.freedesktop.ModemManager1.Modem.Voice.xml
new file mode 100644
index 0000000..fbd91da
--- /dev/null
+++ b/introspection/org.freedesktop.ModemManager1.Modem.Voice.xml
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd";>
+
+ <!--
+ org.freedesktop.ModemManager1.Modem.Voice:
+ @short_description: The ModemManager Voice interface.
+
+ The Voice interface handles Calls.
+ -->
+ <interface name="org.freedesktop.ModemManager1.Modem.Voice">
+
+ <!--
+ ListCalls:
+ @result: The list of call object paths.
+
+ Retrieve all Calls.
+
+ This method should only be used once and subsequent information
+ retrieved either by listening for the
+ #org.freedesktop.ModemManager1.Modem.Voice::Added signal,
+ or by querying the specific Call object of interest.
+ -->
+ <method name="ListCalls">
+ <arg name="result" type="ao" direction="out" />
+ </method>
+
+ <!--
+ DeleteCall:
+ @path: The object path of the Call to delete.
+
+ Delete a Call from lists of calls.
+ If it is still active, Call.Hangup method is performed
+ -->
+ <method name="DeleteCall">
+ <arg name="path" type="o" direction="in" />
+ </method>
+
+ <!--
+ CreateCall:
+ @properties: Call properties from the <link linkend="gdbus-org.freedesktop.ModemManager1.Call">Call D-Bus interface</link>.
+ @path: The object path of the new call object.
+
+ Creates a new call object.
+
+ The '<link linkend="gdbus-property-org-freedesktop-ModemManager1-Call.Number">Number</link>' is mandatory
+ -->
+ <method name="CreateCall">
+ <arg name="properties" type="a{sv}" direction="in" />
+ <arg name="path" type="o" direction="out" />
+ </method>
+
+ <!--
+ CallAdded:
+ @path: Object path of the new call.
+
+ Emitted when any part of a Call has been received or added.
+ -->
+ <signal name="CallAdded">
+ <arg name="path" type="o" />
+ </signal>
+
+ <!--
+ CallDeleted:
+ @path: Object path of the now deleted Call.
+
+ Emitted when a call has been deleted.
+ -->
+ <signal name="CallDeleted">
+ <arg name="path" type="o" />
+ </signal>
+
+ <!--
+ Calls:
+
+ The list of calls object paths.
+ -->
+ <property name="Calls" type="ao" access="read" />
+
+ </interface>
+</node>
--
1.9.1
_______________________________________________
ModemManager-devel mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/modemmanager-devel
