doc/supplementaryservices-api.txt

SupplementaryServices hierarchy
==========================

Service		org.ofono
Interface	org.ofono.SupplementaryServices
Object path	[variable prefix]/{modem0,modem1,...}

Methods		string, variant Initiate(string command)

			If the command is a recognized supplementary service
			control string, the corresponding SS request is made
			and the result is returned.

			Otherwise the command is sent to the network
			initiating a USSD session. When the request is handled
			by the appropriate node of the network, the
			method returns the response or an appropriate
			error. The network may be awaiting further response
			from the ME after returning from this method and no
			new command can be initiated until this one is
			cancelled or ended.

			The output arguments are described in section
			"Initiate method outptut arguments" below.

			Possible Errors: [service].Error.InProgress
					 [service].Error.NotImplemented
					 [service].Error.InvalidArguments
					 [service].Error.InvalidFormat
					 [service].Error.NotSupported
					 [service].Error.NotAllowed
					 [service].Error.IncorrectPassword
					 [service].Error.NotRegistered
					 [service].Error.Timedout
					 [service].Error.AccessDenied
					 [service].Error.Failed
					 [service].Error.NotRecognized
					 [service].Error.Terminated

		string Respond(string reply)

			Send a response to the network either when
			it is awaiting further input after Initiate()
			was called or after a network-initiated request.

			Possible Errors: [service].Error.InProgress
					 [service].Error.NotActive
					 [service].Error.NotImplemented
					 [service].Error.InvalidArguments
					 [service].Error.InvalidFormat
					 [service].Error.Failed
					 [service].Error.Terminated

		void Cancel()

			Cancel an ongoing USSD session, mobile- or
			network-initiated.

			Possible Errors: [service].Error.NotActive
					 [service].Error.InProgress
					 [service].Error.NotImplemented
					 [service].Error.Failed

		dict GetProperties()

			Returns Supplementary Services related properties. See
			the properties section for available properties.

Signals		NotificationReceived(string message)

			Signal is emitted on a network-initiated USSD
			request for which no response is needed.

		RequestReceived(string message)

			Signal is emitted on a network-initiated USSD
			request for which a response must be sent using
			the Respond method unless it is cancelled or
			the request is not supported.

		PropertyChanged(string property, variant value)

			Signal is emitted whenever a property has changed.
			The new value is passed as the signal argument.

Properties	string State [readonly]

			Reflects the state of current USSD session.  The
			values have the following meanings:

			"idle"			No active USSD session.
			"active"		A session is active between the
						network and the ME, the ME is
						waiting for a reply from the
						network.
			"user-response"		The network is waiting for the
						user's response, client must
						call Respond().


Initiate method output arguments
================================

The first return argument and the corresponding second return argument are:

	"USSD"				string ussd_response
	"CallBarring"			(string ss_op, string cb_service,
					dict cb_dict)
	"CallForwarding"		(string ss_op, string cf_service,
					dict cf_dict)
	"CallWaiting"			(string ss_op, dict cw_dict)
	"CallingLinePresentation"	(string ss_op, string status)
	"ConnectedLinePresentation"	(string ss_op, string status)
	"CallingLineRestriction"	(string ss_op, string clir_status)
	"ConnectedLineRestriction"	(string ss_op, string status)

ss_op contains the supplementary service operation:

	"activation"
	"registration"
	"interrogation"
	"deactivation"
	"erasure"

cb_service contains the call barring service for which the operation was
requested:

	"AllOutgoing"
	"InternationalOutgoing"
	"InternationalOutgoingExceptHome"
	"AllIncoming"
	"IncomingWhenRoaming"
	"AllBarringServices"
	"AllOutgoingServices"
	"AllIncomingServices"

cf_service contains the call forwarding service for which the operation was
requested:

	"Unconditional"
	"Busy"
	"NoReply"
	"NotReachable"
	"All"
	"AllConditional"

cb_dict contains basic service/call barring service combinations that were
affected by SS operation and their current status ("enabled" or "disabled").
The basic services are:

	"Voice"
	"Data"
	"Fax"
	"Sms"
	"DataSync"
	"DataAsync"
	"DataPad"
	"DataPacket"

To those the name of call barring service is appended, so the property and
value is for example:

	"FaxIncomingWhenRoaming" : "disabled"

cf_dict contains call forwarding properties affected by the operation.
Propery names are formed from basic service name and call forwarding
service name, for example:

	"VoiceNoReply" : "+12345678"

The property value is the phone number to which the call is forwarded.

For "NoReply" service, there is also a timeout property, holding the timeout
in seconds, for example:

	"VoiceNoReplyTimeout" : 20

cw_dict contains basic services with "CallWaiting" suffix that were affected
by call waiting operation and their current status ("enabled" or "disabled"),
for example:

	"VoiceCallWaiting" : "enabled"

status can be "disabled" or "enabled".
clir_status can be "disabled", "permanent", "on" or "off".

More information about supplementary services is provided in
call-barring-api.txt, call-forwarding-api.txt and call-settings-api.txt