API Call proposal

[Dan Williams]

On Tue, 2015-04-21 at 11:59 +0200, Aleksander Morgado wrote:
> On Tue, Apr 21, 2015 at 11:42 AM, Riccardo Vangelisti
> <riccardo.vangelisti at sadel.it> wrote:
> > Fiuu... ;)
> >
> > I've attach'd the previuosly patch with CallLog renamed to Voice as you want
> > :)
> >
> 
> I think this is already a good start for an API.
> 
> Dan, what do you think?

I'd use "Hangup" instead of "HangUp".

I'd also add a u32 "reason" argument to StateChanged, to provide more
information later about why a call was terminated.  For example, was it
because it was an orderly termination, or due to network request (bad
signal), handoff failure, etc.  It doesn't have to be used right now,
but it's there for later.

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.

+ * MM_CALL_STATE_RINGING: call is waiting for an answer

Might be worth explicitly stating that this state is valid for both
locally (eg, incoming call waiting to be answered) and remotely
(outgoing call ringing on the other side).

+ * @MM_CALL_STATE_ACCEPTED: call is active between two peers

Maybe ACTIVE here?  To me, semantically acceptance happens at one
specific point in the process, after that (for 2 seconds or 1 hour or 2
hours) it's just an active call.

I think we also need STATE_HELD to indicate when the call is on hold
(see +CHLD docs), and STATE_WAITING (+CCWA).

+ * @MM_CALL_STATE_TERMINATED: call is terminated
+ * @MM_CALL_STATE_REFUSED: call is refused or busy
+ * @MM_CALL_STATE_ERROR: call in error (wrong number, network

Could these be converted into "reason" codes instead?

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.

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.

I would make the methods/signals a bit more explicit, eg ListCalls,
CreateCall, DeleteCall, CallAdded, CallDeleted.

DeleteCall needs more explanation; obviously it will terminate (hang up,
disconnect) the call and release any resources.  Basically it's just
like Hangup() right?

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.

In any case, thanks for working on this Riccardo, lets keep moving it
foward!

Dan