Le fichier manifest.json est un fichier déclaratif au format JSON. Il déclare les éléments de l'application QML à lancer sur la Freebox, les droits qui lui sont nécessaires et enfin le type d'URL que l'application est capable de gérer. Ce fichier doit porter exactement le nom manifest.json et doit être placé à la racine du package de l'application pour le FreeStore.

En guise d'exemple, le fichier manifest.json suivant décrit une application simple, dont le nom est Mire, et dont le programme principal QML à lancer sera dans le fichier main.qml. 

{
	"name": "Mire",
	"identifier": "com.example.mire",
	"description": "Mire Rock'n'Roll",
	"icon": "icon.png",
	"entryPoints": {
		"main": {
			"default": true,
			"file": "main.qml"
		}
	}
}

On pourra noter que chaque application est identifiée par un nom de package sous la forme d'une notation pointée qui doit être unique et dont le préfixe est le même que celui entré par le dévelopeur dans la console du FreeFactory. Par exemple ici com.example.

Le lancement d'une application

Lorsqu'une application est installée sur le Player, il existe deux manières de la démarrer : la première est de se placer dans la liste des applications installées Mes Applications, et de sélectionner l'application à lancer. Dans ce cas, le lanceur d'application du Player va charger le fichier QML qui aura été spécifié comme default dans la section entryPoints du fichier manifest.json. La seconde manière se passe implicitement lorsqu'une application en cours d'utilisation demande l'ouverture d'une URL qu'elle ne sait pas gérer. Le lanceur va alors chercher dans la liste des application installées celles qui savent gérer ce type d'URL et proposera une liste d'applications aptes à être démarrées. Dans ce cas, si une application est sélectionnée, elle sera lancée avec l'URL à traîter.

Comment traîter une URL au lancement

Dans la section entryPoints, vous aurez à déclarer au moins un point d'entrée de l'application par défaut, et optionnellement un urlHanlder dans ce point d'entrée. Dans le cas où un urlHanlder est déclaré, votre fichier associé doit posséder une fonction handleUrl qui permettra de récupérer l'URL à traîter. Sa signature est la suivante : 

function handleUrl(action, url, mediaType) {...}

Cette fonction accepte trois arguments :

  • l'action à opérer, sous forme de verbe en anglais. Exemple : play
  • l'url à traîter. Exemple : http://www.example.com/movies?id=42
  • le type MIME de la ressource désignée par l'URL. Exemple : video/mp4

Ainsi, cela permet aux applications de communiquer les unes avec les autres par le biais des URLs : par exemple, une application qui liste des vidéos classées par thème peut déléguer la lecture d'une vidéo sélectionnée à une application de lecture vidéo. La délégation en question est possible grâce au résolveur d'URLs, qu'une application peut appeler de la manière suivante par l'objet App du contexte Freebox : 

App.urlOpen(url, mediaType)

ou par l'objet Qt standard du contexte : 

Qt.openUrlExternally(url);

Chacune des deux méthodes a son avantage : la première permet de détailler le type de la resource à traiter pour permettre au résolveur de la Freebox de choisir la bonne application, mais la seconde est portable sur d'autres systèmes d'exploitation comme par exemple lorsque l'application fonctionne sur l'ordinateur du développeur.

Les mots-clé du manifest.json

Mots-clé de premier niveau

mot-clé signification type JS usage
name nom de l'application string popup de sélection du résolveur d'URL
identifier identificateur du package string identifiant unique du package
description rôle du programme string popup de sélection du résolveur d'URL
capabilities ensemble des droits nécessaires à l'application object sécurité
icon chemin vers une icône string popup de sélection du résolveur d'URL
entryPoints liste des points de démarrage object lancement de l'application

Mots-clé de l'objet capabilities

mot-clé signification valeurs
net_lan accès au réseau local optional, required
net_gw accès au boitier Server idem, idem
net_wan accès à internet idem, idem
gw_settings FreeboxOS, accès aux paramètres idem, idem
gw_contacts FreeboxOS, accès à la liste des contacts idem, idem
gw_calls FreeboxOS, accès à la liste des appels idem, idem
gw_explorer FreeboxOS, accès aux disques idem, idem
gw_downloader FreeboxOS: accès au downloader idem, idem
gw_parental FreeboxOS: accès au controle parental idem, idem
gw_pvr FreeboxOS: accès au enregistrements idem, idem
in_app_purchase achats à l'intérieur de l'application idem, idem
morality_18 interdit aux moins de 18 ans idem, idem

Mots-clé des entryPoints

mot-clé signification type JS
main point d'entrée principal object
settings point d'entrée de la configuration de l'application object

Mots-clé d'un point d'entrée

mot-clé signification type JS
file chemin vers le programme QML à charger string
urlHandler tableau de définition des URLs gérées array
default détermine quel point d'entrée est à lancer par défaut bool

Mots-clé des éléments de urlHandler

mot-clé signification exemple
urlPattern regex d'URL gérée ^http://www.youtube.com/
mediaTypePattern regex de type MIME géré ^video/
actionId verbe d'action view
actionLabel label de l'action Voir
score capacité à gérer ce type d'URL (0 = faible) 1000

Un exemple : afficher une photo via son URL

Voici un programme d'affichage d'une photo. Son fichier manifestc.json est le suivant : 

{
	"name": "Picture Viewer",
	"identifier": "com.example.picview",
	"description": "Visionneur d'image",
	"capabilities": {
		"net_gw": "required",
		"net_lan": "required"
	},
	"icon": "icon.png",
	"entryPoints": {
		"main": {
			"default": true,
			"file": "main.qml",
			"urlHandler": [
				{
					"urlPattern": "^https?://",
					"mediaTypePattern": "^image/",
					"actionId": "view"
					"actionLabel": "Voir",
					"score": 1000
				}
			]
		}
	}
}

On peut constater l'apparition du champ capabilities où net_lan et net_gw sont requis, ce qui permettra à l'application d'obtenir la permission d'accéder au réseau local et au boitier Server. On constate aussi que les champs urlPattern et mediaTypePattern sont définis sous forme d'expressions régulières.

Et le programme main.qml est le suivant : 

import QtQuick 2.4
import fbx.application 1.0

Application {
	Image {
		id: photo
		anchors.fill: parent
		fillMode: Image.PreserveAspectFit
	}

	function handleUrl(action, url, mediaType) {
		if (!mediaType.match(/^image/)) {
			Qt.quit();
			return;
		}

		if (action != "view") {
			Qt.quit();
			return;
		}

		photo.source = url;
	}
}

Ainsi, ce programme pourra être démarré depuis n'importe quel programme du Player qui voudra faire afficher une image du réseau local via son URL.

màj : %%mtime(%B %d, %Y)