Google Cloud Print n'est plus disponible depuis le 31 décembre 2020. Pour obtenir de l'aide sur la migration, veuillez consulter cet article d'aide.

Cette page a été traduite par l'API Cloud Translation.

Privet

Privet est une API Cloud Device Local Discovery utilisée par les services cloud. Ce document comporte les sections suivantes:

Introduction: présentation de Privet
Découverte : mécanismes de découverte locale
Annonces : annonces de découverte à proximité
API: API Privet pour les appareils cloud généraux
API Printer: API Privet utilisées par les imprimantes
Annexe : Schémas supplémentaires

1. Présentation

Les appareils connectés au cloud présentent de nombreux avantages. Ils peuvent utiliser des services de conversion en ligne, héberger des files d'attente d'emplois lorsque l'appareil est hors connexion et être accessibles partout dans le monde. Cependant, comme de nombreux appareils cloud sont accessibles à un utilisateur donné, nous devons fournir une méthode permettant de trouver l'appareil le plus proche en fonction de l'emplacement. L'objectif du protocole Privet est de lier la flexibilité des appareils cloud à un mécanisme de découverte local approprié afin que les appareils soient facilement découverts dans de nouveaux environnements.

Les objectifs de ce protocole sont les suivants :

rendre les appareils cloud visibles localement
enregistrer des appareils cloud auprès d'un service cloud
associer des appareils enregistrés à leur représentation dans le cloud
activer la fonctionnalité hors connexion
simplifier l'implémentation pour que les petits appareils puissent l'utiliser ;

Le protocole Privet se compose de deux parties principales: la découverte et l'API. Discovery est utilisé pour localiser l'appareil sur le réseau local, et l'API permet d'obtenir des informations sur l'appareil et d'effectuer certaines actions. Dans ce document, l'appareil fait référence à un appareil connecté au cloud qui implémente le protocole Privet.

2. Découverte

Discovery est un protocole basé sur zéro (mDNS + DNS-SD). L'appareil DOIT mettre en œuvre l'adressage local de liaison IPv4. L'appareil DOIT être conforme aux spécifications mDNS et DNS-SD.

http://www.rfc-editor.org/rfc/rfc3927.txt (lien IPv4 local)
http://www.rfc-editor.org/rfc/rfc4862.txt (lien IPv6 local)
http://www.rfc-editor.org/rfc/rfc6762.txt (mDNS)
http://www.rfc-editor.org/rfc/cgi6763.txt (DNS-SD)

L'appareil DOIT résoudre les conflits de noms selon les spécifications ci-dessus.

2.1. Type de service

DNS Service Discovery utilise le format suivant pour les types de services : _applicationprotocol._transportprotocol. Dans le cas du protocole Privet, le type de service pour DNS-SD doit être : _privet._tcp

L'appareil peut également mettre en œuvre d'autres types de services. Nous vous recommandons d'utiliser le même nom d'instance de service pour tous les types de services mis en œuvre par l'appareil. Par exemple, une imprimante peut mettre en œuvre les services "Imprimante XYZ._privet._tcp&" et "Imprimante XYZ._imprimante._tcp". Cela simplifiera la configuration pour l'utilisateur. Cependant, les clients Privet ne rechercheront que "_privet._tcp".

En plus du type de service principal, l'appareil DOIT annoncer les enregistrements PTR pour les sous-types correspondants (voir la spécification DNS-SD : "7.1. Énumération d'instances sélective (sous-types)"). Le format doit être le suivant : _<subtype>._sub._privet._tcp

Actuellement, le seul sous-type d'appareil compatible est imprimante. Toutes les imprimantes DOIVENT donc faire la promotion de deux enregistrements PTR:

_privet._tcp.local.
_imprimante._sub._privet._tcp.local.

2.2. Enregistrement TXT

DNS Service Discovery définit des champs pour ajouter des informations facultatives sur un service dans les enregistrements TXT. Un enregistrement TXT est composé de paires clé/valeur. Chaque paire clé/valeur commence à partir de l'octet de longueur suivi de 255 octets maximum de texte. La clé correspond au texte situé avant le premier caractère "=", et la valeur correspond au texte situé après le premier caractère "="" jusqu'à la fin. La spécification n'autorise aucune valeur dans l'enregistrement. Dans ce cas, il ne s'agit pas du caractère "=", OU il n'y a pas de texte après le caractère "=". (Voir la spécification DNS-SD : "6.1. Règles générales relatives au format des enregistrements TXT DNS &6.2. la taille d'enregistrement TXT DNS-SD pour la longueur recommandée).

Privet exige que l'appareil envoie les paires clé/valeur suivantes dans l'enregistrement TXT. Les chaînes de valeurs/clés ne sont pas sensibles à la casse. Par exemple, "CS=online" et "cs=Online" sont les mêmes. Les informations contenues dans l'enregistrement TXT DOIVENT être identiques à celles accessibles via l'API /info (voir 4.1. API).

Nous vous recommandons de ne pas dépasser 512 octets.

2.2.1. txtvers

Version de la structure TXT. Le premier enregistrement de la structure TXT doit être txtvers. Actuellement, la seule version compatible est 1.

txtvers=1

2.2.2. ty

Nom de l'appareil lisible par l'utilisateur. Exemple :

ty=Google Cloud Ready Printer Model XYZ

2.2.3. Remarque (facultatif)

Nom de l'appareil lisible par l'utilisateur. Exemple :

note=1st floor lobby printer

Remarque:Cette clé facultative peut être ignorée. Toutefois, s'il est présent, l'utilisateur DOIT pouvoir modifier cette valeur. La même description DOIT être utilisée lors de l'enregistrement de l'appareil.

2.2.4. URL

URL du serveur auquel cet appareil est connecté (protocole inclus). Exemple :

url=https://www.google.com/cloudprint

2.2.5. type

Liste des sous-types d'appareils compatibles avec cet appareil, séparés par une virgule. Le format est : "type=_subtype1,_subtype2". Actuellement, le seul sous-type d'appareil compatible est imprimante.

type=printer

Chaque sous-type répertorié doit être annoncé à l'aide d'un enregistrement PTR correspondant. Il doit y avoir un élément correspondant pour chaque sous-type de service compatible. Le nom du sous-type de service (<subtype>._sub._privet._tcp) doit être égal au type d'appareil ici.

2.2.6. ID

ID de l'appareil. Si l'appareil n'a pas encore été enregistré, cette clé doit être présente, mais la valeur doit être vide. Exemple :

  id=11111111-2222-3333-4444-555555555555
  id=

2.2.7. cs

Indique l'état de connexion actuel de l'appareil. Quatre valeurs possibles sont définies dans cette spécification.

&online: indique que l'appareil est actuellement connecté au cloud.
"hors connexion" indique que l'appareil est disponible sur le réseau local, mais qu'il ne peut pas communiquer avec le serveur.
"connecting" (connexion) indique que l'appareil effectue sa séquence de démarrage et qu'il n'est pas encore entièrement connecté.
"not-configure" indique que l'accès Internet de l'appareil n'a pas encore été configuré. Cette valeur n'est pas utilisée actuellement, mais elle peut être utile dans les futures versions de la spécification.

Par exemple :

cs=en ligne
cs=hors connexion
cs=connexion

Si l'appareil a été enregistré auprès d'un cloud, il doit vérifier la connectivité à un serveur pour détecter son état de connexion (par exemple, en appelant l'API Cloud pour obtenir les paramètres de l'appareil). L'appareil peut utiliser l'état de sa connexion au canal de notification (par exemple, PAMP) pour indiquer cette valeur. Les appareils non enregistrés au démarrage peuvent pinguer un domaine pour détecter leur état de connexion (par exemple, pinguer www.google.com pour les appareils Cloud Print).

3. Annonces

Lors du démarrage, de l'arrêt ou du changement d'état d'un appareil, celui-ci DOIT effectuer l'étape d'annonce décrite dans la spécification mDNS. Elle DEVRAIT envoyer l'annonce correspondante au moins deux fois avec un intervalle d'au moins une seconde entre elles.

3.1. Démarrage

Au démarrage de l'appareil, il DOIT effectuer des vérifications et des annonces comme décrit dans la spécification mDNS. Dans ce cas, les enregistrements SRV, PTR et TXT doivent être envoyés. Il est recommandé de regrouper tous les enregistrements dans une seule réponse DNS, si possible. Dans le cas contraire, nous vous recommandons d'utiliser les enregistrements SRV, PTR et TXT.

3.2. Arrêt

Lors de l'arrêt de l'appareil, il DOIT essayer d'avertir toutes les parties concernées en envoyant un "paquet d'adieu" avec "TTL=0" (comme décrit dans la documentation mDNS).

3.3. Mettre à jour

Si des informations décrites dans le fichier TXT ont été modifiées, l'appareil DOIT envoyer une mise à jour. Dans ce cas, il suffit d'envoyer le nouvel enregistrement TXT. Par exemple, une fois qu'un appareil est enregistré, il DOIT envoyer une annonce de mise à jour incluant le nouvel ID.

4. API

Lorsqu'un appareil cloud est découvert, la communication client est activée avec celui-ci directement sur le réseau local. Toutes les API utilisent le protocole HTTP 1.1. Les formats de données sont basés sur JSON. Les requêtes API peuvent être des requêtes GET ou POST.

Chaque requête DOIT contenir un en-tête X-Privet-Token valide. La SEULE requête autorisée peut avoir un en-tête "X-Privet-Token" vide, à savoir la requête /privet/info (notez que l'en-tête DOIT toujours être présent). Si l'en-tête "X-Privet-Token" est manquant, l'appareil DOIT répondre avec l'erreur HTTP 400 suivante:

HTTP/1.1 400 Missing X-Privet-Token header.

Si l'en-tête "X-Privet-Token" est vide ou non valide, l'appareil DOIT répondre "invalid X-Privet-Token error" (invalid_x_privet_token, voir la section "Erreurs" pour plus de détails). La seule exception est l'API /info. Pour en savoir plus sur les raisons de cette opération et sur la façon dont les jetons doivent être générés, consultez l'Annexe A: attaque et prévention XSSI et XSRF.

Si une API demandée n'existe pas ou n'est pas compatible, l'appareil DOIT renvoyer une erreur HTTP 404.

4.1. Disponibilité de l'API

Avant d'exposer TOUTE API (y compris l'API /info), l'appareil DOIT contacter le serveur pour vérifier les paramètres locaux. Les paramètres locaux DOIVENT être conservés entre les redémarrages. Si le serveur n'est pas disponible, les derniers paramètres locaux connus doivent être utilisés. Si l'appareil n'a pas encore été enregistré, il doit suivre les paramètres par défaut.

Les appareils Cloud Print DOIVENT suivre la procédure ci-dessous pour enregistrer, recevoir et mettre à jour les paramètres locaux.

4.1.1. Inscription

Lors de l'enregistrement, l'appareil DOIT spécifier le paramètre "&local_settings" comme suit:

{
       "current": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": true,
                "printer/conversion_printing_enabled": true,
                "xmpp_timeout_value": 300
        }
}

Les paramètres suivants peuvent être définis:

Nom de la valeur	Type de valeur	Description
local_discovery	booléen	Indique si la fonctionnalité de découverte locale est autorisée. Si la valeur est "false", toutes les API locales (y compris /info) et la détection DNS-SD doivent être désactivées. Par défaut, les nouveaux appareils doivent passer "true".
jeton_accès	Booléen (facultatif)	Indique si l'API /accesstoken doit être exposée sur le réseau local. La valeur par défaut doit être "true".
imprimante/local_printing_enabled	Booléen (facultatif)	Indique si la fonctionnalité d'impression locale (/printer/createjob, /printer/submitdoc, /printer/jobstate) doit être exposée sur le réseau local. La valeur par défaut doit être "true".
impression/conversion_printing_enabled	Booléen (facultatif)	Indique si l'impression locale peut envoyer une tâche au serveur pour conversion. Cette option n'est utile que si l'impression en local est activée.
xmpp_timeout_value [valeur_délai_d'expiration]	int (facultatif)	Indique le nombre de secondes entre les pings du canal XMP. Par défaut, il DOIT être d'au moins 300 (5 minutes).

Important:L'absence de valeur facultative indique que la fonctionnalité correspondante est complètement incompatible avec l'appareil.

4.1.2. Démarrage

Au démarrage de l'appareil, le service doit contacter le serveur pour vérifier quelles API sont disponibles sur le réseau local. Les imprimantes connectées à Cloud Print doivent appeler la méthode suivante:

/cloudprint/printer?printerid=<printer_id>

/cloudprint/list

/xlsx/printer est préférable à /xlsx/list, mais les deux fonctionnent.

Cette API renvoie les paramètres actuels de l'appareil, y compris les paramètres de l'API locale. La réponse du serveur aura le format suivant:

"local_settings": {
        "current": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": true,
                "printer/conversion_printing_enabled": true,
                "xmpp_timeout_value": 300
         },
         "pending": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": false,
                "printer/conversion_printing_enabled": false,
                "xmpp_timeout_value": 500
         }
}

L'objet "current" indique les paramètres actuellement en vigueur.

"en attente" indique les paramètres à appliquer à l'appareil (cet objet peut être manquant).

Lorsque l'appareil voit les paramètres "en attente", il DOIT mettre à jour son état (voir ci-dessous).

4.1.3. Mettre à jour

Si une mise à jour des paramètres est nécessaire, une notification XPP est envoyée à l'appareil. La notification sera au format suivant:

<device_id>/update_settings

À la réception d'une notification de ce type, l'appareil DOIT interroger le serveur pour obtenir les derniers paramètres. Les appareils Cloud Print DOIVENT utiliser:

/cloudprint/printer?printerid=<printer_id>

Une fois que la section "en attente" s'affiche sur l'appareil à la suite de l'utilisation de l'API /cloudkms/printer (au démarrage ou en raison d'une notification), il DOIT mettre à jour son état interne afin de mémoriser les nouveaux paramètres. Il DOIT appeler l'API du serveur pour confirmer les nouveaux paramètres. Pour les imprimantes cloud, l'appareil DOIT appeler l' /cloudkms/update API et utiliser le paramètre "local_settings" comme lors de l'enregistrement.

Lors de la reconnexion à la version XMP, l'appareil DOIT appeler l'API /translate/printer pour vérifier si les paramètres locaux ont été modifiés depuis la dernière fois.

4.1.3.1. Paramètres locaux en attente

paramètre local que l'appareil utilise pour appeler l'API de serveur ne doit JAMAIS contenir la section "en attente".

4.1.3.2. Paramètres locaux actuels

SEULEMENT l'appareil peut modifier la section actuelle du paramètre "local_settings". Tous les autres utilisateurs modifient la section "en attente" et attendent que les modifications soient appliquées à la section "en cours" par l'appareil.

4.1.4. Hors connexion

Si le serveur ne peut pas contacter le serveur au démarrage, il DOIT utiliser les derniers paramètres locaux connus après la notification.

4.1.5. Suppression de l'appareil du service

Si l'appareil a été supprimé du service (GCP, par exemple), une notification XPP est envoyée à l'appareil. La notification est au format suivant:

<device_id>/delete

À la réception d'une notification de ce type, l'appareil DOIT accéder au serveur pour vérifier son état. Les appareils Cloud Print DOIVENT utiliser:

/cloudprint/printer?printerid=<printer_id>

L'appareil DOIT recevoir une réponse HTTP positive avec la valeur success=false et aucune description d'appareil/d'imprimante. Cela signifie que l'appareil a été supprimé du serveur et qu'il DOIT effacer ses identifiants et revenir au mode de configuration d'usine par défaut.

Chaque fois que l'appareil reçoit une réponse indiquant qu'il a été supprimé à la suite de l'utilisation de l'API /cloudkms/printer (démarrage, notification des paramètres de mise à jour, ping quotidien), il DOIT supprimer ses identifiants et passer en mode par défaut.

4.2. API /privet/info

L'API info est OBLIGATOIRE et DOIT être implémentée par tous les appareils. Il s'agit d'une requête HTTP GET pour "/privet/info" url: GET /privet/info HTTP/1.1

L'API Info renvoie des informations de base sur un appareil et une fonctionnalité compatibles. Cette API NE DOIT PAS modifier l'état de l'appareil ni effectuer aucune action, car elle est vulnérable aux attaques XSRF. Cette seule API est autorisée à avoir un en-tête "X-Privet-Token" vide. Les clients doivent appeler l'API /privet/info avec l'en-tête "X-Privet-Token" défini sur X-Privet-Token : "

L'API d'informations DOIT renvoyer des données cohérentes avec celles disponibles dans l'enregistrement TXT lors de la découverte.

4.2.1. Input

L'API /privet/info ne comporte aucun paramètre d'entrée.

4.2.2. Aller-retour

L'API /privet/info renvoie des informations de base sur l'appareil et les fonctionnalités compatibles.

La colonne TXT indique le champ correspondant dans l'enregistrement TXT DNS-SD.

Nom de la valeur	Type de valeur	Description	TXT
version	chaîne	Version la plus élevée (major.minor) de l'API compatible, actuellement 1.0
name (nom)	chaîne	Nom lisible de l'appareil.	ty
description	chaîne	(Facultatif) Description de l'appareil. DOIT être modifié par l'utilisateur.	note
url	chaîne	URL du serveur auquel cet appareil parle. L'URL DOIT inclure une spécification de protocole, par exemple: https://www.google.com/dashboard.	url
type	liste de chaînes	Liste des types d'appareils compatibles.	type
id	chaîne	ID de l'appareil (vide si l'appareil n'a pas encore été enregistré)	id
device_state [état_appareil]	chaîne	État de l'appareil. inactif signifie que l'appareil est prêt Le traitement signifie que l'appareil est occupé et que les fonctionnalités peuvent être limitées pendant un certain temps. arrêté signifie que l'appareil ne fonctionne pas et qu'une intervention de l'utilisateur est requise.
état_de_connexion	chaîne	État de la connexion au serveur (base_url) en ligne - connexion disponible hors connexion - aucune connexion connexion - exécution de la procédure de démarrage non configuré : la connexion n'a pas encore été configurée Un appareil enregistré peut signaler son état de connexion en fonction de l'état du canal de notification (par exemple, l'état de connexion PPP).	cs
fabricant	chaîne	Nom du fabricant de l'appareil
modèle	chaîne	Modèle de l'appareil
numéro_de_série	chaîne	Identifiant unique de l'appareil. Dans cette spécification, il DOIT être un UUID. (Spécification GCP 1.1) (facultatif) Nous vous recommandons vivement d'utiliser le même ID de série partout, afin que différents clients puissent identifier le même appareil. Par exemple, les imprimantes mettant en œuvre IPP peuvent utiliser cet ID de série dans le champ "id-device-id".
micrologiciel	chaîne	Version du micrologiciel de l'appareil
uptime	int	Nombre de secondes depuis le démarrage de l'appareil.
Configurer une URL	chaîne	URL (facultative) de la page (avec protocole de configuration)
URL_support	chaîne	URL (facultative) de la page avec protocole (y compris le protocole) et informations sur la FAQ
URL de mise à jour	chaîne	URL (facultative) (y compris le protocole) de la page contenant les instructions de mise à jour du micrologiciel
x-privet-jeton	chaîne	Valeur de l'en-tête X-Privet-Token qui doit être transmise à toutes les API pour empêcher les attaques XSSI et XSRF. Pour en savoir plus, reportez-vous à la section 6.1.
api	description des API	Liste des API compatibles (décrites ci-dessous)
état_sémantique	JSON	(Facultatif) État sémantique de l'appareil au format CloudDeviceState.

api : est une liste JSON contenant la liste des API disponibles via le réseau local. Notez que toutes les API peuvent ne pas être disponibles en même temps sur le réseau local. Par exemple, un appareil nouvellement connecté ne doit accepter que l'API /register:

"api": [
        "/privet/register",
]

Une fois l'enregistrement de l'appareil terminé, il NE DOIT plus être compatible avec l'API /register. L'appareil doit également se renseigner auprès du service pour savoir quelles API peuvent être exposées sur le réseau local. Exemple :

"api": [
        "/privet/accesstoken",
        "/privet/capabilities",
        "/privet/printer/submitdoc",
]

Les API suivantes sont actuellement disponibles:

/privet/register : API pour l'enregistrement d'appareils sur le réseau local (Pour plus de détails, consultez la section /privet/register.) Cette API DOIT être masquée une fois l'appareil correctement enregistré dans le cloud.
/privet/accesstoken : API pour demander un jeton d'accès à partir de l'appareil (pour plus d'informations, reportez-vous à l'API /privet/accesstoken).
/privet/capacity : API pour récupérer les fonctionnalités d'un appareil (pour en savoir plus, consultez la section /privet/features API).
/privet/printer/* : API spécifique au type d'appareil, voir les API spécifiques aux imprimantes pour plus de détails.

Voici un exemple de réponse /privet/info. (Notez l'absence de l'API /privet/register, car il s'agit d'un appareil déjà enregistré) :

{
        "version": "1.0",
        "name": "Gene’s printer",
        "description": "Printer connected through Chrome connector",
        "url": "https://www.google.com/cloudprint",
        "type": [
                "printer"
        ],
        "id": "11111111-2222-3333-4444-555555555555",
        "device_state": "idle",
        "connection_state": "online",
        "manufacturer": "Google",
        "model": "Google Chrome",
        "serial_number": "1111-22222-33333-4444",
        "firmware": "24.0.1312.52",
        "uptime": 600,
        "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=en",
        "support_url": "http://support.google.com/cloudprint/?hl=en",
        "update_url": "http://support.google.com/cloudprint/?hl=en",
        "x-privet-token": "AIp06DjQd80yMoGYuGmT_VDAApuBZbInsQ:1358377509659",
        "api": [
                "/privet/accesstoken",
                "/privet/capabilities",
                "/privet/printer/submitdoc",
        ]
}

Voici un exemple de réponse /privet/info pour une imprimante à court d'encre (remarquez le champ sémantique_state) :

{
        "version": "1.0",
        "name": "Gene’s printer",
        "description": "Printer connected through Chrome connector",
        "url": "https://www.google.com/cloudprint",
        "type": [
                "printer"
        ],
        "id": "11111111-2222-3333-4444-555555555555",
        "device_state": "stopped",
        "connection_state": "online",
        "manufacturer": "Google",
        "model": "Google Chrome",
        "serial_number": "1111-22222-33333-4444",
        "firmware": "24.0.1312.52",
        "uptime": 600,
        "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=en",
        "support_url": "http://support.google.com/cloudprint/?hl=en",
        "update_url": "http://support.google.com/cloudprint/?hl=en",
        "x-privet-token": "AIp06DjQd80yMoGYuGmT_VDAApuBZbInsQ:1358377509659",
        "api": [
                "/privet/accesstoken",
                "/privet/capabilities",
                "/privet/printer/submitdoc",
        ],
        "semantic_state": {
                "version": "1.0",
                "printer": {
                        "state": "STOPPED",
                        "marker_state": {
                                "item": [
                                        {
                                                "vendor_id": "ink",
                                                "state": "EXHAUSTED",
                                                "level_percent": 0
                                        }
                                ]
                        }
                }
        }
}

4.2.3. Erreurs

L'API /privet/info ne doit renvoyer une erreur que si l'en-tête X-Privet-Token est manquant. Il DOIT s'agir d'une erreur HTTP 400:

HTTP/1.1 400 Missing X-Privet-Token header.

4.3. API /privet/register

L'API /privet/register est FACULTATIVE. Il s'agit d'une requête HTTP POST. L'API /privet/register DOIT rechercher un en-tête X-Privet-Token valide. L'appareil DOIT mettre en œuvre cette API sur "/privet/register" url:

POST /privet/register?action=start&user=user@domain.com HTTP/1.1
POST /privet/register?action=complete&user=user@domain.com HTTP/1.1

L'appareil doit exposer l'API /privet/register SEULEMENT lorsqu'elle autorise l'enregistrement anonyme à un moment donné. Exemple :

Lorsque l'appareil est allumé (ou après avoir cliqué sur un bouton spécial) et qu'il n'a pas encore été enregistré, il doit exposer l'API /privet/register pour permettre à un utilisateur du réseau local de revendiquer l'imprimante.
Une fois l'enregistrement terminé, l'appareil doit cesser d'exposer l'API /privet/register pour empêcher un autre utilisateur du réseau local de le récupérer.
Certains appareils peuvent enregistrer des appareils de différentes manières et ne doivent pas exposer du tout l'API /privet/register (par exemple, le connecteur Chrome Cloud Print).

Le processus d'inscription se déroule en trois étapes (voir l'inscription anonyme à Cloud Print).

Lancez un processus d'inscription anonyme.
Un client lance ce processus en appelant l'API /privet/register. L'appareil peut attendre la confirmation de l'utilisateur à ce moment-là.
Obtenir un jeton de revendication.

Le client s'interroge pour savoir quand l'appareil est prêt à continuer. Une fois que l'appareil est prêt, il envoie une requête au serveur pour récupérer le jeton et l'URL d'enregistrement. Le jeton reçu et l'URL DOIVENT être renvoyés au client. Au cours de cette étape, si l'appareil reçoit un autre appel pour initialiser l'enregistrement, il doit:

S'il s'agit du même utilisateur qui a commencé l'enregistrement, abandonnez toutes les données précédentes (le cas échéant) et lancez un nouveau processus d'enregistrement.
S'il s'agit d'un autre utilisateur, renvoyez une erreur device_occupation et un délai avant expiration de 30 secondes.

Suivez la procédure d'inscription.

Une fois que le client a revendiqué l'appareil, il doit lui demander de terminer l'enregistrement. Une fois le processus d'enregistrement terminé, l'appareil doit envoyer une annonce de mise à jour, y compris l'ID de l'appareil nouvellement acquis.

Remarque: Lorsque l'appareil traite un appel d'API /privet/register, aucun autre appel d'API /privet/register ne peut être traité simultanément. L'appareil DOIT renvoyer l'erreur device_occupation et un délai avant expiration de 30 secondes.

La confirmation d'inscription de l'utilisateur sur l'appareil est vivement recommandée. S'il est implémenté, l'appareil DOIT attendre la confirmation de l'utilisateur APRÈS avoir reçu un appel d' /privet/register?action=start API. Le client appellera l'API /privet/register?action=getClaimToken pour savoir quand la confirmation de l'utilisateur sera terminée et quand le jeton de revendication sera disponible. Si l'utilisateur annule l'enregistrement sur l'appareil (en appuyant sur le bouton "Annuler", par exemple), l'erreur user_cancel DOIT être renvoyée. Si l'utilisateur n'a pas confirmé l'enregistrement dans un délai spécifique, l'erreur confirmation_timeout DOIT être renvoyée. Pour en savoir plus, consultez la section "Par défaut".

4.3.1. Input

L'API /privet/register présente les paramètres d'entrée suivants:

Nom	Value
action	Voici les différents états possibles : start - pour lancer le processus d'enregistrement getClaimToken - récupérer le jeton de revendication de l'appareil cancel - pour annuler le processus d'enregistrement complete - pour terminer le processus d'enregistrement
user	Adresse e-mail de l'utilisateur qui revendiquera cet appareil.

L'appareil DOIT vérifier que l'adresse e-mail de toutes les actions (début, getClaimToken, annuler, terminée) correspond.

4.3.2. Aller-retour

L'API /privet/register renvoie les données suivantes:

Nom de la valeur	Type de valeur	Description
action	chaîne	Même action que dans le paramètre d'entrée.
user	chaîne (facultatif)	Même utilisateur que dans le paramètre d'entrée (peut être manquant s'il est omis dans l'entrée).
token	chaîne (facultatif)	Jeton d'enregistrement (obligatoire pour la réponse "getClaimToken" ; omis pour la valeur "start" et "complet")
revendiquer_url	chaîne (facultatif)	URL d'inscription (obligatoire pour la réponse "getClaimToken") ou omise pour la valeur "start" et "complete". Pour les imprimantes cloud, il doit s'agir de l'URL "complete_invite_url" fournie par le serveur.
automatisé_revendication	chaîne (facultatif)	URL d'inscription (obligatoire pour la réponse "getClaimToken") ou omise pour la valeur "start" et "complete". Pour les imprimantes cloud, il doit s'agir de l'élément "Automate_invite_url" reçu du serveur.
id_appareil	chaîne (facultatif)	Nouvel ID de l'appareil (supprimé pour la réponse "start", obligatoire, obligatoire pour la valeur "complet")

L'appareil DOIT renvoyer son ID d'appareil dans la réponse de l'API /privet/info UNIQUEMENT une fois l'enregistrement terminé.

Exemple 1 :

{
        "action": "start",
        "user": "user@domain.com",
}

Exemple 2 :

{
        "action": "getClaimToken",
        "user": "user@domain.com",
        "token": "AAA111222333444555666777",
        "claim_url": "https://domain.com/SoMeUrL",
}

Exemple 3 :

{
        "action": "complete",
        "user": "user@domain.com",
        "device_id": "11111111-2222-3333-4444-555555555555",
}

4.3.3. Erreurs

L'API /privet/register peut renvoyer les erreurs suivantes (consultez la section "Erreurs" pour plus de détails):

Error	Description
appareil_occupé	L'appareil est occupé et ne peut pas effectuer l'action demandée. Réessayez après le délai.
en attente_action_utilisateur	En réponse à "getClaimToken" indique que l'appareil est toujours en attente de confirmation de l'utilisateur, et la requête "getClaimToken" doit être relancée après le délai d'inactivité.
annulation_utilisateur	L'utilisateur a explicitement annulé le processus d'enregistrement depuis l'appareil.
confirmation_timeout	Le délai de confirmation de l'utilisateur expire.
invalid_action [non_valide]	Une action non valide a été appelée. Par exemple, si le client a appelé action=complete avant d'appeler action=start et action=getClaimToken.
invalid_params	Les paramètres spécifiés dans la requête ne sont pas valides. (Les paramètres inconnus doivent être ignorés pour garantir leur compatibilité.) Par exemple, renvoyez ce résultat si le client a appelé action=unknown ou user=.
Erreur de configuration de l'appareil	La date et l'heure (ou d'autres paramètres) sont incorrectes du côté de l'appareil. L'utilisateur doit accéder au site Web interne de l'appareil et configurer ses paramètres.
offline	L'appareil est actuellement hors connexion et ne peut pas communiquer avec le serveur.
Erreur_du_serveur	Erreur serveur lors du processus d'inscription.
invalide_x_privet_jeton	X-Privet-Token non valide ou vide dans la requête.

L'appareil DOIT cesser d'exposer l'API /privet/register une fois l'enregistrement terminé. Si l'appareil n'expose pas l'API /privet/register, il DOIT renvoyer une erreur HTTP 404. Par conséquent, si un appareil est déjà enregistré, l'appel de cette API DOIT renvoyer le code d'erreur 404. Si l'en-tête X-Privet-Token est manquant, l'appareil DOIT renvoyer une erreur HTTP 400.

4.4. API /privet/accesstoken

L'API /privet/accesstoken est FACULTATIVE. Il s'agit d'une requête HTTP GET. L'API /privet/accesstoken DOIT rechercher un en-tête "&-trive-Token" valide. L'appareil DOIT implémenter cette API sur l'URL "/privet/accesstoken" url :

GET /privet/accesstoken HTTP/1.1

Lorsque l'appareil reçoit l'appel d'API /accesstoken, il doit appeler le serveur pour récupérer le jeton d'accès pour l'utilisateur donné et le renvoyer au client. Le client utilisera ensuite le jeton d'accès pour accéder à cet appareil via le cloud.

Les appareils Cloud Print DOIVENT appeler l'API suivante:

/cloudprint/proximitytoken

et transmettre les paramètres "printerid\"> Si la requête aboutit, la réponse du serveur contient l'objet suivant :

"proximity_token": {
        "user": "user@domain.com",
        "token": "AAA111222333444555666777",
        "expires_in": 600
}

Les appareils Cloud Print DOIVENT transmettre la valeur de l'objet"proximity_token"dans la réponse aux appels d'API locaux /privet/accesstoken. Il est plus avantageux (Pérennisé) que l'appareil puisse transmettre TOUS les paramètres (y compris ceux qui ne sont pas décrits dans cette spécification).

4.4.1. Input

L'API /privet/accesstoken comporte les paramètres d'entrée suivants:

Nom	Value
user	Adresse e-mail de l'utilisateur qui souhaitait utiliser ce jeton d'accès. Peut être vide dans la requête.

4.4.2. Aller-retour

L'API /privet/accesstoken renvoie les données suivantes:

Nom de la valeur	Type de valeur	Description
jeton	chaîne	Jeton d'accès renvoyé par le serveur
user	chaîne	Même utilisateur que dans le paramètre d'entrée.
expires_in	int	Nombre de secondes jusqu'à l'expiration de ce jeton. Envoyé par le serveur et transmis dans cette réponse.

Exemple :

{
        "token": "AAA111222333444555666777",
        "user": "user@domain.com",
        "expires_in": 600
}

4.4.3. Erreurs

L'API /privet/accesstoken peut renvoyer les erreurs suivantes (voir la section "Erreurs" pour plus de détails):

Error	Description
offline	L'appareil est actuellement hors connexion et ne peut pas communiquer avec le serveur.
accès refusé	Droits insuffisants. Accès refusé. L'appareil doit renvoyer cette erreur lorsque la requête a été explicitement refusée par le serveur.
invalid_params	Les paramètres spécifiés dans la requête ne sont pas valides. (Les paramètres inconnus doivent être ignorés pour garantir leur compatibilité.) (par exemple, /accesstoken?user= ou /accesstoken).
Erreur_du_serveur	Erreur du serveur.
invalide_x_privet_jeton	Le jeton X-Privet est incorrect ou vide dans la requête.

Si l'appareil n'expose pas l'API /privet/accesstoken, il DOIT renvoyer une erreur HTTP 404. Si l'en-tête X-Privet-Token est manquant, l'appareil DOIT renvoyer une erreur HTTP 400.

4.5. API /privet/features

L'API /privet/features est FACULTATIVE. Il s'agit d'une requête HTTP GET. L'API /privet/abilities DOIT rechercher un en-tête "X-Privet-Token" valide. L'appareil DOIT mettre en œuvre cette API sur /privet/features" url :

GET /privet/capabilities HTTP/1.1

Lorsque l'appareil reçoit un appel d'API /features, s'il est en mesure de le faire, il DOIT contacter le serveur pour obtenir les fonctionnalités de mise à jour. Par exemple, si une imprimante accepte de publier une tâche d'impression (reçue localement) via le service Cloud Print, elle doit renvoyer les fonctionnalités renvoyées par ce service. Dans ce cas, Cloud Print peut modifier les fonctionnalités d'origine de l'imprimante en ajoutant de nouvelles fonctionnalités avant d'envoyer la tâche à l'imprimante. Le cas le plus courant est une liste des types de documents acceptés. Si l'imprimante est hors connexion, elle doit renvoyer les types de documents compatibles. Toutefois, si l'imprimante est en ligne et enregistrée auprès de Cloud Print, elle DOIT renvoyer le type "*/*"". Dans ce cas, le service Cloud Print effectue la conversion nécessaire. Pour l'impression hors connexion, l'imprimante DOIT prendre en charge au moins le format image/pwg-raster".

4.5.1. Input

L'API /privet/features possède les paramètres d'entrée suivants:

Nom	Value
offline	(facultatif) Ne peut être que "hors connexion=1". Dans ce cas, l'appareil doit renvoyer des fonctionnalités destinées à être utilisées hors connexion (si elles diffèrent des fonctionnalités "en ligne").

4.5.2. Aller-retour

L'API /privet/features renvoie les fonctionnalités de l'appareil au format JSON CDD (Cloud Device Description) (consultez le document CDD pour en savoir plus). Les imprimantes doivent au minimum renvoyer une liste des types compatibles. Par exemple, une imprimante connectée à Internet actuellement renvoyée peut renvoyer ce qui suit (au minimum) :

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        {
                                "content_type": "application/pdf",
                                "min_version": "1.4"
                        },
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" },
                        { "content_type": "*/*" }
                ]
        }
}

Lorsque celle-ci est déconnectée du serveur, elle peut renvoyer les éléments suivants :

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        {
                                "content_type": "application/pdf",
                                "min_version": "1.4"
                        },
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" }
                ]
        }
}

Remarque : Les imprimantes indiquent la priorité des types de contenu compatibles en fonction de l'ordre. Dans les exemples ci-dessus, l'imprimante indique qu'elle préfère les données d'application aux fichiers PDF par rapport à l'image/pwg-raster&image/jpeg. Dans la mesure du possible, les clients doivent respecter les priorités des imprimantes (consultez le document CDD pour plus d'informations).

4.5.3. Erreurs

L'API /privet/features peut renvoyer les erreurs suivantes (consultez la section "Erreurs" pour plus de détails):

Error	Description
invalide_x_privet_jeton	X-Privet-Token non valide ou vide dans la requête.

Si l'appareil n'expose pas l'API /privet/features, il DOIT renvoyer une erreur HTTP 404. Si l'en-tête X-Privet-Token est manquant, l'appareil DOIT renvoyer une erreur HTTP 400.

4.6. Erreurs

Les erreurs sont renvoyées par les API ci-dessus au format suivant:

Nom de la valeur	Type de valeur	Description
erreur	chaîne	Type d'erreur (défini par API)
description	chaîne (facultatif)	Description lisible de l'erreur.
serveur_api	chaîne (facultatif)	En cas d'erreur du serveur, ce champ contient l'API du serveur qui a échoué.
server_code [code_serveur]	int (facultatif)	En cas d'erreur du serveur, ce champ contient le code d'erreur renvoyé par le serveur.
serveur_http_code	int (facultatif)	En cas d'erreur HTTP du serveur, ce champ contient le serveur de code d'erreur HTTP renvoyé.
timeout	int (facultatif)	Nombre de secondes d'attente du client avant de réessayer (pour les erreurs récupérables uniquement). Le client DOIT randomiser le délai réel de cette valeur à une valeur supérieure à 20%.

Toutes les API DOIVENT renvoyer une erreur HTTP 400 s'il manque l'en-tête X-Privet-Token.

HTTP/1.1 400 En-tête X-Privet-Token manquant.

Exemple 1 :

{
        "error": "server_error",
        "description": "Service unavailable",
        "server_api": "/submit",
        "server_http_code": 503
}

Exemple 2 :

{
        "error": "printer_busy",
        "description": "Printer is currently printing other job",
        "timeout": 15
}

5. API Printer

L'un des types d'appareils compatibles avec ce protocole est le type d'imprimante. Les appareils compatibles avec ce type PEUVENT mettre en œuvre des fonctionnalités spécifiques aux imprimantes. Idéalement, l'impression sur des imprimantes connectées au Web passe par un serveur Cloud Print:

Dans certains cas, un client peut avoir besoin d'envoyer un document en local. Cela peut être nécessaire lorsque le client ne possède pas d'ID Google ou ne parvient pas à communiquer avec le serveur Cloud Print. Dans ce cas, la tâche d'impression est envoyée en local à l'imprimante. L'imprimante utilise ensuite le service Cloud Print pour mettre les tâches en file d'attente et effectuer les conversions. L'imprimante va republier la tâche envoyée en local au service Cloud Print, puis la demander, car elle a été envoyée via le cloud. Ce processus offre une expérience utilisateur flexible en termes de service (conversion) et de gestion/suivi des tâches d'impression.

Étant donné que le service Cloud Print implémente la conversion, l'imprimante DOIT annoncer qu'elle accepte tous les formats d'entrée ("*/*") dans la liste des types de contenu compatibles:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "*/*" }
                ]
        }
}

Dans certains cas, une solution complètement hors connexion est souhaitée. Étant donné que les imprimantes sont compatibles avec un nombre limité de formats d'entrée, un client devra convertir les documents dans quelques formats d'imprimantes compatibles de manière native.

Cette spécification impose que toutes les imprimantes soient compatibles avec le format de pixel PWG (image/pwg-raster") pour l'étui d'impression hors connexion. Une imprimante peut prendre en charge d'autres formats (par exemple, JPEG) et, si un client le permet, elle peut envoyer des documents dans ce format. L'imprimante DOIT exposer les types compatibles via l'API /features, par exemple:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" }
                ]
        }
}

Un client peut lancer une impression sur le réseau local de deux manières.

Impression simple : le client envoie le document via le réseau local à l'API /submitdoc (sans spécifier le paramètre job_id). Le document envoyé sera imprimé à l'aide des paramètres de ticket d'impression par défaut, et aucun état de tâche d'impression n'est nécessaire. Si l'imprimante prend en charge UNIQUEMENT ce type d'impression, elle DOIT annoncer UNIQUEMENT l'API /submitdoc dans la réponse de l'API /privet/info.

"api": [
        "/privet/accesstoken",
        "/privet/capabilities",
        "/privet/printer/submitdoc",
]

Impression avancée : le client doit d'abord créer une tâche d'impression sur l'imprimante en appelant l'API /privet/printer/createjob et une demande de tâche CJT valide dans la requête. L'imprimante DOIT stocker le ticket d'impression en mémoire et renvoyer un job_id au client. Le client appellera ensuite l'API /printer/submitdoc et spécifiera l'identifiant job_id déjà reçu. L'imprimante démarre alors. Le client interroge l'imprimante pour connaître l'état de la tâche d'impression en appelant l'API /privet/printer/jobstate.

Dans un multicompte, il n'y a aucune garantie que cette API soit appelée. Un client peut appeler /createjob entre les appels /createjob->/submitdoc d'un autre client. Pour éviter les interblocages et améliorer l'usabilité, nous vous recommandons de disposer d'une petite file d'attente de tâches d'impression en attente sur l'imprimante (au moins trois à cinq):

/createjob occupe la première place disponible dans la file d'attente.
La durée de vie de la tâche (dans la file d'attente) est d'au moins cinq minutes.
Si tous les emplacements de la file d'attente sont sélectionnés, la tâche la plus ancienne non liée aux impressions doit être supprimée et une nouvelle tâche y sera placée.
Si une tâche d'impression est en cours sur l'appareil (impression simple ou avancée), l'état /submitdoc doit renvoyer une disponibilité et proposer un délai avant expiration pour réessayer.
Si /submitdoc fait référence à une tâche supprimée de la file d'attente (en raison d'un remplacement ou d'un délai d'inactivité), l'imprimante doit renvoyer l'erreur invalid_print_job, et le client relance le processus à l'étape /createjob. Le client DOIT attendre un délai d'expiration aléatoire pouvant aller jusqu'à cinq secondes avant de réessayer.

Si des contraintes de mémoire empêchent le stockage de plusieurs tâches en attente sur l'appareil, il est possible de disposer d'une file d'attente contenant une tâche d'impression. Il doit toujours suivre le même protocole que ci-dessus. Une fois qu'une tâche est terminée ou a échoué avec une erreur, l'imprimante doit stocker les informations sur l'état de la tâche pendant au moins cinq minutes. La taille de la file d'attente permettant de stocker l'état des tâches terminées doit être d'au moins 10. Si d'autres états de tâche doivent être stockés, le plus ancien peut être supprimé de la file d'attente avant l'expiration du délai de cinq minutes.

Remarque:Pour l'instant, les clients interrogent l'état de la tâche. À l'avenir, nous pouvons exiger que l'imprimante envoie une notification DNS TXT lorsque N'IMPORTE LEQUEL des états de la tâche d'impression a changé.

5.1. API /privet/printer/createjob

L'API /privet/printer/createjob est FACULTATIVE (voir "Impression simple" ci-dessus). Il s'agit d'une requête HTTP POST. L'API /privet/printer/createjob DOIT rechercher un en-tête "&-trive-Token" valide. L'appareil DOIT implémenter cette API sur "/privet/printer/createjob" url:

POST /privet/printer/createjob HTTP/1.1

Lors de la réception d'un appel d'API /privet/printer/createjob, l'imprimante DOIT créer un ID de tâche d'impression, stocker le ticket d'impression reçu au format CJT, puis renvoyer l'ID de tâche d'impression au client.

5.1.1. Input

L'API /privet/printer/createjob ne contient aucun paramètre d'entrée. Le corps de la requête doit contenir les données de ticket de tâche d'impression au format CJT.

5.1.2. Aller-retour

L'API /privet/printer/createjob renvoie les données suivantes:

Nom de la valeur	Type de valeur	Description
job_id	chaîne	ID de la tâche d'impression nouvellement créée.
expires_in	int	Nombre de secondes pendant lesquelles cette tâche d'impression est valide.

Exemple :

{
        "job_id": "123",
        "expires_in": 600
}

5.1.3. Erreurs

L'API /privet/printer/createjob peut renvoyer les erreurs suivantes (pour plus d'informations, consultez la section "Erreurs"):

Error	Description
ticket_non valide	Le billet envoyé n'est pas valide.
impression_occupée	L'imprimante est occupée et ne peut pas traiter la tâche /create pour le moment. Réessayez après le délai.
Erreur_imprimante	L'imprimante est en état d'erreur et nécessite une interaction de la part de l'utilisateur pour la corriger. La description doit contenir des explications plus détaillées (par exemple, "Bourrage papier" dans le Bac 1).
invalide_x_privet_jeton	X-Privet-Token non valide ou vide dans la requête.

Si l'appareil n'expose pas /privet/printer/createjob, il DOIT renvoyer une erreur HTTP 404. Si l'en-tête X-Privet-Token est manquant, l'appareil DOIT renvoyer une erreur HTTP 400.

5.2. /privet/printer/submitdoc API

/privet/printer/submitdoc est obligatoire pour mettre en œuvre l'impression sur un réseau local (hors connexion ou à nouveau sur Cloud Print). Il s'agit d'une requête HTTP POST. L'API /privet/printer/submitdoc DOIT rechercher un en-tête "X-Privet-Token" valide. L'appareil DOIT mettre en œuvre cette API sur /privet/printer/submitdoc" url :

POST /privet/printer/submitdoc HTTP/1.1

Lorsque vous recevez l'appel d'API /privet/printer/submitdoc, l'imprimante doit commencer à imprimer. Si l'impression ne peut pas commencer, le message d'erreur "printer_ animée" doit s'afficher ainsi qu'un délai avant expiration recommandé que le client devra attendre avant de réessayer.

Si l'imprimante n'est pas en mesure de conserver toutes les données du tampon interne, elle DOIT utiliser des mécanismes TCP pour ralentir le transfert de données jusqu'à ce qu'elle imprime une partie du document et rende alors une partie de la mémoire tampon disponible. Par exemple, l'imprimante peut définir windowsize=0 sur des couches TCP, ce qui fait attendre le client.

L'envoi d'un document à l'imprimante peut prendre beaucoup de temps. Le client doit pouvoir vérifier l'état de l'imprimante et de la tâche (impression avancée) pendant l'impression. Pour ce faire, l'imprimante DOIT permettre au client d'appeler les API /privet/info et /privet/printer/jobstate tout en traitant les appels d'API /privet/printer/submitdoc. Il est recommandé à tous les clients de démarrer un nouveau thread pour exécuter l'appel d'API /privet/printer/submitdoc, afin que le thread principal puisse utiliser les API /privet/info et /privet/printer/jobstate pour vérifier l'état des imprimantes et des tâches.

Remarque: À la fin ou à l'avortement de la tâche d'impression locale, il est vivement recommandé (et obligatoire dans une prochaine version de cette spécification) de signaler l'état final de la tâche à l'interface /dashboard/submit pour la comptabilité et l'expérience utilisateur. Les paramètres "printerid" et "titleType" et "final_ sémantique_state" (au format PrintJobState) sont obligatoires, tandis que les paramètres "tag" (paramètre répété) et "ticket" et le "ticket de travail" sont les suivants. Notez que le PrintJobState fourni doit en fait être final, c'est-à-dire que son type doit être DONE ou ABORTED, et qu'une cause doit être fournie s'il est ABORTED (pour en savoir plus, consultez JobState). Notez également que l'utilisation de l'interface /translate/submit pour signaler des tâches d'impression locales n'est pas mentionnée dans la spécification, car cette section est destinée à décrire l'utilisation principale de l'interface: envoyer une tâche d'impression avec le document à imprimer fourni dans le paramètre "content".

5.2.1. Input

L' /privet/printer/submitdoc API comporte les paramètres d'entrée suivants:

Nom	Value
job_id	(Facultatif) ID de la tâche d'impression. Peut être omis pour les impressions simples (voir ci-dessus). Doit correspondre à celui renvoyé par l'imprimante.
nom_utilisateur	(Facultatif) Nom d'utilisateur lisible. Cette valeur n'est pas définitive et ne doit être utilisée que pour les annotations de tâche d'impression. Si la tâche est à nouveau publiée dans le service Cloud Print, cette chaîne doit être associée à la tâche.
nom_client	(Facultatif) Nom de l'application cliente à l'origine de cette requête. À des fins d'affichage uniquement. Si la tâche est à nouveau publiée dans le service Cloud Print, cette chaîne doit être associée à la tâche.
nom_tâche	(Facultatif) Nom de la tâche d'impression à enregistrer. Si la tâche est à nouveau publiée dans le service Cloud Print, cette chaîne doit être associée à la tâche.
offline	(facultatif) La valeur peut être "hors connexion=1". Dans ce cas, l'imprimante ne doit effectuer l'impression que hors connexion (pas de nouvelle publication sur le serveur Cloud Print).

Le corps de la requête doit contenir un document valide pour l'impression. La valeur "Content-Length" doit inclure la longueur correcte de la requête. L'en-tête "Content-Type" doit être défini sur le type MIME du document et doit correspondre à l'un des types dans le CDD (sauf si CDD spécifie "*/*").

Nous vous recommandons vivement de fournir un nom d'utilisateur (ou une adresse e-mail) valide, ainsi qu'un nom de client et d'offre d'emploi pour cette requête. Ces champs ne sont utilisés que dans les interfaces utilisateur pour améliorer l'expérience utilisateur.

5.2.2. Aller-retour

L' /privet/printer/submitdoc API renvoie les données suivantes:

Nom de la valeur	Type de valeur	Description
job_id	chaîne	ID de la tâche d'impression nouvellement créée (impression simple) ou de job_id spécifié dans la requête (impression avancée).
expires_in	int	Nombre de secondes pendant lesquelles cette tâche d'impression est valide.
type_tâche	chaîne	Type de contenu du document envoyé.
taille_tâche	entier 64 bits	Taille des données d'impression en octets.
nom_tâche	chaîne	(Facultatif) Nom de la tâche identique à celui saisi (le cas échéant).

Exemple :

{
        "job_id": "123",
        "expires_in": 500,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document"
}

5.2.3. Erreurs

L'API /privet/printer/submitdoc peut renvoyer les erreurs suivantes (pour plus d'informations, consultez la section "Erreurs"):

Error	Description
invalid_print_job [tâche_impression_incorrecte]	L'ID de tâche non valide/arrivé à expiration est spécifié dans la requête. Réessayez après le délai d'inactivité.
invalid_document_type [type_document_non valide]	Le type MIME du document n'est pas compatible avec l'imprimante.
document_incorrect	Le document envoyé n'est pas valide.
document_trop_grand	Le document dépasse la taille maximale autorisée.
impression_occupée	L'imprimante est occupée et ne peut pas traiter le document pour l'instant. Réessayez après le délai.
Erreur_imprimante	L'imprimante est en état d'erreur et nécessite une interaction de la part de l'utilisateur pour la corriger. La description doit contenir des explications plus détaillées (par exemple, "Bourrage papier" dans le Bac 1).
invalid_params	Les paramètres spécifiés dans la requête ne sont pas valides. (Les paramètres inconnus doivent être ignorés pour garantir leur compatibilité.)
annulation_utilisateur	L'utilisateur a explicitement annulé le processus d'impression depuis l'appareil.
Erreur_du_serveur	Échec de la publication du document dans Cloud Print.
invalide_x_privet_jeton	X-Privet-Token non valide ou vide dans la requête.

Si l'appareil n'expose pas le fichier /privet/printer/submitdoc, il DOIT renvoyer une erreur HTTP 404. Si l'en-tête X-Privet-Token est manquant, l'appareil DOIT renvoyer une erreur HTTP 400.

Remarque : L'API /privet/printer/submitdoc peut nécessiter un traitement spécial du côté de l'imprimante (en raison de la charge utile importante). Dans certains cas (en fonction de la plate-forme et de l'implémentation du serveur HTTP de l'imprimante), l'imprimante peut fermer le socket AVANT de renvoyer l'erreur HTTP. En revanche, l'imprimante peut renvoyer une erreur 503 (au lieu de l'erreur Privet). Les imprimantes DOIVENT essayer autant que possible de renvoyer Privet. Toutefois, tous les clients qui mettent en œuvre la spécification Privet DOIVENT gérer les fermetures de socket (pas d'erreur HTTP) et les erreurs HTTP 503 pour l'API /privet/printer/submitdoc. Dans ce cas, le client DOIT le gérer comme une erreur Privet "printer_welcome" avec un délai d'expiration défini sur 15 secondes. Pour éviter un nombre infini de tentatives, le client peut arrêter de réessayer après un nombre raisonnable de tentatives (par exemple, 3).

5.3. API /privet/printer/jobstate

L'API /privet/printer/jobstate est FACULTATIVE (voir "Impression simple" ci-dessus). Il s'agit d'une requête HTTP GET. L'API /privet/printer/jobstate DOIT rechercher un en-tête "&-trive-Token" valide. L'appareil DOIT mettre en œuvre cette API sur "/privet/printer/jobstate" url :

GET /privet/printer/jobstate HTTP/1.1

Lorsqu'il reçoit un appel d'API /privet/printer/jobstate, une imprimante doit renvoyer l'état de la tâche d'impression demandée ou de l'erreur invalid_print_job.

5.3.1. Input

L'API /privet/printer/jobstate comporte les paramètres d'entrée suivants:

Nom	Value
job_id	ID de la tâche d'impression pour laquelle renvoyer l'état.

5.3.2. Aller-retour

L'API /privet/printer/jobstate renvoie les données suivantes:

Nom de la valeur	Type de valeur	Description
job_id	chaîne	Les informations d'état concernent l'ID de la tâche d'impression.
state	chaîne	draft : la tâche d'impression a été créée sur l'appareil (aucun appel /privet/printer/submitdoc n'a encore été reçu). queued : la tâche d'impression a été reçue et mise en file d'attente, mais l'impression n'a pas encore commencé. in_progress : la tâche d'impression est en cours d'impression. arrêtée : la tâche d'impression a été mise en veille, mais elle peut être redémarrée manuellement ou automatiquement. done : la tâche d'impression est terminée. aborted : échec de la tâche d'impression.
description	chaîne	(Facultatif) Description lisible de l'état de la tâche d'impression. Doit inclure des informations supplémentaires si state < est arrêté ou aborted. Le champ sémantique_state fournit généralement une description plus appropriée et plus pertinente au client.
expires_in	int	Nombre de secondes pendant lesquelles cette tâche d'impression est valide.
type_tâche	chaîne	(Facultatif) Type de contenu du document envoyé.
taille_tâche	entier 64 bits	(Facultatif) Taille des données d'impression en octets.
nom_tâche	chaîne	(Facultatif) Nom de la tâche identique à celui saisi (le cas échéant).
id_tâche_serveur	chaîne	(Facultatif) ID de la tâche renvoyée par le serveur (si la tâche a été publiée dans le service Cloud Print). Omis pour l'impression hors connexion.
état_sémantique	JSON	(Facultatif) État sémantique de la tâche au format PrintJobState.

Exemple (impression via la création de rapports via Cloud Print):

{
        "job_id": "123",
        "state": "in_progress",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document",
        "server_job_id": "1111-2222-3333-4444"
}

Exemple (erreur d'impression hors connexion):

{
        "job_id": "123",
        "state": "stopped",
        "description": "Out of paper",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document"
}

Exemple (tâche d'impression annulée par l'utilisateur):

{
        "job_id": "123",
        "state": "aborted",
        "description": "User action",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document",
        "semantic_state": {
                "version": "1.0",
                "state": {
                        "type": "ABORTED",
                        "user_action_cause": {"action_code": "CANCELLED"}
                },
                "pages_printed": 7
        }
}

Exemple (la tâche d'impression s'est arrêtée, car il n'y a plus de papier). Notez la référence à l'état de l'appareil. Le client doit appeler l'API /privet/info pour obtenir plus de détails sur l'état de l'appareil:

{
        "job_id": "123",
        "state": "stopped",
        "description": "Out of paper",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": "123456",
        "job_name": "My PDF document",
        "semantic_state": {
                "version": "1.0",
                "state": {
                        "type": "STOPPED",
                        "device_state_cause": {"error_code": "INPUT_TRAY"}
                },
                "pages_printed": 7
        }
}

5.3.3. Erreurs

L'API /privet/printer/jobstate peut renvoyer les erreurs suivantes (pour plus d'informations, consultez la section "Erreurs"):

Error	Description
invalid_print_job [tâche_impression_incorrecte]	L'ID de tâche non valide/arrivé à expiration est spécifié dans la requête.
Erreur_du_serveur	Échec de l'obtention de l'état de la tâche d'impression (pour les tâches d'impression publiées sur Cloud Print).
invalide_x_privet_jeton	X-Privet-Token non valide ou vide dans la requête.

Si l'appareil n'expose pas l'attribut /privet/printer/jobstate, il DOIT renvoyer une erreur HTTP 404. Si l'en-tête X-Privet-Token est manquant, l'appareil DOIT renvoyer une erreur HTTP 400.

6. Annexe

6.1. Comportement et paramètres par défaut

Cette section explique le comportement par défaut attendu sur TOUS les appareils compatibles avec Privet.

Les appareils prêts à l'emploi ne doivent être compatibles qu'avec les API /privet/info et /privet/register. Toutes les autres API (par exemple, /privet/accesstoken, impression locale) doivent être désactivées.
L'enregistrement nécessite une interaction physique avec un appareil.

L'utilisateur DOIT effectuer une action physique sur l'appareil (par exemple, appuyer sur un bouton) pour confirmer son accès à l'appareil.
Une fois que l'utilisateur a effectué l'action indiquée ci-dessus, l'imprimante doit envoyer la requête /dashboard/register. Il ne doit envoyer cette requête qu'une fois l'action effectuée (voir le schéma de séquence 1).
Si l'appareil traite une requête /privet/register (par exemple, en attente de l'action ci-dessus), il doit refuser toutes les autres requêtes /privet/register. Dans ce cas, l'appareil DOIT renvoyer l'erreur device_occupation.
L'appareil doit suspendre les requêtes /register qui ne reçoivent pas l'action physique mentionnée ci-dessus dans les 60 secondes. Dans ce cas, l'appareil DOIT renvoyer l'erreur confirmation_timeout.
Facultatif: Recommandé, mais non obligatoires, les éléments suivants peuvent améliorer l'expérience utilisateur:

Il se peut que l'imprimante clignote en voyant ou en voyant l'écran, ce qui indique à l'utilisateur qu'une action est requise pour confirmer l'enregistrement.
L'imprimante peut indiquer à l'écran qu'elle est enregistrée auprès de Google Cloud Print pour l'utilisateur abc@def.com. Appuyez sur "OK" pour continuer. abc@def.com correspond au paramètre utilisateur de l'appel d'API /register. Cela permettrait aux utilisateurs de mieux comprendre:

c'est sa demande d'inscription
Que se passe-t-il s'il n'a pas déclenché la demande ?

En plus d'une action physique à confirmer sur l'imprimante (par exemple, "Appuyer sur le bouton OK"), une imprimante peut également proposer à l'utilisateur un bouton permettant d'annuler la demande (par exemple, "Annuler pour refuser"). Cela permettra aux utilisateurs qui n'ont pas déclenché la demande d'enregistrement de l'annuler avant l'expiration du délai de 60 secondes. Dans ce cas, l'appareil DOIT renvoyer l'erreur user_cancel.

Transferts de propriété:

L'appareil peut être supprimé explicitement du service Cloud.

Si l'appareil reçoit un message de réussite, mais qu'aucune description d'appareil n'a été obtenue à la suite d'un appel de l'interface /cloudkms/printer (pour GCP), il DOIT revenir au mode par défaut (prêt à l'emploi).
Si les identifiants de l'appareil ne fonctionnent plus (de façon explicite en raison de la réponse du serveur concernant les identifiants non valides), il DOIT revenir au mode par défaut (prêt à l'emploi).

Le rétablissement de la configuration d'usine locale DOIT effacer les identifiants de l'appareil et rétablir sa configuration par défaut.
Facultatif: L'appareil peut fournir un élément de menu pour effacer les identifiants et le définir en mode par défaut.

Les appareils compatibles avec les notifications XPPP DOIVENT inclure la possibilité de pinguer le serveur. Le délai d'expiration du ping DOIT être contrôlable depuis le serveur via "local_settings".
L'appareil ne peut pas pinguer le serveur de manière explicite (API / déclin/printer pour GCP, en plus des pings XPPP) qu'une fois par jour au maximum (24 heures) pour s'assurer de leur synchronisation. Nous vous recommandons de sélectionner de manière aléatoire la période de vérification dans les 24 à 32 heures.
Facultatif: Pour les appareils Cloud Print, il est recommandé, mais pas obligatoire, d'avoir un moyen (bouton) permettant à l'utilisateur de lancer une vérification pour les nouvelles tâches d'impression à partir de l'appareil. Certaines imprimantes en disposent déjà.
Facultatif. Les imprimantes d'entreprise peuvent avoir la possibilité de désactiver complètement la découverte locale. Dans ce cas, l'appareil DOIT mettre à jour ces paramètres locaux sur le serveur. Les nouveaux paramètres locaux DOIVENT être vides (la valeur "local_discovery" est définie sur "false"), ce qui signifie qu'ils peuvent être réactivés à partir du service GCP.

6.1.2 Schéma d'inscription par défaut

6.2. Attaques et prévention XSSI et XSRF

Cette section explique la possibilité d'attaques XSSI et XSRF sur l'appareil, ainsi que la manière de les protéger (y compris les techniques de génération de jetons).
Pour en savoir plus, consultez cette page : http://infoTypesecurity.blogspot.com/2011/05/website-security-for-webmasters.html
Normalement, les attaques XSSI et XSRF sont possibles lorsqu'un site utilise des mécanismes d'authentification par cookie. Bien que Google n'utilise pas de cookies avec le service Cloud Print, de telles attaques restent possibles. Par nature, l'accès au réseau local fait confiance aux requêtes de manière implicite.

6.2.1. XSSI

Un site Web malveillant peut deviner l'adresse IP et le numéro de port d'un appareil compatible avec Privet et essayer d'appeler l'API Privet à l'aide d'un tag &ltt;src=\"lt;api name>" dans un tag <script> :

<script type="text/javascript" src="http://192.168.1.42:8080/privet/info"></script>

Sans protection, les sites Web malveillants pourraient exécuter des appels d'API et accéder aux résultats.
Pour éviter ce type d'attaque, TOUS les appels d'API Privet DOIVENT nécessiter l'en-tête"X-Privet-Token"dans la requête. Les tags de script &srctlt;api>" ne peuvent pas ajouter des en-têtes et se protéger efficacement contre ce type d'attaque.

6.2.2. XSRF

http://en.wikipedia.org/wiki/Cross-site_request_forgery
Un site Web malveillant peut deviner l'adresse IP et le numéro de port d'un appareil compatible avec Privet, et essayer d'appeler l'API Privet à l'aide d'un formulaire de chargement <iframe>, ou de tout autre mécanisme de chargement sur plusieurs sites Web. Les pirates informatiques ne pourraient pas accéder aux résultats de la requête, mais ils pourraient la déclencher si celle-ci effectuait une action (par exemple, l'impression).

Pour éviter cette attaque, nous avons besoin de la protection suivante:

Laissez l'API /privet/info ouverte à XSRF
L'API /privet/info NE DOIT PAS effectuer d'actions sur l'appareil
Utilisez l'API /privet/info pour recevoir x-privet-token
Toutes les autres API DOIVENT rechercher un jeton x-privet-x valide dans l'en-tête "X-Privet-Token".
x-privet-token DOIT être valide pendant 24 heures seulement.

Même si un pirate informatique parvient à exécuter l'API /privet/info, il ne pourra pas lire le jeton x-privet-token à partir de la réponse, et il ne pourra donc pas appeler d'autre API.

Nous vous recommandons vivement de générer le jeton XSRF à l'aide de l'algorithme suivant:

XSRF_token = base64( SHA1(device_secret + DELIMITER + issue_timecounter) + DELIMITER + issue_timecounter )

Éléments de génération de jetons XSRF:

')}> est un caractère spécial, généralement ":".
issue_timecounter correspond à un nombre de secondes écoulées depuis un événement (époque pour l'horodatage) ou le temps de démarrage de l'appareil (pour les compteurs de processeur). issue_timecounter est en augmentation constante lorsque l'appareil est opérationnel (voir la vérification des jetons ci-dessous).
SHA1 : fonction de hachage avec l'algorithme SHA1
base64 : encodage base64
device_secret : code secret spécifique à l'appareil. Le code secret de l'appareil DOIT être mis à jour à chaque redémarrage.

Méthodes recommandées pour générer un code secret d'appareil:

Générer un nouvel UUID à chaque redémarrage
Générer un nombre aléatoire de 64 bits à chaque redémarrage

L'appareil n'est pas tenu de stocker tous les jetons XSRF qu'il a émis. Lorsque l'appareil doit valider la validité d'un jeton XSRF, il doit le décoder en base64. Obtenez le issue_timecounter à partir de la deuxième moitié (texte clair), et essayez de générer le hachage SHA1 de device_secret + + issue_timecounter, où issue_timecounter correspond au jeton. Si le nouveau SHA1 correspond à celui du jeton, l'appareil doit maintenant vérifier si issue_timecounter se situe dans la période de validité (24 heures) du compteur temporel actuel. Pour ce faire, l'appareil utilise le compteur de temps actuel (compteur de processeur, par exemple) et soustrait issue_timecounter. Le résultat DOIT être le nombre de secondes écoulées depuis l'émission du jeton.

Important : Il s'agit de la méthode recommandée pour mettre en œuvre la protection XSRF. Les clients de la spécification Privet ne doivent pas essayer de comprendre le jeton XSRF, mais plutôt comme une boîte noire. La Figure 6.2.3 illustre une méthode recommandée pour mettre en œuvre le jeton X-Privet et vérifier une requête type.

6.2.3 Schéma des séquences de vérification et de génération des jetons X-Privet

6.3. Schémas du workflow

Cette section illustre un workflow dans différents cas.

6.3.1. Workflow d'impression prêt à l'emploi

6.3.2. Démarrage de l'imprimante enregistrée

6.3.3 Workflow de gestion des notifications XMPP

6.3.4. Vérifier le workflow des paramètres de l'imprimante