Please comment on callhistory API

Please comment on callhistory API

[rajyalakshmi bommaraju]

[-- Attachment #1: Type: text/plain, Size: 2916 bytes --]

Hello,
Attached Callhistory API , please send me your feedback on it, I will 
extend this include SmsHistory once callhistory API looks good.

Thanks
Raji


							Callhistory Adapter-Agent


	CallHistoryAdapter is a built in plugin for ofono. It uses CallHistoryAgent api exposed by dialer or client daemon to push voice call history information to client. CallHistoryAgent api is an service interface exposed by client over dbus. Plugin exposes CallHistoryAdapter interface that CallHistoryAgent registers and unregisters with. if the CallHistoryAgent registers with Adapter then plugin pushes the history information to dialer as soon as it receives from ofono, otherwise it caches the data in a disk file until agent registers, once agent registers plugin will read the data from the disk file and pushes all the records to it.


Adapter: 

it is going to register and unregister the agent. Calls the methods on the agent for delivering history information whent the agent is up and running. If the record cant be delivered that means agent method returns an error then it will be written to the disk file. If the agent is down it will persist history record in disk file.


CallHistoryAdapter hierarchy
============================

Service 	: org.ofono
Interface	: org.ofono.CallHistoryAdapter
Object path	: freely definable

Methods		void RegisterAgent (objectpath)  

			RegisterAgent method registers the agent object path. Methods on this agent will be called if history needs to push data.  

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.InvalidFormat
					 [service].Error.InUse

		void UnregisterAgent (objectpath) 

			UnregisterAgent method unregister the already registered agent object path.

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.InvalidFormat
					 [service].Error.InUse


CallHistoryAgent hierarchy
==========================

Service Name	: Unique Name
Interface	: org.ofono.CallHistoryAgent
Objectpath	: Freely definable

Methods		void SendHistory(array {struct {uint32,uint32,uint8,uint32,uint32} }) 

			This method gets called by ofono to deliver one record of voice call history.
		
			Possible Errors: [service].Error.Unsuccessful

		void SendCachedHistory(array {struct {uint32,uint32,uint8,uint32,uint32} })

			This method gets called by the ofono when CallHistoryAgent starts running. 
			It delivers all the history records as an array of structures.

			Possible Errors: [service].Error.Unsuccessful

		void Release() 
			Cleans up agent, assumes that agent is already unregistered, so not needed to unregister. 

CallHistory Record 
================
 
CallHistoryRecord {
		uint32	uid;
		uint8	voicecalltype;
		char	lineid[20];
		uint32	starttime;
		uint32	endtime;
}

voicecalltype {
	outgoing = 0,
	incoming = 1,
	missed = 2
}
		

Re: Please comment on callhistory API

[Marcel Holtmann]

[-- Attachment #1: Type: text/plain, Size: 5285 bytes --]

Hi Raji,

> Attached Callhistory API , please send me your feedback on it, I will 
> extend this include SmsHistory once callhistory API looks good.

please include such text in the email and not as attachment. We wanna
review it and not bother with just having to save it to disk first, then
copy it back into the response email to have to comment on it. I prefer
reading this and patches directly in my email client.

> 							Callhistory Adapter-Agent
> 
> 
> 	CallHistoryAdapter is a built in plugin for ofono. It uses CallHistoryAgent api exposed by dialer or client daemon to push voice call history information to client. CallHistoryAgent api is an service interface exposed by client over dbus. Plugin exposes CallHistoryAdapter interface that CallHistoryAgent registers and unregisters with. if the CallHistoryAgent registers with Adapter then plugin pushes the history information to dialer as soon as it receives from ofono, otherwise it caches the data in a disk file until agent registers, once agent registers plugin will read the data from the disk file and pushes all the records to it.
> 
> 
> Adapter: 
> 
> it is going to register and unregister the agent. Calls the methods on the agent for delivering history information whent the agent is up and running. If the record cant be delivered that means agent method returns an error then it will be written to the disk file. If the agent is down it will persist history record in disk file.
> 
> 
> CallHistoryAdapter hierarchy
> ============================
> 
> Service 	: org.ofono
> Interface	: org.ofono.CallHistoryAdapter
> Object path	: freely definable

What is Adapter meaning here. Just CallHistory would be fine. And makes
is more consistent with STK Agent.

The object path is not freely definable. You do have to pick one.

> Methods		void RegisterAgent (objectpath)  
> 
> 			RegisterAgent method registers the agent object path. Methods on this agent will be called if history needs to push data.  
> 
> 			Possible Errors: [service].Error.InvalidArguments
> 					 [service].Error.InvalidFormat
> 					 [service].Error.InUse

What is InvalidFormat? Fair enough, you copied this from STK Agent and
it uses this for invalid object path. I don't even think this is needed
at all since the D-Bus system daemon will ensure this, but fair enough
leave that in since STK Agent is using it similar. Consistency is good.

> 		void UnregisterAgent (objectpath) 
> 
> 			UnregisterAgent method unregister the already registered agent object path.
> 
> 			Possible Errors: [service].Error.InvalidArguments
> 					 [service].Error.InvalidFormat
> 					 [service].Error.InUse
> 
> 
> CallHistoryAgent hierarchy
> ==========================
> 
> Service Name	: Unique Name
> Interface	: org.ofono.CallHistoryAgent
> Objectpath	: Freely definable
> 
> Methods		void SendHistory(array {struct {uint32,uint32,uint8,uint32,uint32} }) 
> 
> 			This method gets called by ofono to deliver one record of voice call history.
> 		
> 			Possible Errors: [service].Error.Unsuccessful

Yeah. No way. Use a dictionary. We are not modeling some weird memory
structure via D-Bus. That is not extendable at all.

> 		void SendCachedHistory(array {struct {uint32,uint32,uint8,uint32,uint32} })
> 
> 			This method gets called by the ofono when CallHistoryAgent starts running. 
> 			It delivers all the history records as an array of structures.
> 
> 			Possible Errors: [service].Error.Unsuccessful

No.

One method for both here. If the client calls RegisterAgent then at that
point you start sending out the cached history. No need to make a
differentiation here. The client doesn't care. It just needs to get the
information.

> 		void Release() 
> 			Cleans up agent, assumes that agent is already unregistered, so not needed to unregister. 
> 
> CallHistory Record 
> ================
>  
> CallHistoryRecord {
> 		uint32	uid;
> 		uint8	voicecalltype;
> 		char	lineid[20];
> 		uint32	starttime;
> 		uint32	endtime;
> }
> 
> voicecalltype {
> 	outgoing = 0,
> 	incoming = 1,
> 	missed = 2
> }

Define proper dictionary key/type values pair like we do for property or
use inside the Messaging API already. Consistency.

	New immediate (class 0) SMS received. Info has Sender,
	LocalSentTime, and SentTime information.  Sender
	address is given in string format.  LocalSentTime and
	SentTime are given in string form using ISO8601 format.

So it defines already LocalSentTime, SentTime and Sender. And voicecall
already defines LineIdentifcation.

	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.

This could be all nicely re-used. I think you get the idea.

If the call history agent is a global agent, then you need to include
the modem object path here as well. So that a client could identify from
which modem this came. Over time the modem could change, but the IMSI
could stay the same. Or just include the IMSI here. We need to discuss
this, but keep it in mind.

Regards

Marcel

Re: Please comment on callhistory API

[rajyalakshmi bommaraju]

[-- Attachment #1: Type: text/plain, Size: 3091 bytes --]

Hello Marcel,
I have incorporated your feedback into the document . Please let me know 
if anything needs to be changed.

Thanks
Raji

			Callhistory Adapter-Agent


CallHistory is a built in plugin for ofono. It uses CallHistoryAgent api 
exposed by client to push voice call history information. 
CallHistoryAgent api is a service interface exposed by client over dbus. 
Plugin exposes CallHistory interface that CallHistoryAgent registers and 
unregisters with. if the CallHistoryAgent registers with CallHistory 
then plugin pushes the history information to the agent soon as it 
receives from ofono, otherwise it caches the data in a disk file until 
agent registers, once agent registers plugin will read the data from the 
disk file and pushes all the records to it.

CallHistory:

it is going to register and unregister the agent. It calls the methods 
on the agent for delivering history information whent the agent is up 
and running. The history record will be written to the disk if agent 
method returns error or if the agent is not running.


CallHistory hierarchy
=============

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

Methods 	void RegisterAgent (objectpath)

			RegisterAgent method registers the agent object path. Methods on this 
			agent will be called if history needs to push data.

			Possible Errors: [service].Error.InvalidArguments
			[service].Error.InvalidFormat
			[service].Error.InUse

		void UnregisterAgent (objectpath)

			UnregisterAgent method unregister the already registered agent object path.

			Possible Errors: [service].Error.InvalidArguments
			[service].Error.InvalidFormat
			[service].Error.InUse

CallHistoryAgent hierarchy
================

Service Name : Unique Name
Interface : org.ofono.CallHistoryAgent
Objectpath : Freely definable

Methods 	void SendHistory( array{dict})

			This method gets called by ofono to deliver an array of records. Each 
			record is represented as a dictionary, all the dict properties are 
			described in the "Properties" section.

			Possible Errors: [service].Error.Unsuccessful

		void Release()
			Cleans up agent, assumes that agent is already unregistered, so not 
			needed to unregister.

Properties
=======
		integer Uid [Read Only]
			Integer representing the unique id of the history record

		string Calltype [Read Only]
			string representing the call type. Call type can be one of the following 
			three alternatives
			"outgoing" - it is an outgoing call
			"incoming" - it is an incoming call
			"missed" - it is a missed call

		string LineIdentification [Read Only]
			string representing the LineIdentification , for outgoing call it is the 
			phone number dialed. For Incoming call it is the CLIP, or COLP if 
			received by the underlying implementation.

		string StartTime [Read Only]
			String representing start time of the call

		string EndTime [Read Only]
			String representing end time of the call

Re: Please comment on callhistory API

[Marcel Holtmann]

[-- Attachment #1: Type: text/plain, Size: 3273 bytes --]

Hi Raji,

> CallHistory hierarchy
> =============
> 
> Service : org.ofono
> Interface : org.ofono.CallHistory
> Object path : [variable prefix]/{modem0,modem1,...}/CallHistory

the object path is wrong here. This should be pretty much on the main /
object path. And not on per modem and not in a sub-path.

I really don't think that per modem history makes sense. Denis?

> Methods 	void RegisterAgent (objectpath)
> 
> 			RegisterAgent method registers the agent object path. Methods on this 
> 			agent will be called if history needs to push data.
> 
> 			Possible Errors: [service].Error.InvalidArguments
> 			[service].Error.InvalidFormat
> 			[service].Error.InUse
> 
> 		void UnregisterAgent (objectpath)
> 
> 			UnregisterAgent method unregister the already registered agent object path.
> 
> 			Possible Errors: [service].Error.InvalidArguments
> 			[service].Error.InvalidFormat
> 			[service].Error.InUse
> 
> CallHistoryAgent hierarchy
> ================
> 
> Service Name : Unique Name
> Interface : org.ofono.CallHistoryAgent
> Objectpath : Freely definable

So I am actually thinking this should be just History and HistoryAgent
interfaces. Since we can differentiate between different types by the
different methods in the agent.

> Methods 	void SendHistory( array{dict})
> 
> 			This method gets called by ofono to deliver an array of records. Each 
> 			record is represented as a dictionary, all the dict properties are 
> 			described in the "Properties" section.
> 
> 			Possible Errors: [service].Error.Unsuccessful

We have to do some semantical things here first. So you proposal here is
to do org.ofono.CallHistoryAgent.SendHistory. The "History" part is used
twice here. That is never a good idea. Also it is not really sending a
history per se. It is more reporting one and just one at a time. So it
is not history it reports, it is a call.

So my proposal here is just to have one method for ReportCall and
another one for ReportTextMessage etc.

> 		void Release()
> 			Cleans up agent, assumes that agent is already unregistered, so not 
> 			needed to unregister.
> 
> Properties
> =======
> 		integer Uid [Read Only]
> 			Integer representing the unique id of the history record

In this case I would prefer UID as value and in uint32 please. D-Bus
doesn't have an integer type.

Also do we actually need this? Denis?

> 		string Calltype [Read Only]
> 			string representing the call type. Call type can be one of the following 
> 			three alternatives
> 			"outgoing" - it is an outgoing call
> 			"incoming" - it is an incoming call
> 			"missed" - it is a missed call

If is is the call history dict then just Type is good enough. No idea to
duplicate the work Call all over the place.

> 
> 		string LineIdentification [Read Only]
> 			string representing the LineIdentification , for outgoing call it is the 
> 			phone number dialed. For Incoming call it is the CLIP, or COLP if 
> 			received by the underlying implementation.
> 
> 		string StartTime [Read Only]
> 			String representing start time of the call
> 
> 		string EndTime [Read Only]
> 			String representing end time of the call

These looks fine.

Regards

Marcel

Re: Please comment on callhistory API

[rajyalakshmi bommaraju]

[-- Attachment #1: Type: text/plain, Size: 4306 bytes --]

Marcel,

org.ofono.History will be the main adapter interface and 
org.ofono.CallHistoryAgent the callhistory agent and 
org.ofono.SmsHistoryAgent as the sms history agent. I want to seperate 
the two agents so that sms app will expose sms history agent and dialer 
will register and expose callhistory agent. Then it will be clear which 
agent is interested in which history, vs one org.ofono.HistoryAgent 
exposing ReportCall and ReportTextMessage methods. In the later case 
adapter needs to flush both smshistory and callsistory onto two agents 
even though agents are not interested only in type of history.

Does it sound reasonable?
Thanks,
Raji

Marcel Holtmann wrote:
> Hi Raji,
>
>   
>> CallHistory hierarchy
>> =============
>>
>> Service : org.ofono
>> Interface : org.ofono.CallHistory
>> Object path : [variable prefix]/{modem0,modem1,...}/CallHistory
>>     
>
> the object path is wrong here. This should be pretty much on the main /
> object path. And not on per modem and not in a sub-path.
>
> I really don't think that per modem history makes sense. Denis?
>
>   
>> Methods 	void RegisterAgent (objectpath)
>>
>> 			RegisterAgent method registers the agent object path. Methods on this 
>> 			agent will be called if history needs to push data.
>>
>> 			Possible Errors: [service].Error.InvalidArguments
>> 			[service].Error.InvalidFormat
>> 			[service].Error.InUse
>>
>> 		void UnregisterAgent (objectpath)
>>
>> 			UnregisterAgent method unregister the already registered agent object path.
>>
>> 			Possible Errors: [service].Error.InvalidArguments
>> 			[service].Error.InvalidFormat
>> 			[service].Error.InUse
>>
>> CallHistoryAgent hierarchy
>> ================
>>
>> Service Name : Unique Name
>> Interface : org.ofono.CallHistoryAgent
>> Objectpath : Freely definable
>>     
>
> So I am actually thinking this should be just History and HistoryAgent
> interfaces. Since we can differentiate between different types by the
> different methods in the agent.
>
>   
>> Methods 	void SendHistory( array{dict})
>>
>> 			This method gets called by ofono to deliver an array of records. Each 
>> 			record is represented as a dictionary, all the dict properties are 
>> 			described in the "Properties" section.
>>
>> 			Possible Errors: [service].Error.Unsuccessful
>>     
>
> We have to do some semantical things here first. So you proposal here is
> to do org.ofono.CallHistoryAgent.SendHistory. The "History" part is used
> twice here. That is never a good idea. Also it is not really sending a
> history per se. It is more reporting one and just one at a time. So it
> is not history it reports, it is a call.
>
> So my proposal here is just to have one method for ReportCall and
> another one for ReportTextMessage etc.
>
>   
>> 		void Release()
>> 			Cleans up agent, assumes that agent is already unregistered, so not 
>> 			needed to unregister.
>>
>> Properties
>> =======
>> 		integer Uid [Read Only]
>> 			Integer representing the unique id of the history record
>>     
>
> In this case I would prefer UID as value and in uint32 please. D-Bus
> doesn't have an integer type.
>
> Also do we actually need this? Denis?
>
>   
>> 		string Calltype [Read Only]
>> 			string representing the call type. Call type can be one of the following 
>> 			three alternatives
>> 			"outgoing" - it is an outgoing call
>> 			"incoming" - it is an incoming call
>> 			"missed" - it is a missed call
>>     
>
> If is is the call history dict then just Type is good enough. No idea to
> duplicate the work Call all over the place.
>
>   
>> 		string LineIdentification [Read Only]
>> 			string representing the LineIdentification , for outgoing call it is the 
>> 			phone number dialed. For Incoming call it is the CLIP, or COLP if 
>> 			received by the underlying implementation.
>>
>> 		string StartTime [Read Only]
>> 			String representing start time of the call
>>
>> 		string EndTime [Read Only]
>> 			String representing end time of the call
>>     
>
> These looks fine.
>
> Regards
>
> Marcel
>
>
> _______________________________________________
> ofono mailing list
> ofono(a)ofono.org
> http://lists.ofono.org/listinfo/ofono
>   

Re: Please comment on callhistory API

[Marcel Holtmann]

[-- Attachment #1: Type: text/plain, Size: 1292 bytes --]

Hi Raji,

this is the second time I have to remind you to not top post. Next time
I will ignore your email. Just a friendly reminder to follow proper
mailing list etiquette.

> org.ofono.History will be the main adapter interface and 
> org.ofono.CallHistoryAgent the callhistory agent and 
> org.ofono.SmsHistoryAgent as the sms history agent. I want to seperate 
> the two agents so that sms app will expose sms history agent and dialer 
> will register and expose callhistory agent. Then it will be clear which 
> agent is interested in which history, vs one org.ofono.HistoryAgent 
> exposing ReportCall and ReportTextMessage methods. In the later case 
> adapter needs to flush both smshistory and callsistory onto two agents 
> even though agents are not interested only in type of history.

actually not really. So why does the dialer and SMS application need to
register for the history? Isn't that going to be stored central in
Tracker or something similar. Should not be Tracker or some Tracker
helper be registering the agent?

I might be wrong, but does it really make sense to separate it on this
level?

And it needs to be MessageHistoryAgent if we decide to go for this. We
banned the shortcut "sms" from the rest of the API.

Regards

Marcel

Re: Please comment on callhistory API

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 1057 bytes --]

Hi Marcel,

On 09/27/2010 12:50 PM, Marcel Holtmann wrote:
> Hi Raji,
> 
>> CallHistory hierarchy
>> =============
>>
>> Service : org.ofono
>> Interface : org.ofono.CallHistory
>> Object path : [variable prefix]/{modem0,modem1,...}/CallHistory
> 
> the object path is wrong here. This should be pretty much on the main /
> object path. And not on per modem and not in a sub-path.
> 
> I really don't think that per modem history makes sense. Denis?

The idea here is that you can track history by the modem object or more
likely the IMSI.  Thus when switching SIMs or in dual-sim mode phones,
the history shown might change depending on the current SIM.

>> Properties
>> =======
>> 		integer Uid [Read Only]
>> 			Integer representing the unique id of the history record
> 
> In this case I would prefer UID as value and in uint32 please. D-Bus
> doesn't have an integer type.
> 
> Also do we actually need this? Denis?

This is not actually needed, we only track when a call has been ended or
missed.

Regards,
-Denis

Re: Please comment on callhistory API

[Marcel Holtmann]

[-- Attachment #1: Type: text/plain, Size: 981 bytes --]

Hi Denis,

> >> CallHistory hierarchy
> >> =============
> >>
> >> Service : org.ofono
> >> Interface : org.ofono.CallHistory
> >> Object path : [variable prefix]/{modem0,modem1,...}/CallHistory
> > 
> > the object path is wrong here. This should be pretty much on the main /
> > object path. And not on per modem and not in a sub-path.
> > 
> > I really don't think that per modem history makes sense. Denis?
> 
> The idea here is that you can track history by the modem object or more
> likely the IMSI.  Thus when switching SIMs or in dual-sim mode phones,
> the history shown might change depending on the current SIM.

by modem makes no sense. That might change at any time. For example even
if you get a phone replacement. So not really helpful.

The IMSI I can see, but isn't it better then just to include the IMSI
into the report send to the history application. Not that I actually
like sending the IMSI around so much :(

Regards

Marcel

Re: Please comment on callhistory API

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 1179 bytes --]

Hi Marcel,

On 09/27/2010 06:14 PM, Marcel Holtmann wrote:
> Hi Denis,
> 
>>>> CallHistory hierarchy
>>>> =============
>>>>
>>>> Service : org.ofono
>>>> Interface : org.ofono.CallHistory
>>>> Object path : [variable prefix]/{modem0,modem1,...}/CallHistory
>>>
>>> the object path is wrong here. This should be pretty much on the main /
>>> object path. And not on per modem and not in a sub-path.
>>>
>>> I really don't think that per modem history makes sense. Denis?
>>
>> The idea here is that you can track history by the modem object or more
>> likely the IMSI.  Thus when switching SIMs or in dual-sim mode phones,
>> the history shown might change depending on the current SIM.
> 
> by modem makes no sense. That might change at any time. For example even
> if you get a phone replacement. So not really helpful.
> 
> The IMSI I can see, but isn't it better then just to include the IMSI
> into the report send to the history application. Not that I actually
> like sending the IMSI around so much :(

Actually per modem does make sense for HFP use cases where the device is
essentially unique and IMSI is not provided.

Regards,
-Denis

Re: Please comment on callhistory API

[rajyalakshmi bommaraju]

[-- Attachment #1: Type: text/plain, Size: 1844 bytes --]

Hello Marcel,
Marcel Holtmann wrote:
> Hi Raji,
>
> this is the second time I have to remind you to not top post. Next time
> I will ignore your email. Just a friendly reminder to follow proper
> mailing list etiquette.
>
>   
>> org.ofono.History will be the main adapter interface and 
>> org.ofono.CallHistoryAgent the callhistory agent and 
>> org.ofono.SmsHistoryAgent as the sms history agent. I want to seperate 
>> the two agents so that sms app will expose sms history agent and dialer 
>> will register and expose callhistory agent. Then it will be clear which 
>> agent is interested in which history, vs one org.ofono.HistoryAgent 
>> exposing ReportCall and ReportTextMessage methods. In the later case 
>> adapter needs to flush both smshistory and callsistory onto two agents 
>> even though agents are not interested only in type of history.
>>     
>
> actually not really. So why does the dialer and SMS application need to
> register for the history? Isn't that going to be stored central in
> Tracker or something similar. Should not be Tracker or some Tracker
> helper be registering the agent?
>   
No, Dialer and Sms applications are the ones that read and stores 
locally, this will probably move to tracker eventually.
So I dont think we can assume that there is going to be a tracker agent.
> I might be wrong, but does it really make sense to separate it on this
> level?
>   
I am thinking by separating the applications will only register and get 
data they are interested in.
> And it needs to be MessageHistoryAgent if we decide to go for this. We
> banned the shortcut "sms" from the rest of the API.
>
> Regards
>
> Marcel
>
>
> _______________________________________________
> ofono mailing list
> ofono(a)ofono.org
> http://lists.ofono.org/listinfo/ofono
>   

Re: Please comment on callhistory API

[Marcel Holtmann]

[-- Attachment #1: Type: text/plain, Size: 2679 bytes --]

Hi Raji,

> > this is the second time I have to remind you to not top post. Next time
> > I will ignore your email. Just a friendly reminder to follow proper
> > mailing list etiquette.
> >
> >   
> >> org.ofono.History will be the main adapter interface and 
> >> org.ofono.CallHistoryAgent the callhistory agent and 
> >> org.ofono.SmsHistoryAgent as the sms history agent. I want to seperate 
> >> the two agents so that sms app will expose sms history agent and dialer 
> >> will register and expose callhistory agent. Then it will be clear which 
> >> agent is interested in which history, vs one org.ofono.HistoryAgent 
> >> exposing ReportCall and ReportTextMessage methods. In the later case 
> >> adapter needs to flush both smshistory and callsistory onto two agents 
> >> even though agents are not interested only in type of history.
> >>     
> >
> > actually not really. So why does the dialer and SMS application need to
> > register for the history? Isn't that going to be stored central in
> > Tracker or something similar. Should not be Tracker or some Tracker
> > helper be registering the agent?
> >   
> No, Dialer and Sms applications are the ones that read and stores 
> locally, this will probably move to tracker eventually.
> So I dont think we can assume that there is going to be a tracker agent.
> > I might be wrong, but does it really make sense to separate it on this
> > level?
> >   
> I am thinking by separating the applications will only register and get 
> data they are interested in.

so Denis and I had a long chat about this. And essentially the history
agent concept is not really something that we should maintain long term.
We need be able to Tracker to listen on the D-Bus system bus and have
oFono history plugin send data directly to Tracker. The history plugin
should track if Tracker is running or not. If not spool. Otherwise send
data to Tracker directly. Everything else is a pretty much complicated
design.

However for a short term solution, you could do a history agent concept
as part of a MeeGo specific plugin.

So use org.ofono as D-Bus service name and com.meego.TelephonyHistory
and com.meego.TelephonyHistoryAgent as interface names.

The main object path is / since are not going to make this based on a
per modem.

Two method calls in the agent a) ReportVoiceCall a) ReportTextMessage
and that is it in. In the info dict include the Modem property which
points to the modem object this information originates from.

Failure of not existing a) or b) should be handled gracefully so that in
the first error case we don't retry anymore.

Regards

Marcel

Re: Please comment on callhistory API

[rajyalakshmi bommaraju]

[-- Attachment #1: Type: text/plain, Size: 3913 bytes --]

Marcel,
Marcel Holtmann wrote:
> Hi Raji,
>
>   
>>> this is the second time I have to remind you to not top post. Next time
>>> I will ignore your email. Just a friendly reminder to follow proper
>>> mailing list etiquette.
>>>
>>>   
>>>       
>>>> org.ofono.History will be the main adapter interface and 
>>>> org.ofono.CallHistoryAgent the callhistory agent and 
>>>> org.ofono.SmsHistoryAgent as the sms history agent. I want to seperate 
>>>> the two agents so that sms app will expose sms history agent and dialer 
>>>> will register and expose callhistory agent. Then it will be clear which 
>>>> agent is interested in which history, vs one org.ofono.HistoryAgent 
>>>> exposing ReportCall and ReportTextMessage methods. In the later case 
>>>> adapter needs to flush both smshistory and callsistory onto two agents 
>>>> even though agents are not interested only in type of history.
>>>>     
>>>>         
>>> actually not really. So why does the dialer and SMS application need to
>>> register for the history? Isn't that going to be stored central in
>>> Tracker or something similar. Should not be Tracker or some Tracker
>>> helper be registering the agent?
>>>   
>>>       
>> No, Dialer and Sms applications are the ones that read and stores 
>> locally, this will probably move to tracker eventually.
>> So I dont think we can assume that there is going to be a tracker agent.
>>     
>>> I might be wrong, but does it really make sense to separate it on this
>>> level?
>>>   
>>>       
>> I am thinking by separating the applications will only register and get 
>> data they are interested in.
>>     
>
> so Denis and I had a long chat about this. And essentially the history
> agent concept is not really something that we should maintain long term.
> We need be able to Tracker to listen on the D-Bus system bus and have
> oFono history plugin send data directly to Tracker. The history plugin
> should track if Tracker is running or not. If not spool. Otherwise send
> data to Tracker directly. Everything else is a pretty much complicated
> design.
>
> However for a short term solution, you could do a history agent concept
> as part of a MeeGo specific plugin.
>
> So use org.ofono as D-Bus service name and com.meego.TelephonyHistory
> and com.meego.TelephonyHistoryAgent as interface names.
>
> The main object path is / since are not going to make this based on a
> per modem.
>
> Two method calls in the agent a) ReportVoiceCall a) ReportTextMessage
> and that is it in. In the info dict include the Modem property which
> points to the modem object this information originates from.
 For outgoing TextMessages, ofono updates the history plugin in two method calls, first all the text message history related properties msg id, message , local received time,actual sent time, lineid and status='Pending' and in another method ofono updates plugin with the status. Earlier design, I sent out history record with pending status and  when I received  status update I  used  'property changed'  signal for status update. But I use 'uint32,variant' type which is not consistent with the current ofono property changed signal type. My questions,
 1) Are you ok with using signal for status update, this lets us send out history as soon as we receive them if the agent is running      

 2) If we want to avoid signal, then we can store the outgoing text message record until we receive the status update from ofono, combine them and send out in case of agent running. In case of agent not running we do this anyway. 

> Failure of not existing a) or b) should be handled gracefully so that in
> the first error case we don't retry anymore.
>
> Regards
>
> Marcel
>
>
> _______________________________________________
> ofono mailing list
> ofono(a)ofono.org
> http://lists.ofono.org/listinfo/ofono
>   

Re: Please comment on callhistory API

[Marcel Holtmann]

[-- Attachment #1: Type: text/plain, Size: 3826 bytes --]

Hi Raji,

> >>>> org.ofono.History will be the main adapter interface and 
> >>>> org.ofono.CallHistoryAgent the callhistory agent and 
> >>>> org.ofono.SmsHistoryAgent as the sms history agent. I want to seperate 
> >>>> the two agents so that sms app will expose sms history agent and dialer 
> >>>> will register and expose callhistory agent. Then it will be clear which 
> >>>> agent is interested in which history, vs one org.ofono.HistoryAgent 
> >>>> exposing ReportCall and ReportTextMessage methods. In the later case 
> >>>> adapter needs to flush both smshistory and callsistory onto two agents 
> >>>> even though agents are not interested only in type of history.
> >>>>     
> >>>>         
> >>> actually not really. So why does the dialer and SMS application need to
> >>> register for the history? Isn't that going to be stored central in
> >>> Tracker or something similar. Should not be Tracker or some Tracker
> >>> helper be registering the agent?
> >>>   
> >>>       
> >> No, Dialer and Sms applications are the ones that read and stores 
> >> locally, this will probably move to tracker eventually.
> >> So I dont think we can assume that there is going to be a tracker agent.
> >>     
> >>> I might be wrong, but does it really make sense to separate it on this
> >>> level?
> >>>   
> >>>       
> >> I am thinking by separating the applications will only register and get 
> >> data they are interested in.
> >>     
> >
> > so Denis and I had a long chat about this. And essentially the history
> > agent concept is not really something that we should maintain long term.
> > We need be able to Tracker to listen on the D-Bus system bus and have
> > oFono history plugin send data directly to Tracker. The history plugin
> > should track if Tracker is running or not. If not spool. Otherwise send
> > data to Tracker directly. Everything else is a pretty much complicated
> > design.
> >
> > However for a short term solution, you could do a history agent concept
> > as part of a MeeGo specific plugin.
> >
> > So use org.ofono as D-Bus service name and com.meego.TelephonyHistory
> > and com.meego.TelephonyHistoryAgent as interface names.
> >
> > The main object path is / since are not going to make this based on a
> > per modem.
> >
> > Two method calls in the agent a) ReportVoiceCall a) ReportTextMessage
> > and that is it in. In the info dict include the Modem property which
> > points to the modem object this information originates from.
>  For outgoing TextMessages, ofono updates the history plugin in two method calls, first all the text message history related properties msg id, message , local received time,actual sent time, lineid and status='Pending' and in another method ofono updates plugin with the status. Earlier design, I sent out history record with pending status and  when I received  status update I  used  'property changed'  signal for status update. But I use 'uint32,variant' type which is not consistent with the current ofono property changed signal type. My questions,
>  1) Are you ok with using signal for status update, this lets us send out history as soon as we receive them if the agent is running      
> 
>  2) If we want to avoid signal, then we can store the outgoing text message record until we receive the status update from ofono, combine them and send out in case of agent running. In case of agent not running we do this anyway. 

you can just send the method call (it is not a signal in this case) both
times. When you get the pending one and once the final one. The SMS
contains its own SHA-1 based id. So the history application can easily
update its database. It can be used as primary key. oFono ensures its
uniqueness as good as SHA-1 hash can do.

Regards

Marcel

Re: Please comment on callhistory API

[rajyalakshmi bommaraju]

[-- Attachment #1: Type: text/plain, Size: 10447 bytes --]

Marcel,

Marcel Holtmann wrote:
> Hi Raji,
>
>   
>>>>>> org.ofono.History will be the main adapter interface and 
>>>>>> org.ofono.CallHistoryAgent the callhistory agent and 
>>>>>> org.ofono.SmsHistoryAgent as the sms history agent. I want to seperate 
>>>>>> the two agents so that sms app will expose sms history agent and dialer 
>>>>>> will register and expose callhistory agent. Then it will be clear which 
>>>>>> agent is interested in which history, vs one org.ofono.HistoryAgent 
>>>>>> exposing ReportCall and ReportTextMessage methods. In the later case 
>>>>>> adapter needs to flush both smshistory and callsistory onto two agents 
>>>>>> even though agents are not interested only in type of history.
>>>>>>     
>>>>>>         
>>>>>>             
>>>>> actually not really. So why does the dialer and SMS application need to
>>>>> register for the history? Isn't that going to be stored central in
>>>>> Tracker or something similar. Should not be Tracker or some Tracker
>>>>> helper be registering the agent?
>>>>>   
>>>>>       
>>>>>           
>>>> No, Dialer and Sms applications are the ones that read and stores 
>>>> locally, this will probably move to tracker eventually.
>>>> So I dont think we can assume that there is going to be a tracker agent.
>>>>     
>>>>         
>>>>> I might be wrong, but does it really make sense to separate it on this
>>>>> level?
>>>>>   
>>>>>       
>>>>>           
>>>> I am thinking by separating the applications will only register and get 
>>>> data they are interested in.
>>>>     
>>>>         
>>> so Denis and I had a long chat about this. And essentially the history
>>> agent concept is not really something that we should maintain long term.
>>> We need be able to Tracker to listen on the D-Bus system bus and have
>>> oFono history plugin send data directly to Tracker. The history plugin
>>> should track if Tracker is running or not. If not spool. Otherwise send
>>> data to Tracker directly. Everything else is a pretty much complicated
>>> design.
>>>
>>> However for a short term solution, you could do a history agent concept
>>> as part of a MeeGo specific plugin.
>>>
>>> So use org.ofono as D-Bus service name and com.meego.TelephonyHistory
>>> and com.meego.TelephonyHistoryAgent as interface names.
>>>
>>> The main object path is / since are not going to make this based on a
>>> per modem.
>>>
>>> Two method calls in the agent a) ReportVoiceCall a) ReportTextMessage
>>> and that is it in. In the info dict include the Modem property which
>>> points to the modem object this information originates from.
>>>       
>>  For outgoing TextMessages, ofono updates the history plugin in two method calls, first all the text message history related properties msg id, message , local received time,actual sent time, lineid and status='Pending' and in another method ofono updates plugin with the status. Earlier design, I sent out history record with pending status and  when I received  status update I  used  'property changed'  signal for status update. But I use 'uint32,variant' type which is not consistent with the current ofono property changed signal type. My questions,
>>  1) Are you ok with using signal for status update, this lets us send out history as soon as we receive them if the agent is running      
>>
>>  2) If we want to avoid signal, then we can store the outgoing text message record until we receive the status update from ofono, combine them and send out in case of agent running. In case of agent not running we do this anyway. 
>>     

Updated API is below.
> History hierarchy
> ============================
>
> Service : org.ofono
> Interface : com.meego.TelephonyHistory
> Object path : /
>
> Methods void RegisterAgent (objectpath)
>
> RegisterAgent method registers the agent object path. Methods on this 
> agent will be called if history needs to push data.
>
> Possible Errors: [service].Error.InvalidArguments
> [service].Error.InvalidFormat
> [service].Error.InUse
>
> void UnregisterAgent (objectpath)
>
> UnregisterAgent method unregister the already registered agent object 
> path.
>
> Possible Errors: [service].Error.InvalidArguments
> [service].Error.InvalidFormat
> [service].Error.InUse
>
>
> HistoryAgent hierarchy
> ==========================
>
> Service Name : Unique Name
> Interface : com.meego.TelephonyHistoryAgent
> Objectpath : Freely definable
>
> Methods void ReportTextMessage( array{dict})
>
> This method gets called by ofono to deliver an array of records. Each 
> record is represented as a dictionary, all the dict properties are 
> described in the "Properties" section.
>
> Possible Errors: [service].Error.Failed
>
> void ReportVoiceCall( array{dict})
>
> This method gets called by ofono to deliver an array of records. Each 
> record is represented as a dictionary, all the dict properties are 
> described in the "Properties" section.
>
> Possible Errors: [service].Error.Failed
>
> void Release()
> Cleans up agent, assumes that agent is already unregistered, so not 
> needed to unregister.
>
> Properties
> ==========
> uint32 Uid [Read Only]
> Integer representing the internal representation of histroy message id.
>
> string Type [Read Only]
> string representing the type of the history message. Type can be one 
> of the following three alternatives.
>
> "outgoing" - it is an outgoing history message
> "incoming" - it is an incoming history message
> "missed" - It is a history message for missed call
>
> string LineIdentification [Read Only]
> string representing the LineIdentification , for outgoing message it 
> is the phone number dialed. For incoming message it is the CLIP, or 
> COLP if received by the underlying implementation.
>
> String Message [Read Only]
> string represents the text message.
>
> string LocalSentTime [Read Only]
> String representing local sent time.
>
> string SentTime [Read Only]
> String representing sent time.
>
> string StartTime [Read Only]
> String representing start time of the call
>
> string EndTime [Read Only]
> String representing end time of the call
>
> dict Information [Read Only]
> dict representing modem path from which this message originates
> "Modem" - will fetch object path of the modem

> Thanks
>   
Raji
_______________________________________________
> ofono mailing list
> ofono(a)ofono.org
> http://lists.ofono.org/listinfo/ofono
>   



							History Adapter-Agent


	History is a built in plugin for ofono. It uses HistoryAgent api exposed by client to push history information. HistoryAgent api is a service interface exposed by client over dbus. Plugin exposes History interface that HistoryAgent registers and unregisters with. if the HistoryAgent registers with History then plugin pushes the history information to agent soon as it receives from ofono, otherwise it caches the data in a disk file until agent registers, once agent registers plugin will read the data from the disk file and pushes all the records to it.

History: 

it is going to register and unregister the agent. It calls the methods on the agent for delivering history information whent the agent is up and running. The history record will be written to the disk if agent method returns error or if the agent is not running. For outgoing messages ofono hands over history to plugin in 2 calls. It calls the plugin with all the message history properties with 'Pending" status first and updates the status with another method call. Plugin updates the messages history to client in 2 calls using same ReportTextMessage method. 


History hierarchy
============================

Service 	: org.ofono
Interface	: com.meego.TelephonyHistory
Object path	: /

Methods		void RegisterAgent (objectpath)  

			RegisterAgent method registers the agent object path. Methods on this agent will be called if history needs to push data.  

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.InvalidFormat
					 [service].Error.InUse

		void UnregisterAgent (objectpath) 

			UnregisterAgent method unregister the already registered agent object path.

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.InvalidFormat
					 [service].Error.InUse


HistoryAgent hierarchy
==========================

Service Name	: Unique Name
Interface	: com.meego.TelephonyHistoryAgent
Objectpath	: Freely definable

Methods		void ReportTextMessage( array{dict}) 

			This method gets called by ofono to deliver an array of records. Each record is represented as a dictionary, all the dict 				properties are described in the "Properties" section.
		
			Possible Errors: [service].Error.Failed

		void ReportVoiceCall( array{dict}) 

			This method gets called by ofono to deliver an array of records. Each record is represented as a dictionary, all the dict 				properties are described in the "Properties" section.
		
			Possible Errors: [service].Error.Failed
		
		void Release() 
			Cleans up agent, assumes that agent is already unregistered, so not needed to unregister.

Properties 
==========	
		uint32	Uid [Read Only]
			Integer representing the internal representation of histroy message id.

		string  Type [Read Only]
			string representing the type of the history message. Type can be one of the following three alternatives.
 
			"outgoing" - it is an outgoing history message 
			"incoming" - it is an incoming history message
			"missed" - It is a history message for missed call
			
		string	LineIdentification [Read Only]
			string representing the LineIdentification , for outgoing message it is the phone number dialed. For incoming message it is the 			CLIP, or COLP if received by the underlying implementation.

		String  Message [Read Only]
			string represents the text message.

		string	LocalSentTime [Read Only]
			String representing local sent time. 

		string	SentTime [Read Only]
			String representing sent time.

		string  StartTime [Read Only]
 			String representing start time of the call

 		string  EndTime [Read Only]
 			String representing end time of the call
			
		dict	Information [Read Only]
			dict representing modem path from which this message originates
			"Modem" - will fetch object path of the modem