[RFCv3] Add message agent API

[RFCv3] Add message agent API

[Aki Niemi]

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

---
 doc/message-api.txt |   72 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 72 insertions(+), 0 deletions(-)

diff --git a/doc/message-api.txt b/doc/message-api.txt
index 693a111..4b7c287 100644
--- a/doc/message-api.txt
+++ b/doc/message-api.txt
@@ -26,6 +26,43 @@ Methods		dict GetProperties()
 
 			Send the message in text to the number in to.
 
+		void RegisterAgent(object path, string type)
+
+			Registers an agent to handle received messages.
+
+			The object path defines the path of the agent that
+			will be called when a message is ready to be
+			dispatched.  The type parameters accepts a MIME
+			type of the messages this agent is willing to
+			accept.  Some common types include:
+
+				"text/plain" - Regular text messages
+				"text/x-vcard" - vCard objects
+				"text/calendar" - vCalendar objects
+				"application/vnd.oma.push" - WAP push
+				"application/x-sms-agent" - Any datagram
+
+			Wildcards are not allowed as the MIME subtype, but
+			registering an agent on a generic port is supported.
+			For instance, to listen on port 5678, the agent
+			would need to register using type:
+
+				"application/x-sms-agent;port=5678"
+
+			Possible Errors: [service].Error.InvalidArguments
+					 [service].Error.InvalidFormat
+					 [service].Error.InUse
+
+		void UnregisterAgent(object path)
+
+			Unregisters an agent.  If no agents exist that
+			can handle an incoming message, it will be
+			silently dropped.
+
+			Possible Errors: [service].Error.InvalidArguments
+					 [service].Error.InvalidFormat
+					 [service].NotFound
+
 Signals		PropertyChanged(string name, variant value)
 
 			This signal indicates a changed value of the given
@@ -64,3 +101,38 @@ Properties	string ServiceCenterAddress
 				"ps-preferred" - Use CS if PS is unavailable
 
 			By default oFono uses "cs-preferred" setting.
+
+
+MessageAgent Hierarchy
+===============
+
+Service		unique name
+Interface	org.ofono.MessageAgent
+Object path	freely definable
+
+Methods		void HandleTextMessage(string message, dict info)
+
+			New incoming text 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.
+
+		void HandleDatagram(array{byte}, dict info)
+
+			New incoming datagram SMS received.  Info has
+			Sender, LocalSentTime, SentTime, MediaType or
+			DestinationPort, and SourcePort information.
+			Sender address is given in string format.
+			LocalSentTime and SentTime are given in string
+			using ISO8601 format.  MediaType is given as
+			a MIME media type in string form, if it is
+			a known type.  Otherwise, DestinationPort is
+			given as a 16bit unsigned integer.  SourcePort
+			is always given as a 16bit unsigned integer.
+
+		void Release()
+
+			Agent is being released, possibly because of oFono
+			terminating, the MessageManager interface being
+			torn down or modem powering down.
-- 
1.7.0.4

Re: [RFCv3] Add message agent API

[Marcel Holtmann]

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

Hi Aki,

> +		void RegisterAgent(object path, string type)
> +
> +			Registers an agent to handle received messages.
> +
> +			The object path defines the path of the agent that
> +			will be called when a message is ready to be
> +			dispatched.  The type parameters accepts a MIME
> +			type of the messages this agent is willing to
> +			accept.  Some common types include:
> +
> +				"text/plain" - Regular text messages
> +				"text/x-vcard" - vCard objects
> +				"text/calendar" - vCalendar objects
> +				"application/vnd.oma.push" - WAP push
> +				"application/x-sms-agent" - Any datagram
> +
> +			Wildcards are not allowed as the MIME subtype, but
> +			registering an agent on a generic port is supported.
> +			For instance, to listen on port 5678, the agent
> +			would need to register using type:
> +
> +				"application/x-sms-agent;port=5678"

so my obvious question here is, what kind of x-sms-agent type
applications do you expect? The need for text, vcard, vcalendar and push
messages is pretty clear. I still haven't figured out what other
applications are out there that we want do support with this. Can you
please give us some concert examples. I think that everybody else has
abandoned any other SMS message types.

Regards

Marcel

Re: [RFCv3] Add message agent API

[Aki Niemi]

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

Hi Marcel,

2010/9/8 Marcel Holtmann <marcel@holtmann.org>:
>> +             void RegisterAgent(object path, string type)
>> +
>> +                     Registers an agent to handle received messages.
>> +
>> +                     The object path defines the path of the agent that
>> +                     will be called when a message is ready to be
>> +                     dispatched.  The type parameters accepts a MIME
>> +                     type of the messages this agent is willing to
>> +                     accept.  Some common types include:
>> +
>> +                             "text/plain" - Regular text messages
>> +                             "text/x-vcard" - vCard objects
>> +                             "text/calendar" - vCalendar objects
>> +                             "application/vnd.oma.push" - WAP push
>> +                             "application/x-sms-agent" - Any datagram
>> +
>> +                     Wildcards are not allowed as the MIME subtype, but
>> +                     registering an agent on a generic port is supported.
>> +                     For instance, to listen on port 5678, the agent
>> +                     would need to register using type:
>> +
>> +                             "application/x-sms-agent;port=5678"
>
> so my obvious question here is, what kind of x-sms-agent type
> applications do you expect? The need for text, vcard, vcalendar and push
> messages is pretty clear. I still haven't figured out what other
> applications are out there that we want do support with this. Can you
> please give us some concert examples.

Example: a voice and video over IP client that doesn't drain the
battery in half a day. My server sends a wakeup over SMS on an
incoming call.

Example: a device lock service. I send a binary SMS to my stolen phone
on a well-known port containing a cryptographic token, causing my
phone to lock and/or wipe itself clean.

Fact is, SMS is still the most widely available and power-efficient
rendezvous service on a mobile phone. It would be silly not to support
it to its full potential.

> I think that everybody else has abandoned any other SMS message types.

Quite the contrary. Every other mobile telephony API out there that I
know of has the ability to send and receive binary messages on an
arbitrary port.

Cheers,
Aki

Re: [RFCv3] Add message agent API

[Marcel Holtmann]

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

Hi Aki,

> >> +             void RegisterAgent(object path, string type)
> >> +
> >> +                     Registers an agent to handle received messages.
> >> +
> >> +                     The object path defines the path of the agent that
> >> +                     will be called when a message is ready to be
> >> +                     dispatched.  The type parameters accepts a MIME
> >> +                     type of the messages this agent is willing to
> >> +                     accept.  Some common types include:
> >> +
> >> +                             "text/plain" - Regular text messages
> >> +                             "text/x-vcard" - vCard objects
> >> +                             "text/calendar" - vCalendar objects
> >> +                             "application/vnd.oma.push" - WAP push
> >> +                             "application/x-sms-agent" - Any datagram
> >> +
> >> +                     Wildcards are not allowed as the MIME subtype, but
> >> +                     registering an agent on a generic port is supported.
> >> +                     For instance, to listen on port 5678, the agent
> >> +                     would need to register using type:
> >> +
> >> +                             "application/x-sms-agent;port=5678"
> >
> > so my obvious question here is, what kind of x-sms-agent type
> > applications do you expect? The need for text, vcard, vcalendar and push
> > messages is pretty clear. I still haven't figured out what other
> > applications are out there that we want do support with this. Can you
> > please give us some concert examples.
> 
> Example: a voice and video over IP client that doesn't drain the
> battery in half a day. My server sends a wakeup over SMS on an
> incoming call.

isn't this most likely done better via WAP Push? Do you have any concert
specification of an VoIP client doing this as SMS datagram.

> Example: a device lock service. I send a binary SMS to my stolen phone
> on a well-known port containing a cryptographic token, causing my
> phone to lock and/or wipe itself clean.

I think this is clear example where it should be done as an oFono plugin
and not go via the user session.

> Fact is, SMS is still the most widely available and power-efficient
> rendezvous service on a mobile phone. It would be silly not to support
> it to its full potential.

Yes, SMS is nice, but I am trying to figure out what use cases we have
that are done inside the user session and where it makes no sense to
have a specific oFono plugin doing the proper task. Meaning what really
needs user interaction or requires an application for it.

I can only come up with some theoretical examples and potential
applications. I like to see some applications that exist right now and
use SMS in this way. That is my problem right now, I just can't find
them. Since you spent some time thinking about real uses, do you have
examples all existing application using SMS like this?

Keep in mind that SMS are actually causing costs and we have to protect
random application from sending or receiving random messages as well.

> > I think that everybody else has abandoned any other SMS message types.
> 
> Quite the contrary. Every other mobile telephony API out there that I
> know of has the ability to send and receive binary messages on an
> arbitrary port.

And is it actually in use. That telephony API can make coffee for me if
it likes to, but if I am not using it, why bother?

I am not against supporting binary SMS over D-Bus, but I am trying hard
to understand the use cases and failing right now. I really like to get
a clear picture of what is needed by the application and why.

We have been always asking these hard questions and justifying them with
real use cases. That is the only way to avoid a cluttered API where only
30% is actually used.

This doesn't mean in any way that binary SMS are not supported. That is
not true at all. They are supported via oFono plugins all ready and
should be supported that way. No questions asked. My question is driven
towards the D-Bus API and its users.

Regards

Marcel

Re: [RFCv3] Add message agent API

[Aki Niemi]

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

Hi Marcel,

2010/9/8 Marcel Holtmann <marcel@holtmann.org>:
>> Example: a voice and video over IP client that doesn't drain the
>> battery in half a day. My server sends a wakeup over SMS on an
>> incoming call.
>
> isn't this most likely done better via WAP Push? Do you have any concert
> specification of an VoIP client doing this as SMS datagram.

Not better, just different. Surely this could be done via vCal as well.

>> Example: a device lock service. I send a binary SMS to my stolen phone
>> on a well-known port containing a cryptographic token, causing my
>> phone to lock and/or wipe itself clean.
>
> I think this is clear example where it should be done as an oFono plugin
> and not go via the user session.

Huh? What do you mean by user session?

And you can't seriously be suggesting these sort of applications end
up in the oFono source tree, or will be licensed under GPL. This is
exactly why we are using D-Bus after all, so that applications using
oFono can have any license, including proprietary.

>> Fact is, SMS is still the most widely available and power-efficient
>> rendezvous service on a mobile phone. It would be silly not to support
>> it to its full potential.
>
> Yes, SMS is nice, but I am trying to figure out what use cases we have
> that are done inside the user session and where it makes no sense to
> have a specific oFono plugin doing the proper task. Meaning what really
> needs user interaction or requires an application for it.
>
> I can only come up with some theoretical examples and potential
> applications. I like to see some applications that exist right now and
> use SMS in this way. That is my problem right now, I just can't find
> them. Since you spent some time thinking about real uses, do you have
> examples all existing application using SMS like this?

You asked for use cases, which is what I provided. Now you want an
actual real-world application? What's next, requiring over 250 000
downloads?

> Keep in mind that SMS are actually causing costs and we have to protect
> random application from sending or receiving random messages as well.

Are you saying there is some extra cost in running an agent that
handles SMSs, as opposed to silently dropping them? Keep in mind that
there is no ICMP in SMS, so there is absolutely nothing to stop
someone from sending SMSs to your phone on any port -- regardless of
whether your phone wants them.

>> > I think that everybody else has abandoned any other SMS message types.
>>
>> Quite the contrary. Every other mobile telephony API out there that I
>> know of has the ability to send and receive binary messages on an
>> arbitrary port.
>
> And is it actually in use. That telephony API can make coffee for me if
> it likes to, but if I am not using it, why bother?

There's a separate patch to add support for RFC2324. This not it.

Cheers,
Aki