From 89bbf66ae8cf877b53cd277c45058145bff2ca3e Mon Sep 17 00:00:00 2001 From: Marcel Holtmann Date: Wed, 12 Aug 2009 16:43:34 -0700 Subject: [PATCH] Add API documentation for voice call interfaces --- doc/Makefile.am | 3 +- doc/voicecall-api.txt | 106 ++++++++++++++++++++++++++++++++++ doc/voicecallmanager-api.txt | 131 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 239 insertions(+), 1 deletion(-) create mode 100644 doc/voicecall-api.txt create mode 100644 doc/voicecallmanager-api.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index 4c9473e..9ae9ff7 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,7 @@ man_MANS = ofonod.8 EXTRA_DIST = $(man_MANS) overview.txt \ - manager-api.txt modem-api.txt network-api.txt + manager-api.txt modem-api.txt network-api.txt \ + voicecallmanager-api.txt voicecall-api.txt MAINTAINERCLEANFILES = Makefile.in diff --git a/doc/voicecall-api.txt b/doc/voicecall-api.txt new file mode 100644 index 0000000..62db5a1 --- /dev/null +++ b/doc/voicecall-api.txt @@ -0,0 +1,106 @@ +VoiceCall hierarchy +=================== + +Service org.ofono +Interface org.ofono.VoiceCall +Object path [variable prefix]/{modem0,modem1,...}/{call0,call1,...} + +Methods dict GetProperties() + + Returns all global system properties. See the + properties section for available properties. + + Possible Errors: [service].Error.InvalidArguments + + void Busy() + + Notifies the incoming or waiting call that the user + is busy. This is done by setting the User Determined + User Busy (UDUB) condition. This method is only valid + if there is an incoming or waiting call. + + This functionality is generally implemented by using + the +CHLD=0 AT command. + + void Deflect(string number) + + Deflects the incoming or waiting call to number given + in the argument. This method is only valid if the + call is in "incoming" or "waiting" state and the + Call Deflection supplementary service is subscribed to. + + This functionality is generally implemented by using + the +CHLD=4 * NUMBER command. + + This method should not be confused with the Transfer() + method. + + void Hangup() + + Hangs up the voice call. + + This functionality is generally implemented by + +CHLD=1X, +CHUP or ATH AT commands. + + void Answer() + + Answers the incoming call. Only valid if the state + of the call is "incoming." + + This functionality is generally implemented by ATA + AT command. + +Signals PropertyChanged(string property, variant value) + + Signal is emitted whenever a property has changed. + The new value is passed as the signal argument. + + DisconnectReason(string reason) + + This signal is emitted when the modem manager can + provide extra information about why this call was + released. The possible reason values are: + "local" - The call was release due to local user action + "remote" - Remote party released the call + "network" - Network released the call, most likely due + to low signal or other network + failure + + Not all implementations are able to provide this + information, so applications should treat the emission + of this signal as optional. This signal will be + emitted before the PropertyChanged signal. + +Properties string LineIdentification [readonly] + + Contains the Line Identification information returned + by the network, if present. For incoming calls this is + effectively the CLIP. For outgoing calls this attribute + will hold the dialed number, or the COLP if received by + the underlying implementation. + + Please note that COLP may be different from the + dialed number. A special "withheld" value means the + remote party refused to provide caller ID and the + "override category" option was not provisioned for + the current subscriber. + + string State [readonly] + + Contains the state of the current call. The state + can be one of: + - "active" - The call is active + - "held" - The call is on hold + - "dialing" - The call is being dialed + - "alerting" - The remote party is being alerted + - "incoming" - Incoming call in progress + - "waiting" - Call is waiting + - "disconnected" - No further use of this object + is allowed, it will be destroyed shortly + + string StartTime [readonly, optional] + + Contains the starting time of the call. The time is + stamped when the call enters the "active" state. + Client applications can use this to infer somewhat + reliable call duration information. diff --git a/doc/voicecallmanager-api.txt b/doc/voicecallmanager-api.txt new file mode 100644 index 0000000..361370a --- /dev/null +++ b/doc/voicecallmanager-api.txt @@ -0,0 +1,131 @@ +VoiceCallManager hierarchy +========================== + +Service org.ofono +Interface org.ofono.VoiceCallManager +Object path [variable prefix]/{modem0,modem1,...} + +Methods dict GetProperties() + + Returns all global system properties. See the + properties section for available properties. + + Possible Errors: [service].Error.InvalidArguments + + object Dial(string number, string hide_callerid) + + Initiates a new outgoing call. Returns the object path + to the newly created call. The clir variable holds + the CLIR override for this call. + The defines values are: + "" or "default" - Default (Netowrk) CLIR mode + is used + "enabled" - Hides callerid, CLIR Invocation + is used + "disabled" - Shows callerid, CLIR Suppression + is used + + This is usually implemented using the ATD AT command. + + void Transfer() + + Joins the currently Active (or Outgoing, depending + on network support) and Held calls together and + disconnects both calls. In effect transfering + one party to the other. This procedure requires + an Active and Held call and the Explicit Call Transfer + (ECT) supplementary service to be active. + + This functionality is generally implemented by using + the +CHLD=4 AT command. + + void SwapCalls() + + Swaps Active and Held calls. The effect of this + is that all calls (0 or more including calls in a + multi-party conversation) that were Active are now Held, + and all calls (0 or more) that were Held are now Active. + + GSM specification does not allow calls to be swapped + in the case where Held, Active and Waiting calls exist. + Some modems implement this anyway, thus it is manufacturer + specific whether this method will succeed in the case + of Held, Active and Waiting calls. + + This functionality is generally implemented by using + the +CHLD=2 AT command. + + void ReleaseAndAnswer() + + Releases currently active call and answers the currently + waiting call. Please note that if the current call is + a multiparty call, then all parties in the multi-party + call will be released. + + void HoldAndAnswer() + + Puts the current call (including multi-party calls) on + hold and answers the currently waiting call. Calling + this function when a user already has a both Active and + Held calls is invalid, since in GSM a user can have + only a single Held call at a time. + + void HangupAllCalls() + + Releases all calls. + + array{object} PrivateChat(object call) + + Places the multi-party call on hold and makes desired + call active. This is used to accomplish private chat + functionality. Note that if there are only two calls + (three parties) in the multi-party call the result will + be two regular calls, one held and one active. The + Multiparty call will need to be setup again by using the + CreateMultiparty method. Returns the new list of calls + participating in the multiparty call. + + This is usually implemented using the +CHLD=2X command. + + array{object} CreateMultiparty() + + Joins active and held calls together into a multi-party + call. If one of the calls is already a multi-party + call, then the other call is added to the multiparty + conversation. Returns the new list of calls + participating in the multiparty call. + + There can only be one subscriber controlled multi-party + call according to the GSM specification. + + This is usually implemented using the +CHLD=3 AT + command. + + void HangupMultiparty() + + Hangs up the multi-party call. All participating + calls are released. + + void SendTones(string tones) + + Sends the DTMF tones to the network. Under GSM the + tones have a fixed duration. Tones can be one of: + '0' - '9', '*', '#', 'A', 'B', 'C', 'D'. The last four + are typically not used in normal circumstances. + +Signals PropertyChanged(string property, variant value) + + Signal is emitted whenever a property has changed. The + new value is passed as the signal argument. + +Properties array{object} Calls [readonly] + + Returns the list of calls currently present in the + system. If there are no calls, the list will be empty. + + array{object} MultipartyCalls [readonly] + + Returns the list of calls that are currently + participating in the multi-party (MPTY) call. The list + will be empty if no multi-party call is active, or a + list with at least two elements otherwise. -- 2.7.4