Re: [GnomeMeeting-devel-list] Dbus' future in gnomemeeting

[Jan Schampera <jan schampera web de>]

Julien,

thanks for your nice overview of the current API  interface. This is my
 thoughts as well as Kilian's (at least he agreed with me and made
many suggestions).

Original document currently stored at:
http://www.thebonsai.net/GM_IPC.pdf

---SNIP---

Suggestion for an application interface via DBUS to GnomeMeeting

<kk verfaction de>
<jan schampera web de>

1 Introduction

This is a suggestion for the DBUS API of Gnomemeeting, as asked for 
in MID<4347F48D 20401 free fr> from Julien PUYDT <jpuydt free fr> on 
the Gnomemeeting development Mailinglist.

The overall goal is to use less signals and methods to catch a huge 
amount of functionality, not to add a signal for every particular
meaning.

As Julien has suggested, the current API should scale to the full 
extent of what GM might become capable of. Therefore the several 
states should reflect all the possible local and remote availability 
information, as is currently displayed through the tray icon. What 
exactly has to be done to allow this or that condition is far beyond 
the scope of this text. It shows a direction, not the way.

2 States

2.1 Call states - how can a call look like

  CSTATE_CALLING

A call has this state, when an outgoing connection attempt is made.

  CSTATE_RING

This state indicates that this client gets a connection attempt from
outside.

  CSTATE_ESTABLISHED

The connection reaches this state either out of CSTATE_CALLING or
CSTATE_RING.

  CSTATE_PAUSING

Indicates that the client is trying to bring the connection to into 
CSTATE_PAUSED.

  CSTATE_PAUSED

Reached after a successful CSTATE_PAUSING operation.

  CSTATE_RESUMING

The client tries to bring the connection out of CSTATE_PAUSED.

  CSTATE_CLOSING

The client brings the connection down to CSTATE_UNCONNECTED.

  CSTATE_TRANSFERING

The call is being transferred to another client.

  CSTATE_MUTEDUSER

This call is put on mute mode within the conference upon moderator
request.

  CSTATE_BACKGROUND

The local client is no longer actively involved in the current 
conference. Also applies to attended transfer with proxy mode.

  CSTATE_ECHOMODE

Allow for echo testing like with OpenMCU.

  CSTATE_CONFJOINING

The client tries to join a conference with this call at the moment.

  CSTATE_CONFJOINED

This call is part of a conference.

  CSTATE_UNCONNECTED

A call associated to the requested call handle exists, but it isn't 
in any of the other states.

  CSTATE_ERROR

Indicates an error condition with this call, or an error condition 
in any action related to this call handle.

  CSTATE_NX

A call with the requested call handle doesn't exist. All other state 
bits set to zero.

2.2 Gnomemeeting application states

  APPSTATE_ACTIVECALL

Gnomemeeting is in an active call at the moment.

  APPSTATE_ACCEPTING

Accepting incoming calls (ready for operation).

  APPSTATE_DND

Automatically deny incoming calls.

  APPSTATE_AUTOANSWER

Automatically answer incoming calls.

  APPSTATE_AUTOFORWARD

Forward any incoming call.

  APPSTATE_FORWARDONBUSY

Forward incoming calls when APPSTATE_ACTIVECALL is set.

  APPSTATE_ACCEPTRESTRICTED

Accept only restricted calls.

  APPSTATE_ACCEPTMULTIPLE

Accepting calls when already in a call (Multicall).

  APPSTATE_RING

Ringing.

  APPSTATE_VOICEMAIL

One or more voicemail(s) waiting.

  APPSTATE_MISSEDCALLS

Missed calls in list.

  APPSTATE_TERMINATING

Application is closing. All other state bits unset. An IPC client 
should not send any DBUS message to Gnomemeeting after recieving this.

3 The interface

3.1 Signals

  CallAdded

Sent when Gnomemeeting adds a call, the given call handle is 
associated with this call.

Data: call handle

  CallDeleted

Sent when Gnomemeeting deletes a call. After this, the given call 
handle isn't valid anymore.

Data: call handle

  CallStateChange

Sent when the state of a connection changes

Data: call handle, call state

  GMStateChange

Sent when the state of the GM application itself changes

Data: GM state

3.2 Methods

  OpenCall

Sent to Gnomemeeting to request calling out.

IN: URL

OUT: call handle, initial call state (also indicates possible errors 
on call setup)

  CloseCall

Requests to close the call with the given call handle.

IN: call handle.

OUT: call state

  AlterCallParms

Alter the current call parameters. 

IN: call handle, requested call state

OUT: call state after altering (may include CSTATE_ERROR to set an 
error condition for the altering itself)

  GetCallState

To retrieve the state of the given call handle.

IN: call handle

OUT: call state

  GetCallInfo

To get extended information about the call, out of the scope of
GetCallState.

IN: call handle

OUT: String

  EnumCalls

To get a list of call handles of active calls.

IN: <none>

OUT: list of call handles

4 RATIONALE

4.1 Concept

Signal-, method- and bitnames are just verbose examples here - 
again, this is a concept, not an implementation. Implementation 
specific problems are out of the scope of this suggestion.

This concept assumes that Gnomemeeting opens a call handle for every 
call-related event, not only for active, running calls.

Some state informations are double in application and call state. 
The application state is meant in general, without further 
information, e.g. for a panel applet reporting only "Ringing".

4.2 Call states

Call states also including things for features Gnomemeeting doesn't 
have at the moment (usually MCU operation mode).

Which call states can be set or may occour under which particular 
conditions is also not topic of this text.

Call states should be minimum unsigned 32bit integer to be really 
future-proof.

4.3 Application states

The application state "TERMINATING" was choosen, because usually 
Gnomemeeting takes some time to shut down.

Applicaten states should, just like call states, be minimum unsigned 
32bit integer.

4.4 Signals

I tried to bring every neccesary information into these signals. It 
was suggested to use separate signals for particular events (e.g. 
shutdown), but all that can be done by reading the given application 
state information. That also means, that in some circumstances two 
signals will be sent - one for the call, with call handle, and one 
for the application, indicating its general state.

4.5 Methods

It is suggested to ensure that the CloseCall method can't be done by 
evil code or a crazy process. Thoughts? 

For future MCU mode things like

* ForgegroundUser to split one call from the conference for a 
  private question, and

* RejoinUser to merge back call to the conference after the private
question

may be needed.

The AlterCallParams method doesn't return a direct "exit state", but a 
resulting call state, with the CSTATE_ERROR flag used as result. 
This behaviour might not be the best.

I'm not sure if EnumCalls method's answer is a good practise: 
enumerating integer values. The IPC partner hast to GetCallInfo for 
every of these integers to get the final list.

Also methods to request the list of voicemails or missed calls may 
be useful.

4.6 Call handles 

A call handle should be an integer, which can be handled in a much 
better way then a string ("call token"). A descriptive string for a 
connection can be requested by GetCallInfo method if needed.

---SNIP---

Awaiting comments, flames and other stuff.

-- 
"Be liberal in what you accept, and conservative in what you send."
- J. B. Postel, master of the net.