URLDispatcher

Differences between revisions 9 and 10
Revision 9 as of 2014-03-28 20:26:01
Size: 3406
Editor: cpe-76-187-229-139
Comment:
Revision 10 as of 2015-04-24 14:52:59
Size: 3936
Editor: mpt
Comment: + bug 1370008 (url-dispatcher-bad-url)
Deletions are marked like this. Additions are marked like this.
Line 56: Line 56:

== Unsupported URLs ==

(bug Bug:1370008)

{{attachment:unrecognized-address.png}}

Whenever the URL dispatcher is called on to open an address of a protocol that it does not understand (`url-dispatcher-bad-url`), it should open an alert with the title “Unrecognized Address”, text of the form ‘Ubuntu can’t open addresses of type “{protocol:}”.’, and an “OK” button. To prevent denial of UI service, however, the alert should not open if it has already opened more than three times in the past minute.

Introduction

The URL Dispatcher is a small service that can allow applications that are confined to launch other applications that are identified with a particular URL. Perhaps the most common case would be sending an http:// URL to the web browser, but other applications like music or just starting an application that is in a different sandbox is also supported. For most applications this is a useful way to get out of their application to another piece of content or user request.

For Qt/QML applications access to the URL Dispatcher is provided through the Qt desktop plugin. C++ applications can use QDesktopServices.openURL() method. QML applications can use Qt.openUrlExternally(string) method. Both are valid and the backend is transparent. For other applications they can use the Platform API or liburl-dispatcher directly depending on their needs.

The URL dispatcher project is hosted in Launchpad.

Supported URLs

Base URLS

There are a few URLs that are supported internally in the URL dispatcher.

URL

Description

application:///$(app_id).desktop

The application URL can be used to start an application with a known Application ID. For applications that install their desktop file in /usr/share/applications the application ID should just be the name of the desktop file.

appid://$(pkg)/$(app)/$(version)

Allows for launching an application using an application ID. Also provides for wild cards. The $(app) can be first-listed, last-listed-app or only-listed-app to select the appropriate applicaiton using the click manifest. Also the $(version) can be current-user-version to select the version in the manifest

Application URLs

Applications can register to be opened when a URL is activated by adding a URL definition to their Click manifest. For this a small JSON file needs to be added along side the desktop file in the "hooks" section of the file. A simple manifest could look like this:

{
        "name": "My App",
        "version": "1.2.3",
        "hooks": {
                "foo": {
                        "desktop": "foo.desktop",
                        "urls": "foo.url-dispatcher"
                }
        }
}

Which would then point to another JSON file in your click package that defines which URLs you are expecting to recieve. A simple version of that file could look like:

[
        {
                "protocol": "foo",
                "domain-suffix": "bar.com"
        }
]

This would mean that the application in "foo.desktop" would be launched anyone someone requested a URL with the pattern "foo://*.bar.com". The domain-suffix field can be left out if you'd like to recieve all requests for a given protocol. The URL dispatcher definition is an array, so as many protocol/suffixes that you wish to recieve for that application may be added.

Temporarily Hardcoded URLs

For legacy reasons we've hardcoded some URLs into the dispatcher:

URL

App ID

Description

file:///home/*/Music/*

music-app

Opens music in the Music player

file:///home/*/Videos/*

mediaplayer-app

Opens video content in the media player

Unsupported URLs

(bug 1370008)

unrecognized-address.png

Whenever the URL dispatcher is called on to open an address of a protocol that it does not understand (url-dispatcher-bad-url), it should open an alert with the title “Unrecognized Address”, text of the form ‘Ubuntu can’t open addresses of type “{protocol:}”.’, and an “OK” button. To prevent denial of UI service, however, the alert should not open if it has already opened more than three times in the past minute.

URLDispatcher (last edited 2015-08-04 15:15:51 by mpt)