Public intent registration system

[Peli]

Dear all,

We've been approached by a Google employee on the possibility of
providing a public "intent registration system" - and OpenIntents
would be the ideal place for it.

The idea is quite simple:
We would host a place where a developer could fill out a simple form
describing a new Intent they have implemented in their application
that is available to others, with corresponding facilities to browse
and search through those intents.

Before actually starting to implement this web service, we'd like to
ask for early feedback from developers (and future users):

* How would you like to provide the intent data? Would you prefer to
fill in online forms (copy and paste from Eclipse), or would you
prefer to upload your Manifest file?

* What kind of additional data would you like to be able to provide?
Developer info, application title & description, link to website, link
to Android Market, screenshot, Android SDK version, your application
version, ...? What else?

* Search through available intents? Would it help to organize them in
categories, or tag them? Which categories would be helpful?

* Additional features: possibility to have discussions around specific
intent protocols people have published, the ability for people to add
other apps that implement or use the protocols, ...

* Would it be helpful to post short code snippets to each intent
showcasing how to use them in one's application? (easy possibility to
copy and paste)

* How should intents be published? Would you be interested in RSS
feeds on newly available intents?

* Would there be interest for something similar also for content
providers? Is there anything else in the Android system that is worth
sharing through a web site in this way?

As usual, we'll try to start with a KISS version, but it is always a
good idea to also have a good picture of where all this may evolve to.

Feedback and additional ideas are welcome!

Peli

[hackbod]

For providing the Intent data, I think I would suggest data similar to
how we document them in the Intent class, since the manifest doesn't
include all of the interesting information, in particular any extra
fields and the output that is expected back.

I suspect that sample code is probably not all that important -- there
is really so little involved in starting an Intent and getting the
data back, that given you have the information about the constants and
such, once you know how to use the general facility concrete code for
each variation won't add a whole lot.

Also doing something for content providers is an interesting idea.
What we have been thinking for them is supplying a static library that
clients can link into their app, which defines all of the interesting
constants, provides helper methods, etc. Basically something like the
classes we have in android.provider, but in its own static library.

[friedger]

As a starting point I have started a simple list of intents at
http://www.openintents.org/en/node/35 (mainly copied from Android
documentation).

If you would like to have your intent added there post a comment there
with your description. I hope this helps to get a better idea of what
kind of data are needed in the intent registration.

Cheers,
Friedger

[Peli]

Another general question:

Would it make more sense to organize the data internally in the form
of a database with rigid structure, or more like a wiki or blog with
flexible structure?

The descriptions of the Android intents are currently organized in
form of a simple web page:
* http://code.google.com/android/reference/android/content/Intent.html
* http://code.google.com/android/reference/available-intents.html

Having them organized in form of database entries would give more
freedom in restructuring the output:
* Show lists of all intents, sorted in various ways.
* Show all intents that belong to a certain scheme
* Show all applications that implement a certain intent or that use a
certain intent
* Sort intents by the number of applications that use them

On the other hand, being too rigid would make it more difficult to
describe extras or the possibility to have variations of an intent
(would slight variations of intents by different extras all belong to
the same intent and described on the same page, or should each
variation get a separate page?)

If stored in a database, would the following structure make sense?
== Table Intents ==
* id
* action: e.g. android.intent.action.VIEW
* action_variable: android.content.Intent.ACTION_VIEW
* scheme: geo:
* scheme_variations: geo:latitude,longitude; geo:latitude,longitude?
z=zoom; geo:0,0?q=my+street+address; geo:0,0?q=business+near+city
* category:
* type:
* component:
* extras:
* description: Opens the Maps application to the given location or
query. The Geo URI scheme (not fully supported) is currently under
development. The z field specifies the zoom level. A zoom level of 1
shows the whole Earth, centered at the given lat,lng. A zoom level of
2 shows a quarter of the Earth, and so on. The highest zoom level is
23. A larger zoom level will be clamped to 23.
* return_value:

== Table application ==
* id
* name
* author
* description
* website

== Table application_implements_intent ==
* intent_id
* application_id

== Table application_uses_intent ==
* intent_id
* application_id

Or am I starting to make things look more difficult than they should
be? Who would prefer such a rigid structure? Who would prefer a simple
wiki or blog?

It may also depend on how large we expect this to grow. If it is just
a handful of people interested, a wiki may be the better choice. If
the thing grows, the database may be more appropriate... How many
intents are there already "in the wild"? Maybe we could start to
collect a few example in this thread. This may give a better idea of
how best to organize them...

Peli

[Peli]

> As a starting point I have started a simple list of intents at http://www.openintents.org/en/node/35

Good idea! This is basically the bottom line of my more elaborate post
below :-)

Peli

[friedger]

I vote for the database solution.
If we want to provide a intent resolution application we need
structured data. However, the intent table could just consist of a few
free text columns.

The mapping table between applications and intents is a good idea. So
versioning of applications is possible and you can provide
alternatives to the same "intent protocol".

Friedger

On Sep 17, 10:46 am, Peli <peli0...@googlemail.com> wrote:
> Another general question:
>
> Would it make more sense to organize the data internally in the form
> of a database with rigid structure, or more like a wiki or blog with
> flexible structure?
>
> The descriptions of the Android intents are currently organized in
> form of a simple web page:
> *http://code.google.com/android/reference/android/content/Intent.html

> *http://code.google.com/android/reference/available-intents.html

[Peli]

> > As a starting point I have started a simple list of intents at http://www.openintents.org/en/node/35

I have added the intents of the apps-for-android to http://www.openintents.org/en/node/35
and have noticed the following points:

1) Sometimes there are several ways to do the same thing, like VIEW
and EDIT call exactly the same activity with same functionality, or
GET_CONTENT or PICK do essentially the same. Does it make sense to
duplicate all explanation for these entries in the database? Should
they be collected? Or should developers rather be advised to only
provide a single interface, to simplify future maintainability? (or is
the philosophy rather the opposite, to provide as many scheme / action
combinations as possible?)

2) Most of the time, the action is one of the standard actions VIEW,
EDIT, PICK, so should they actually go into a separate table "action",
with id and action?

3) "scheme" in the Android sense is only the first part of the URI,
but in the table, the whole URI is put there. Should a database rather
contain a strict representation of the intents and store
scheme="flickr" host="photos", or be more user-friendly and store
scheme="flickr://photos"?

4) With the "extras", the table structure can get really messy:
Sometimes there are extras as input, sometimes extras as output,
sometimes input extras and output extras agree, sometimes they
disagree. Should they be described as text only in the description?
Would there be any use for storing them in a more rigid structure
(separate table for extras)?

Peli

[hackbod]

On Sep 18, 9:13 am, Peli <peli0...@googlemail.com> wrote:
> 1) Sometimes there are several ways to do the same thing, like VIEW
> and EDIT call exactly the same activity with same functionality, or
> GET_CONTENT or PICK do essentially the same. Does it make sense to
> duplicate all explanation for these entries in the database? Should
> they be collected? Or should developers rather be advised to only
> provide a single interface, to simplify future maintainability? (or is
> the philosophy rather the opposite, to provide as many scheme / action
> combinations as possible?)

As far as VIEW and EDIT go, they are defined to do different things,
so they are indeed different. Of course, VIEW is used all over the
place, and EDIT is used much less frequently. But still -- VIEW means
to present the user a UI for viewing the given data, and EDIT means to
present the user a UI for editing it. It is not at all unexpected
that the same activity could implement both, and look at the intent
action to adjust its UI to do what is being asked (or even just be a
general purpose UI that does both intrinsically).

GET_CONTENT and PICK are even more distinct: the entire protocol for
them is different. PICK is given a URI and allows the user to pick
from some data in there which is returned as the result intent data.
GET_CONTENT is given a MIME type of the data you would like, shows the
user a UI for browsing through that type of data managed by the
activity, and returns the selection as the result intent data.

As with VIEW and EDIT, GET_CONTENT is much more common than PICK
(although in the current applications this is not reflected well
because GET_CONTENT was added quite a bit later than PICK when we
found the PICK protocol usually wasn't what we really wanted).

> 2) Most of the time, the action is one of the standard actions VIEW,
> EDIT, PICK, so should they actually go into a separate table "action",
> with id and action?

We should be documenting intent -protocols-. That is, VIEW is a
protocol, and there should only be one entry for it. The VIEW
protocol is:

- An activity implementing this action will display to the user the
given data. It is not intended for the user to edit it, though an
implementation can allow that to be done as a secondary part of its UI
if desired (as it can provide any other optional features in its UI
for the user).
- The action is mumblemumble.VIEW
- A data Uri must be supplied giving what to view.
- No result is returned.

Likewise, EDIT, GET_CONTENT, and PICK each have their own well-defined
protocols, as documented in the Intent class.

> 3) "scheme" in the Android sense is only the first part of the URI,
> but in the table, the whole URI is put there. Should a database rather
> contain a strict representation of the intents and store
> scheme="flickr" host="photos", or be more user-friendly and store
> scheme="flickr://photos"?

First, the scheme shown here is not appropriate. As far as I know,
there is no standard "flickr" protocol defined (what would that
protocol do?), and so people should not be making up such a thing in
their app. And it is really not useful to do this, because if for
example you wanted to use this with GET_CONTENT or PICK... well,
nobody else knows what to do with a "flickr" scheme (none of the
ContentResolver API would work on it -- from getting MIME types to
opening data streams), so it wouldn't work.

If you want to have a specific Intent that can be invoked to, say, a
Flickr photo viewer, you would define your own action for it, such as
com.mydomain.action.VIEW_FLICKR, and that is what would be registered.

Intent actions are the primary mechanism for introducing new classes
of functionality. There is no reason to get tricky with schemes or
URIs or MIME types for that. Just define an action. That's what
they're for, and there's an infinite supply of the. ;)

> 4) With the "extras", the table structure can get really messy:
> Sometimes there are extras as input, sometimes extras as output,
> sometimes input extras and output extras agree, sometimes they
> disagree. Should they be described as text only in the description?
> Would there be any use for storing them in a more rigid structure
> (separate table for extras)?

My preference would be to have a separate table of extras, which an
Intent protocol would reference. This is because there are two main
ways you use extras:

(1) As required or intrinsic option parameters that go along with the
Intent. This is, when you define a particular protocol, you say "and
the caller must supply extra X and optionally extra Y in the starting
Intent, and the result must contain extra Z."

(2) As additional optional features that can be included with existing
protocols. For example, I may write my Super Contact Viewer, that
replaces the built-in contact views with the same protocol, but has
additional features. I can define new intent extras that callers can
optionally supply when starting a contact viewer, and they can include
these extras so that if my activity (or someone else's activity also
supporting the features) is the one that runs, it will do these
advanced things.

Because of this, like the action names, the extra names should be a
unique, global namespace, allowing them to be mixed and matched with
any protocol as appropriate.

The same follows for categories. The category names allow you to
specify filtering requirements -- for example, you can use GET_CONTENT
by itself to run anything that can select a content: URI, or you can
add in the OPENABLE category to only run those things that will return
a content: URI that can be opened. In fact these two were not defined
at the same time -- we first defined GET_CONTENT, then later realized
we needed to filter the available activities down in some cases, so
introduced the new OPENABLE category as add additional requirement you
can make when using GET_CONTENT. That category could just as well be
used with other actions where it makes sense (PICK possibly), even
though it was originally defined for the needs of GET_CONTENT. So
likewise, we should keep the categories in their own, unique
namespace.

We can also talk the same way about MIME types. People often want to
define their own MIME types for data types, and doing so does not mean
defining a bunch of new Intent protocols: it usually is just be a new
type you can use with the existing protocols. I think this more
properly belongs with defining content providers, though, since
usually defining a MIME type means also defining all of the cursor
rows and such that go along with it.

Finally, a little more on schemes. Though we do use schemes in some
select places for special actions (such as mailto:), this is always
being done with schemes defined by existing standards (most
importantly to be able to supply that functionality for the user
clicking on links in the web browser), and we always try to also
define an official action name for the same function. People
shouldn't be introducing new intent protocols by making up their own
schemes, though of course if you want to provide an implementation for
an existing standard scheme that is quite reasonable.

[Peli]

Thanks for your elaborate answer! I still have to swallow all the
information.

About the scheme:

> > Should a database rather contain [...]
> > scheme="flickr" host="photos"[...]?

>
> First, the scheme shown here is not appropriate.  As far as I know,
> there is no standard "flickr" protocol defined (what would that
> protocol do?), and so people should not be making up such a thing in
> their app.  

> [..]

>  There is no reason to get tricky with schemes or
> URIs or MIME types for that.  Just define an action.  That's what
> they're for, and there's an infinite supply of the. ;)

I guess you should tell that to romainguy :-)

This scheme is used in the Photostream application written by him.
http://android-developers.blogspot.com/2008/09/android-photostream.html
http://code.google.com/p/apps-for-android/source/browse/trunk/Photostream/AndroidManifest.xml

It has received broad interest, and I'm sure many developers will use
this as a role model, so if there is something to be fixed, you should
talk to him soon :-)

> Finally, a little more on schemes.  Though we do use schemes in some
> select places for special actions (such as mailto:), this is always
> being done with schemes defined by existing standards (most
> importantly to be able to supply that functionality for the user
> clicking on links in the web browser), and we always try to also
> define an official action name for the same function.  People
> shouldn't be introducing new intent protocols by making up their own
> schemes, though of course if you want to provide an implementation for
> an existing standard scheme that is quite reasonable.

Ok, got it ;-)

Peli

---
Discussion thread: http://groups.google.com/group/openintents/tree/browse_frm/thread/533d71bd16caed02

[friedger]

So If I understand hackbod correctly, there are two things to
distinguish

1.) Intent protocols consiting of
- description of a general task like "view data"
- action name like "android.action.VIEW"
- extras
- return name

2.) Implementations for these protocols
- reference to protocol like "view data"
- the URI, like "contents://contacts/1
- description of application like "Contact manager, can be downloaded
at...."

Friedger

On Sep 18, 9:59 pm, Peli <peli0...@googlemail.com> wrote:
> Thanks for your elaborate answer! I still have to swallow all the
> information.
>
> About the scheme:
>
> > > Should a database rather contain [...]
> > > scheme="flickr" host="photos"[...]?
>
> > First, the scheme shown here is not appropriate.  As far as I know,
> > there is no standard "flickr" protocol defined (what would that
> > protocol do?), and so people should not be making up such a thing in
> > their app.  
> > [..]
> >  There is no reason to get tricky with schemes or
> > URIs or MIME types for that.  Just define an action.  That's what
> > they're for, and there's an infinite supply of the. ;)
>
> I guess you should tell that to romainguy :-)
>

> This scheme is used in the Photostream application written by him.http://android-developers.blogspot.com/2008/09/android-photostream.htmlhttp://code.google.com/p/apps-for-android/source/browse/trunk/Photost...

>
> It has received broad interest, and I'm sure many developers will use
> this as a role model, so if there is something to be fixed, you should
> talk to him soon :-)
>
> > Finally, a little more on schemes.  Though we do use schemes in some
> > select places for special actions (such as mailto:), this is always
> > being done with schemes defined by existing standards (most
> > importantly to be able to supply that functionality for the user
> > clicking on links in the web browser), and we always try to also
> > define an official action name for the same function.  People
> > shouldn't be introducing new intent protocols by making up their own
> > schemes, though of course if you want to provide an implementation for
> > an existing standard scheme that is quite reasonable.
>
> Ok, got it ;-)
>
> Peli
>
> ---

> Discussion thread:http://groups.google.com/group/openintents/tree/browse_frm/thread/533...

[friedger]

Now you can add new intent protocols at http://www.openintents.org/en/node/add/intent-protocols

The list is available at http://www.openintents.org/en/registry

Friedger

> > This scheme is used in the Photostream application written by him.http://android-developers.blogspot.com/2008/09/android-photostream.ht......

[friedger]

There is also a feed for the registry: http://www.openintents.org/en/rss/registry

On 20 Sep., 01:37, friedger <fried...@googlemail.com> wrote:
> Now you can add new intent protocols athttp://www.openintents.org/en/node/add/intent-protocols
>
> The list is available athttp://www.openintents.org/en/registry

[Peli]

I've added applications as well:
http://www.openintents.org/en/applications

Currently, one can select a list of actions (or "intent protocols")
and a list of URIs on which those actions work, for intents that the
application provides (exposes) to other applications, and intents that
the application uses from other applications.

This is supposed to be KISS, as it is not accurate in several ways:
1) There is no relation between actions and URIs. So if an application
uses several actions and several URIs, it is not clear which actions
can be performed on which URIs.
2) Currently, the intent category is ignored.
3) It is not obvious which optional extras are supported by a specific
application.

All this information can be put by words into the description of the
application.

We should try and see whether this KISS version is sufficient or
whether the caveats 1), 2), 3) are not so bad after all:
A) It is easier and quicker to enter the data and to register a new
application: http://www.openintents.org/en/node/add/application
B) The main purpose is to find applications that support certain
actions or URIs. This registry is already useful in helping to do so.
If one is interested in specific actions / intents / categories /
extras, one anyway has to look carefully at the application itself.
But through the registry, one knows which application(s) to look at.

Opinions and suggestions are welcome :-)

Peli

[Peli]

I've added a couple more applications, intents, and URIs, and there
are now the following views:

Applications http://www.openintents.org/en/applications
Intents http://www.openintents.org/en/intentstable
URIs http://www.openintents.org/en/uris
Extras http://www.openintents.org/en/extras

Also, I think the following policy makes sense:
We ONLY accept applications in this database that EITHER provide some
public intent, OR use some public intent. Otherwise the list of
applications would be swamped with uncooperative mini-apps :-)

If you know any public open source apps or closed source apps that
provide their intents, let me know and I can enter it, or you can
enter it yourself if you log in: http://www.openintents.org/en/node/add/application

Peli

[Peli]

I added some more info blocks:
For example on the View intent page:
http://www.openintents.org/en/node/37

now there is:
*) on the left side a list of other intents
*) below the content a list of applications that provide this intent
*) and below that a list of applications that use this intent.

and something similar for URIs and extras. I think it is really
useful :-) Now we only need more application data :-)

Peli

On Sep 25, 5:27 pm, Peli <peli0...@googlemail.com> wrote:
> I've added a couple more applications, intents, and URIs, and there
> are now the following views:
>
> Applicationshttp://www.openintents.org/en/applications
> Intentshttp://www.openintents.org/en/intentstable
> URIshttp://www.openintents.org/en/uris

> Extrashttp://www.openintents.org/en/extras