Hi,here is a quick little file to document ekiga's dbus component. Should we add a doc/ directory in the cvs, with such files ?
SnarkTitle: Using Ekiga through DBUS
Let us see how ekiga would work to deal with a list of objects ('foo'), each having an integer property (bar), and a state (state). (Notice: the reader familiar with the way rosters are managed in XMPP/jabber will certainly feel at home with that organisation)
All such objects will have a unique string identifier/token/hash. Ekiga will tell us about those objects with two signals:
One of the state will be 'invalid', and will be emitted by ekiga to tell us one object was removed from the list. We will know an object was added to the list when we receive either FooState or FooBar about it.
This already allows a program watching for the signals to display the list and objects, and update it when it changes, with one caveat : if we launch the watcher after ekiga, we will not know the initial list!
This is the reason why ekiga will provide us the exceptional GetFooList method. It is exceptional because it returns something, namely the list of current valid identifiers. Beware that our example watcher should first start to watch the signals, and only then use GetFooList: remember that the list may be obsolete when we get it!
Once we have the list of identifiers, we can use the ResignalFooInfo method to ask ekiga to emit signals about the given identifier (this method doesn't return anything in itself). If the identifier is invalid (or has become since we got it!), ekiga will emit the FooState signal with the invalid state.
This part of the programming interface is enough to allow a watcher to display the list properly, and update it whenever it changes. Now what if don't want to just look at the list, but also act on it?
Ekiga may give us a DeleteFoo signal to remove an object from the list. This method won't return anything, but ekiga will emit the FooState signal in 'invalid' state if it worked.
Similarly, we may perhaps be allowed to add an object with a CreateFoo method, which would receive the value to give to the bar property. The method could either return the identifier of the new object, or nothing depending on the situation. Ekiga will emit the signals if the creation happened.
Finally, changing the value of the bar property, if possible, would be done with a SetFooBar method, which would receive the identifier and the new value. If things go well, ekiga will then emit the FooBar signal to tell us about the new value.
This little example interface is representative of how the other ekiga interfaces work, and hopefully the presentation makes it clear how to use it.
You can read directly in this file the current(cvs) list of interfaces available in ekiga, with their list of methods and signals. The rest of this document is a complement to this file and will try to make things more explicit.
Ekiga doesn't allow to do and know much about the available accounts. The interface is pretty straightforward ; the only thing needing more discussion is the semantics of the state integer.
The state can take three values:
This interface allows to control the calls in which ekiga takes part. This is currently a little stupid since ekiga can only handle one, but we left room for future improvements.
Let us begin this tour by documenting the semantics of the call states:
Ekiga allows to add and remove calls from the list, using the Connect and Disconnect methods, whose meaning should be pretty clear. Notice that Connect returns the call token, so if we decide to call someone we can track what happened.
Here are the various informations we can have about a call (not all of them may be available!):
The PlayPause method is used to put the call on hold, or release it from the hold. The Transfer method is when you want to send the remote party to talk to someone else.
This interface allows to get more information about ekiga's running instance.
It has simple methods like GetName, GetLocation and GetComment which allows to get what the user said in the preferences. The Shutdown command allows to quit ekiga.
And it has an interesting GetLocalAddress method, which allows to know which address to use to contact the user. You have to give it the protocol in which the address should be given (beware that it's reliable mostly for SIP). The goal of that method is to allow other programs, for example XMPP/jabber clients, to make us available for calls.
Since launching ekiga to have only basic informations would be bad (it is a rather big program), it comes with a helper program, which can take requests on its behalf for easy questions.
Of course, this helper is short-lived and exits automatically quite fast, so it is always in sync with the available ekiga.
The current helper knows only two methods:
To be completed(FIXME)