Privet | Cloud Print | Développeurs Google – Bien choisir son serveur d impression

Privet est une API de découverte locale d'appareils de nuage utilisée par les services de nuage. Ce document est organisé   dans les sections suivantes:

Introduction: introduction à Privet Découverte: mécanismes de découverte locaux Annonces: annonces de découverte locale API: API Privet pour les périphériques cloud généraux API d'imprimante: API Privet utilisées par les imprimantes Annexe: schémas supplémentaires

1. Introduction Les appareils connectés au cloud présentent de nombreux avantages. Ils peuvent utiliser les services de conversion en ligne, le travail hôte   file d'attente lorsque l'appareil est hors ligne et accessible de partout dans le monde. Cependant, avec   nombreux périphériques accessibles par un utilisateur donné dans le cloud, nous devons fournir une méthode permettant de   appareil le plus proche en fonction de l'emplacement. Le protocole Privet a pour objectif de lier la flexibilité des   périphériques cloud avec un mécanisme de découverte local approprié, de sorte que les périphériques soient facilement découverts   nouveaux environnements. Les objectifs de ce protocole sont:

rendre les périphériques cloud détectables localement enregistrer des périphériques cloud avec un service cloud associer les appareils enregistrés à leur représentation dans le nuage activer la fonctionnalité hors ligne simplifier la mise en œuvre pour que les petits appareils puissent l'utiliser

Le protocole Privet comprend 2 parties principales: découverte et API. La découverte est utilisée pour trouver le   périphérique sur le réseau local, et l’API permet d’obtenir des informations sur le périphérique et   effectuer des actions. Tout au long de ce document, l'appareil désigne un appareil connecté au cloud   implémenter le protocole Privet. 2. découverte Discovery est un protocole basé sur zeroconf (mDNS + DNS-SD). Le périphérique DOIT implémenter IPv4 Link-Local   Adresser. L'appareil DOIT être conforme aux spécifications mDNS et DNS-SD. Le dispositif DOIT effectuer la résolution des conflits de noms conformément aux spécifications ci-dessus. 2.1. type de service La découverte de service DNS utilise le format suivant pour les types de service: _applicationprotocol._transportprotocol. Dans le cas du protocole Privet, le service   type pour DNS-SD devrait être: _privet._tcp L'appareil peut également implémenter d'autres types de services. Il est conseillé d'utiliser le même service   nom d'instance pour tous les types de services implémentés par le périphérique. Par exemple: une imprimante peut   implémentez les services "Imprimante XYZ._privet._tcp" et "Imprimante XYZ._printer._tcp". Ça va simplifier   configuration pour l'utilisateur. Cependant, les clients Privet rechercheront uniquement "_privet._tcp". En plus du type de service principal, l’appareil DOIT annoncer les enregistrements PTR pour ses   sous-type (s) correspondant (voir spéc. DNS-SD: "7.1. Énumération d'instances sélective (sous-types)").   Le format devrait être le suivant: _._sub.privet._tcp Actuellement, le seul sous-type de périphérique pris en charge est imprimante. Donc, toutes les imprimantes DOIVENT annoncer   deux enregistrements PTR:

_privet._tcp.local. _printer._sub._privet._tcp.local.

2.2. Enregistrement TXT le Découverte du service DNS définit des champs pour ajouter des informations facultatives sur un service dans   les enregistrements TXT. Un enregistrement TXT est constitué de paires clé / valeur. Chaque paire clé / valeur commence à partir du   longueur octet suivi de 255 octets de texte au maximum. La clé est le texte avant le premier   Le caractère "=" et la valeur correspond au texte après le premier caractère "="   jusqu'à la fin. La spécification ne permet aucune valeur dans l'enregistrement, dans ce cas, il n'y aura aucune   Caractère "=" OU pas de texte après le caractère "=". (Voir spéc. DNS-SD:   "6.1. Règles générales de format pour les enregistrements DNS TXT" pour le format d'enregistrement DNS TXT et "6.2. DNS-SD TXT   Taille d'enregistrement "pour la longueur recommandée). Privet exige que le périphérique envoie les paires clé / valeur suivantes dans l'enregistrement TXT. Valeur clé   les chaînes ne respectent pas la casse, par exemple "CS = online" et "cs = ONLINE" sont   le même. Les informations contenues dans l'enregistrement TXT DOIVENT être identiques à celles accessibles via l'API / info (voir 4.1.   Section API). Il est recommandé de conserver une taille d’enregistrement TXT inférieure à 512 octets. 2.2.1. txtvers Version de la structure TXT. txtvers DOIT être le premier enregistrement de la structure TXT. Actuellement   la seule version supportée est 1. txtvers = 1 2.2.2. ty Fournit un nom lisible par l'utilisateur du périphérique. Par exemple: ty = Modèle d'imprimante Google Cloud Ready XYZ 2.2.3. note (optionnel) Fournit un nom lisible par l'utilisateur du périphérique. Par exemple: note = Imprimeur de lobby au 1er étage Remarque: Ceci est une clé optionnelle et peut être ignorée. Cependant, si présent, l'utilisateur   DEVRAIT pouvoir modifier cette valeur. La même description DOIT être utilisée lors de l'enregistrement d'un appareil. 2.2.4. url URL du serveur auquel cet appareil est connecté (protocole compris). Par exemple: url = https: //www.google.com/cloudprint 2.2.5. type Liste de sous-types de périphérique pris en charge par ce périphérique, séparés par des virgules. Le format est:   "type = _subtype1, _subtype2". Actuellement, le seul sous-type de périphérique pris en charge est imprimante. type = imprimante Chaque sous-type répertorié doit être annoncé à l'aide d'un enregistrement PTR correspondant. Pour chaque supporté   service, il doit y avoir un élément correspondant. Nom du sous-type de service   (._sub.privet._tcp) devrait être égal au type de périphérique ici. 2.2.6. identifiant Reference de l'appareil. Si le périphérique n'a pas encore été enregistré, cette clé doit être présente, mais la valeur   devrait être vide. Par exemple:

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

2.2.7. cs Indique l’état actuel de la connexion du périphérique. Quatre valeurs possibles sont définies dans cette   spec.

"online" indique que l'appareil est actuellement connecté au cloud. "hors ligne" indique que le périphérique est disponible sur le réseau local, mais     ne peux pas parler au serveur. "connexion" indique que le périphérique effectue sa séquence de démarrage et est en train de     pas encore complètement en ligne. "non configuré" indique que l'accès Internet de l'appareil n'a pas été     configuré pour le moment. Cette valeur n’est pas utilisée actuellement, mais peut être utile dans les futures versions du logiciel.     spécification.

Par exemple:

cs = en ligne cs = hors ligne cs = connexion

Si le périphérique a été enregistré dans un nuage, il doit vérifier au démarrage la connectivité avec   serveur pour détecter son état de connexion (par exemple, appeler une API cloud pour obtenir les paramètres du périphérique). le   L’équipement peut utiliser l’état de la connexion de son canal de notification (XMPP, par exemple) pour signaler cette valeur.   Les périphériques non enregistrés au démarrage peuvent envoyer un ping à un domaine afin de détecter leur état de connexion (par exemple,   exemple, effectuez un ping sur www.google.com pour les périphériques d’impression dans le cloud 3. Annonces Au démarrage, à l'arrêt ou au changement d'état du périphérique, le périphérique DOIT exécuter l'étape de l'annonce   décrit dans la spécification mDNS. Il   DEVRAIT envoyer l'annonce correspondante au moins deux fois avec un intervalle d'au moins une seconde   entre eux. 3.1. Commencez Au démarrage de l'appareil, il DOIT exécuter les étapes de vérification et d'annonce décrites dans le manuel mDNS.   spécification. Les enregistrements SRV, PTR et TXT doivent être envoyés dans ce cas. Il est recommandé de grouper   tous les enregistrements dans une réponse DNS si possible. Si non, l'ordre suivant est recommandé: SRV,   PTR, enregistrements TXT. 3.2. Fermer Lors de l’arrêt de l’appareil, il DEVRAIT essayer d’en informer toutes les parties intéressées en envoyant un message.   "Au revoir paquet" avec TTL = 0 (comme décrit dans la documentation de mDNS). 3.3. Mise à jour Si l’une des informations décrites dans TXT a changé, le périphérique DOIT envoyer une mise à jour.   annonce. Dans ce cas, il suffit d’envoyer le nouvel enregistrement TXT. Par exemple, après un   appareil est enregistré, il DOIT envoyer une annonce de mise à jour incluant le nouvel identifiant d'appareil. 4. API Une fois qu'un périphérique cloud a été découvert, la communication client est activée avec le périphérique.   directement sur le réseau local. Toutes les API sont basées sur HTTP 1.1. Les formats de données sont basés sur JSON. API   les requêtes peuvent être des requêtes GET ou POST. Chaque demande DOIT contenir un "X-Privet-Token"en-tête. La SEULE demande   autorisé à avoir un en-tête "X-Privet-Token" vide est la requête / privet / info (note   l'en-tête DOIT toujours être présent). Si l'en-tête "X-Privet-Token" est manquant, le   le périphérique DOIT répondre avec l'erreur HTTP 400 suivante: HTTP / 1.1 400 En-tête X-Privet-Token manquant. Si l'en-tête "X-Privet-Token" est vide ou invalide, le périphérique DOIT répondre avec   "erreur X-Privet-Token non valide" (invalid_x_privet_token, voir la section Erreurs pour plus de détails).   détails). La seule exception est l'API / info. Pour voir plus d'informations sur pourquoi cela est fait et comment les jetons   voir Annexe A: Attaques XSSI et XSRF et prévention. Si une API demandée n'existe pas ou n'est pas prise en charge, le périphérique DOIT renvoyer une erreur HTTP 404. 4.1. Disponibilité de l'API Avant TOUTE API ne soit exposée (y compris l’API / info), le périphérique DOIT contacter le serveur pour vérifier   paramètres locaux. Les paramètres locaux DOIVENT être préservés entre   redémarre. Si le serveur n'est pas disponible, les derniers paramètres locaux connus doivent être utilisés. Si la   L'appareil n'a pas encore été enregistré, il devrait suivre les paramètres par défaut. Les périphériques Cloud Print DOIVENT suivre les étapes ci-dessous pour enregistrer, recevoir et mettre à jour les paramètres locaux. 4.1.1. enregistrement Lorsque le périphérique s'inscrit, il DOIT spécifier le paramètre "local_settings", comme suit:

       "actuel":                 "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 La description

découverte_locale booléen Indique si la fonctionnalité de découverte locale est     permis. Si "false", toutes les découvertes d'API locale (y compris / info) et DNS-SD doivent être désactivées. Par     Par défaut, les périphériques nouvellement enregistrés doivent passer "true".

access_token_enabled booléen (optionnel) Indique si / accesstoken API     devrait être exposé sur le réseau local. Par défaut devrait être "true".

printer / local_printing_enabled booléen (optionnel) Indique si local     la fonctionnalité d’impression (/ printer / createjob, / printer / submitdoc, / printer / jobstate) devrait être     exposés sur le réseau local. Par défaut devrait être "true".

printer / conversion_printing_enabled booléen (optionnel) Indique si local     l'impression peut envoyer le travail au serveur pour la conversion. Cela n’a de sens que lorsque l’impression locale est activée.

xmpp_timeout_value int (facultatif) Indique le nombre de secondes entre     Pingles de canal XMPP. Par défaut, DOIT être 300 (5 minutes) ou plus.

Important: L’absence de valeur optionnelle indique que le   la fonctionnalité correspondante est complètement non prise en charge par le périphérique. 4.1.2. Commencez Au démarrage du périphérique, le serveur doit contacter le serveur pour vérifier quelles API sont disponibles pour être exposées dans   le réseau local. Pour les imprimantes connectées à Cloud Print, elles doivent appeler: / cloudprint / printer? printerid = ou / cloudprint / list / cloudprint / printer est préférable à / cloudprint / list, mais les deux fonctionneront. Cette API renvoie les paramètres actuels du périphérique, y compris les paramètres de l'API locale. La réponse du   Le serveur aura le format suivant:

"paramètres locaux":         "actuel":                 "local_discovery": true,                 "access_token_enabled": true,                 "printer / local_printing_enabled": true,                 "printer / conversion_printing_enabled": true,                 "xmpp_timeout_value": 300          ,          "en attente":                 "local_discovery": true,                 "access_token_enabled": true,                 "printer / local_printing_enabled": false,                 "printer / conversion_printing_enabled": false,                 "xmpp_timeout_value": 500          

L'objet "en cours" indique les paramètres en vigueur pour le moment. L'objet "en attente" indique les paramètres à appliquer au périphérique (cet objet   peut être manquant). Une fois que le périphérique voit les paramètres "en attente", il DOIT mettre à jour son état (voir ci-dessous). 4.1.3. Mise à jour Si une mise à jour des paramètres est nécessaire, une notification XMPP sera envoyée au périphérique. La notification   sera dans le format suivant: /mettre à jour les paramètres À la réception d'une telle notification, le périphérique DOIT interroger le serveur pour obtenir les derniers paramètres.   Les périphériques Cloud Print DOIVENT utiliser: / cloudprint / printer? printerid = Une fois que le périphérique voit la section "en attente" suite à l’API / cloudprint / printer (à   démarrage ou en raison de la notification), il DOIT mettre à jour son état interne pour se souvenir du nouveau   paramètres. Il DOIT appeler l'API du serveur pour confirmer les nouveaux paramètres. Pour les imprimantes en nuage, le périphérique   DOIT appeler / cloudprint / update API et utiliser le paramètre "local_settings" comme pendant   enregistrement. Lors de la reconnexion au canal XMPP, le périphérique DOIT appeler / cloudprint / API 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 Le paramètre "local_settings" utilisé par le périphérique pour appeler l'API du serveur NE DOIT JAMAIS contenir   section "en attente". 4.1.3.2. Paramètres locaux actuels UNIQUEMENT l’appareil peut changer la section "actuelle" des "paramètres locaux".   Tout le monde changera la section "en attente" et attendra que les modifications soient apportées.   propagé à la section "en cours" par le périphérique. 4.1.4. Hors ligne Lorsqu'il est impossible de contacter le serveur au démarrage, après notification, le périphérique DOIT utiliser le dernier   paramètres locaux. 4.1.5. Suppression de l'appareil du service Si le périphérique a été supprimé du service (GCP par exemple), une notification XMPP sera envoyée.   envoyé à l'appareil. La notification sera au format suivant: /effacer À la réception d'une telle notification, le périphérique DOIT se rendre sur le serveur pour vérifier son état. Nuage   Les périphériques d’impression DOIVENT utiliser: / cloudprint / printer? printerid = Le périphérique DOIT recevoir une réponse HTTP réussie avec success = false et aucun périphérique / imprimante.   la description. Cela signifie que le périphérique a été retiré du serveur et que le périphérique DOIT effacer ses   informations d’authentification et passer en mode de paramètres d’usine par défaut. TOUTE heure à laquelle le périphérique reçoit une réponse indiquant qu'il a été supprimé à la suite de la   / cloudprint / API (démarrage, notification des paramètres de mise à jour, ping quotidien), elle DOIT supprimer ses   informations d'identification et aller en mode par défaut. 4.2. API / privet / info L'info API est OBLIGATOIRE et DOIT être implémentée par tous les appareils. C'est 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 périphérique et les fonctionnalités qu'il prend en charge. Cette API   NE DOIT jamais changer l’état du dispositif ni effectuer aucune action, car il est vulnérable aux attaques XSRF.   C'est la SEULE API autorisée à avoir un en-tête "X-Privet-Token" vide. Les clients devraient   API call / privet / info avec en-tête "X-Privet-Token" définie sur X-Privet-Token:   "" L'API info DOIT renvoyer des données cohérentes avec les données disponibles dans l'enregistrement TXT lors de la découverte. 4.2.1. Contribution / privet / info L'API n'a pas de paramètre d'entrée. 4.2.2. Revenir L'API / privet / info renvoie des informations de base sur le périphérique et les fonctionnalités prises en charge. La colonne TXT indique le champ correspondant dans l’enregistrement DNS-SD TXT.

Nom de la valeur Type de valeur La description SMS

version chaîne Version la plus récente (major.minor) de l'API prise en charge, actuellement     1,0

Nom chaîne Nom lisible par l'homme du périphérique. ty

la description chaîne (facultatif) Description de l'appareil. DEVRAIT être modifiable par     utilisateur. Remarque

url chaîne URL du serveur avec lequel cet appareil parle. L'URL DOIT inclure     spécification du protocole, par exemple: https://www.google.com/cloudprint. url

type liste de chaînes Liste des types d'appareils pris en charge. type

identifiant chaîne Identifiant de périphérique, vide si le périphérique n'a pas encore été enregistré. identifiant

état_périphérique chaîne Etat de l'appareil.tourner au ralenti signifie que l'appareil est     prêtEn traitement signifie que le périphérique 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 que l'intervention de l'utilisateur est requise

état_connexion chaîne Etat de la connexion au serveur (base_url) en ligne – connexion disponible hors ligne – pas de connection de liaison – effectuer les étapes de démarrage pas configuré – la connexion n'a pas encore été configurée Un périphérique enregistré peut signaler son état de connexion en fonction de l'état de la notification.     canal (par exemple, l'état de la connexion XMPP). 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, cela DOIT être     un UUID. (Spec GCP 1.1) (facultatif) Nous vous recommandons vivement d’utiliser le même identifiant de numéro de série partout, donc différent.     les clients peuvent identifier le même appareil. Par exemple, les imprimeurs implémentant IPP peuvent utiliser cette interface série.     numéro d'identification dans le champ "printer-device-id".

firmware chaîne Version du firmware de l'appareil

la disponibilité int Nombre de secondes à partir du démarrage du périphérique.

setup_url chaîne (facultatif) URL (protocole compris) de la page avec     instructions d'installation

support_url chaîne (facultatif) URL (protocole compris) de la page avec     support, informations FAQ

update_url chaîne (facultatif) URL (protocole compris) de la page avec     mettre à jour les instructions du firmware

x-privet-token chaîne Valeur de la X-Privet-Token en-tête qui a     à transmettre à toutes les API pour empêcher les attaques XSSI et XSRF. Voir 6.1. pour plus de détails.

api description des API Liste des API prises en charge (décrites ci-dessous)

état sémantique JSON (facultatif) Etat sémantique de l'appareil en     Format CloudDeviceState.

api – est une liste JSON contenant la liste des API disponibles via le réseau local. Remarque   toutes les API ne sont peut-être pas disponibles simultanément sur le réseau local. Par exemple, un nouveau   L'appareil connecté ne doit supporter que l'API / Register:

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

Une fois l'enregistrement de l'appareil terminé, l'appareil DEVRAIT cesser de prendre en charge l'API / register. le Le périphérique doit également vérifier auprès du service afin de déterminer quelles API peuvent être exposées sur le serveur local. réseau. Par exemple:

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

Les API suivantes sont disponibles à ce moment:

/ privet / register – API pour l'enregistrement de périphérique sur le réseau local. (voir     / privet / register API pour plus de détails). Cette API DOIT être cachée une fois le périphérique réussi.     enregistré dans le nuage. / privet / accesstoken – API permettant de demander un jeton d’accès à l’appareil (voir     / privet / accesstoken API pour plus de détails). / privet / capacités – API permettant de récupérer les capacités du périphérique (voir / privet / capacités     API pour plus de détails). / privet / printer / * – API spécifique au type de périphérique "imprimante", voir imprimante     API spécifiques pour plus de détails.

Voici un exemple de réponse / privet / info. (Notez le manque de l’API / privet / register, car ce périphérique est déjà enregistré):

        "version": "1.0",         "name": "l’imprimante de Gene",         "description": "Imprimante connectée via un connecteur Chrome",         "url": "https://www.google.com/cloudprint",         "type": [ "printer" ],         "id": "11111111-2222-3333-4444-555555555555",         "device_state": "inactif",         "connection_state": "en ligne",         "fabricant": "Google",         "modèle": "Google Chrome",         "numéro de série": "1111-22222-33333-4444",         "firmware": "24.0.1312.52",         "disponibilité": 600,         "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=fr",         "support_url": "http://support.google.com/cloudprint/?hl=fr",         "update_url": "http://support.google.com/cloudprint/?hl=fr",         "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 (avis   état de sémantique):

{         "version": "1.0",         "name": "l’imprimante de Gene",         "description": "Imprimante connectée via un connecteur Chrome",         "url": "https://www.google.com/cloudprint",         "type": [ "printer" ],         "id": "11111111-2222-3333-4444-555555555555",         "device_state": "stoppé",         "connection_state": "en ligne",         "fabricant": "Google",         "modèle": "Google Chrome",         "numéro de série": "1111-22222-33333-4444",         "firmware": "24.0.1312.52",         "disponibilité": 600,         "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=fr",         "support_url": "http://support.google.com/cloudprint/?hl=fr",         "update_url": "http://support.google.com/cloudprint/?hl=fr",         "x-privet-token": "AIp06DjQd80yMoGYuGmT_VDAApuBZbInsQ: 1358377509659",         "api": [ "/privet/accesstoken", "/privet/capabilities", "/privet/printer/submitdoc", ],         "état sémantique":                 "version": "1.0",                 "imprimante":                         "state": "STOPPED",                         "marker_state":                                 "article": [ "vendor_id": "ink", "state": "EXHAUSTED", "level_percent": 0 ]                           }

4.2.3. les erreurs / privet / info API devrait SEULEMENT renvoyer une erreur si X-Privet-Token l'en-tête est manquant. Il   DOIT être une erreur HTTP 400: HTTP / 1.1 400 En-tête X-Privet-Token manquant. 4.3. / privet / register API / privet / register est facultative. C'est une requête HTTP POST. / privet / register API DOIT vérifier   pour une validité X-Privet-Token entête. Le périphérique DOIT implémenter 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 UNIQUEMENT lorsqu’il autorise l’enregistrement anonyme à la   moment. Par exemple:

Lorsque le périphérique est allumé (ou après avoir cliqué sur un bouton spécial du périphérique) et n’a pas     été enregistré, il devrait exposer l’API / privet / register pour permettre à un utilisateur du répertoire local     réseau pour réclamer l’imprimante. Une fois l’enregistrement terminé, le périphérique doit cesser d’exposer l’API / privet / register à     empêcher un autre utilisateur du réseau local de récupérer le périphérique. Certains appareils peuvent avoir différentes façons d’enregistrer des appareils et ne doivent pas exposer le     / privet / register à tous (par exemple, le connecteur Chrome Cloud Print).

Le processus d’enregistrement se déroule en 3 étapes (voir Enregistrement anonyme pour Cloud Print).

Lancer le processus d'inscription anonyme. Un client initie ce processus en appelant l'API / privet / register. L'appareil peut attendre     confirmation de l'utilisateur à ce moment. Obtenez le jeton de réclamation.

Le client interroge pour savoir quand l'appareil est prêt à continuer. Une fois que l'appareil est prêt, il   envoie une demande au serveur pour récupérer le jeton d'enregistrement et l'URL d'inscription. Jeton reçu   et URL DEVRAIT être retourné au client. Au cours de cette étape, si le périphérique reçoit un autre appel pour   initialiser l'enregistrement, il devrait:

Si c’est le même utilisateur qui a commencé l’enregistrement, supprimez toutes les données précédentes (le cas échéant) et démarrez le système.     un nouveau processus d'inscription. S'il s'agit d'un utilisateur différent, retourne une erreur device_busy et un délai d'attente de 30 secondes.

Processus d'inscription complet. Une fois que le client a réclamé le périphérique, il doit lui notifier son achèvement.   enregistrement. Une fois le processus d'enregistrement terminé, l'appareil doit envoyer une mise à jour.   annonce, y compris l'ID de périphérique nouvellement acquis. Remarque: lorsque le périphérique traite un appel d'API / privet / register, aucune autre API / privet / register   les appels peuvent être traités simultanément. Le périphérique DOIT retourner l'erreur device_busy et 30 secondes   temps libre. La confirmation de l'utilisateur pour l'enregistrement sur l'appareil est fortement recommandée. Si mis en œuvre, le   le périphérique DOIT attendre la confirmation de l'utilisateur APRÈS qu'il reçoive un / privet / register? action = start API   appel. Le client appellera / privet / register? Action = getClaimToken pour savoir quand   la confirmation de l'utilisateur est terminée et le jeton de réclamation est disponible. Si l'utilisateur annule son inscription le   l'appareil (par exemple, appuie sur le bouton Annuler), l'erreur user_cancel DOIT être renvoyée. Si l'utilisateur   l’enregistrement n’a pas été confirmé dans un certain délai, l’erreur confirmation_timeout DOIT être   revenu. Voir la section des valeurs par défaut pour plus de détails. 4.3.1. Contribution L'API / privet / register a les paramètres d'entrée suivants:

Nom Valeur

action Peut être l'un des suivants: début – pour commencer le processus d'inscription getClaimToken – récupérer le jeton de réclamation pour le périphérique Annuler – annuler le processus d'inscription Achevée – terminer le processus d'inscription

utilisateur Email de l'utilisateur qui réclamera cet appareil.

Le périphérique DOIT vérifier que l’adresse électronique de toutes les actions (start, getClaimToken, annuler,   complète) correspond. 4.3.2. Revenir L'API / privet / register renvoie les données suivantes:

Nom de la valeur Type de valeur La description

action chaîne Même action que dans le paramètre d'entrée.

utilisateur chaîne (optionnel) Même utilisateur que dans le paramètre d'entrée (peut être manquant, si     omis dans l'entrée).

jeton chaîne (optionnel) Jeton d'inscription (obligatoire pour     Réponse "getClaimToken", omise pour "démarrer", "complète", "annuler").

claim_url chaîne (optionnel) URL d'enregistrement (obligatoire pour     Réponse "getClaimToken", omise pour "démarrer", "complète", "annuler"). Pour les imprimantes en nuage, il faut     être "complete_invite_url" reçu du serveur.

automation_claim_url chaîne (optionnel) URL d'enregistrement (obligatoire pour     Réponse "getClaimToken", omise pour "démarrer", "complète", "annuler"). Pour les imprimantes en nuage, il faut     être "automatic_invite_url" reçu du serveur.

Reference de l'appareil chaîne (optionnel) Nouvel identifiant d'appareil (omis pour la réponse "start",     obligatoire pour "complet").

Le périphérique DOIT retourner son identifiant de périphérique dans la réponse de l'API / privet / info UNIQUEMENT après l'enregistrement.   Achevée. Exemple 1:

        "action": "start",         "utilisateur": "utilisateur@domaine.com",

Exemple 2:

        "action": "getClaimToken",         "utilisateur": "utilisateur@domaine.com",         "jeton": "AAA111222333444555666777",         "claim_url": "https://domain.com/SoMeUrL",

Exemple 3:

        "action": "complet",         "utilisateur": "utilisateur@domaine.com",         "device_id": "11111111-2222-3333-4444-555555555555",

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

Erreur La description

device_busy Le périphérique est occupé et ne peut pas effectuer l’action demandée. Recommencez     après timeout.

waiting_user_action En réponse à "getClaimToken", cette erreur indique que le     le périphérique est toujours en attente de confirmation de l'utilisateur, et la requête "getClaimToken" doit être réessayée après     temps libre.

user_cancel L'utilisateur a explicitement annulé le processus d'inscription depuis l'appareil.

confirmation_timeout La confirmation de l'utilisateur expire.

invalide_action Une action invalide est appelée. Par exemple, si le client appelé     action = terminé avant d'appeler action = start et action = getClaimToken.

parent_invalide Paramètres non valides spécifiés dans la demande. (Paramètres inconnus     doit être ignoré pour une compatibilité future). Par exemple, renvoyez ceci si le client     appelé action = inconnu ou utilisateur =.

device_config_error La date / heure (ou certains autres paramètres) est incorrecte sur l'appareil     côté. L'utilisateur doit aller (sur le site Web interne du périphérique) et configurer les paramètres du périphérique.

hors ligne L’appareil est actuellement hors ligne et ne peut pas communiquer avec le serveur.

erreur du serveur Erreur du serveur pendant le processus d'inscription.

invalid_x_privet_token X-Privet-Token est invalide ou vide dans la requête.

Le périphérique DOIT cesser d’exposer l’API / privet / register une fois l’enregistrement effectué avec succès.   terminé. Si le périphérique n'expose pas l'API / privet / register, il DOIT renvoyer l'erreur HTTP 404.   Par conséquent, si un périphérique est déjà enregistré, l'appel de cette API DOIT renvoyer 404. Si le   L'en-tête X-Privet-Token est manquant, le périphérique DOIT renvoyer l'erreur HTTP 400. 4.4. / privet / accesstoken API / privet / accesstoken API est FACULTATIF. C'est une requête HTTP GET. / privet / accesstoken API DOIT vérifier pour un en-tête "X-Privet-Token" valide. Le périphérique DOIT implémenter cette API sur le "/ privet / accesstoken" url: GET / privet / accesstoken HTTP / 1.1 Lorsque le périphérique reçoit l'appel de l'API / accesstoken, il doit appeler le serveur pour récupérer le   jeton d'accès pour l'utilisateur donné et renvoyer le jeton au client. Le client utilisera ensuite le   jeton d'accès pour accéder à cet appareil via le cloud. Les périphériques Cloud Print DOIVENT appeler l'API suivante: / cloudprint / proximitétoken et passez les paramètres "printerid =" et "user" du local API. En cas de succès, la réponse du serveur contiendra l'objet suivant:

"proximité_token":         "utilisateur": "utilisateur@domaine.com",         "jeton": "AAA111222333444555666777",         "expires_in": 600

Les périphériques Cloud Print DOIVENT transmettre la valeur de l’objet "proximité_token" dans la réponse. aux appels d’API locaux / privet / accesstoken. Il est plus avantageux (à l’avenir) que l’appareil puisse passe TOUS les paramètres (y compris ceux qui ne sont pas décrits dans cette spécification). 4.4.1. Contribution L'API / privet / accesstoken a les paramètres d'entrée suivants:

Nom Valeur

utilisateur Email de l'utilisateur qui a eu l'intention d'utiliser ce jeton d'accès. Peut être vide dans le     demande.

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

Nom de la valeur Type de valeur La description

jeton chaîne Jeton d'accès renvoyé par le serveur

utilisateur chaîne Même utilisateur que dans le paramètre d'entrée.

expire dans int Nombre de secondes jusqu'à l'expiration de ce jeton. Reçu de     le serveur et passé dans cette réponse.

Exemple:

        "jeton": "AAA111222333444555666777",         "utilisateur": "utilisateur@domaine.com",         "expires_in": 600

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

Erreur La description

hors ligne L'appareil est actuellement hors ligne et ne peut pas parler au serveur.

accès refusé Droits insuffisants. Accès refusé. L'appareil doit renvoyer cette     erreur lorsque la demande a été explicitement refusée par le serveur.

parent_invalide Paramètres non valides spécifiés dans la demande. (Paramètres inconnus     doit être ignoré pour une compatibilité future). Par exemple, si le client appelé     / accesstoken? user = ou / accesstoken.

erreur du serveur Erreur du serveur.

invalid_x_privet_token X-Privet-Token est invalide ou vide dans la demande.

Si le périphérique n'expose pas l'API / privet / accesstoken, il DOIT renvoyer l'erreur HTTP 404. Si la   L'en-tête X-Privet-Token est manquant, le périphérique DOIT renvoyer l'erreur HTTP 400. 4.5 / privet / API de capacités / privet / features est facultatif. C'est une requête HTTP GET. / privet / functions API DOIT vérifier pour un en-tête "X-Privet-Token" valide. Le périphérique DOIT implémenter cette API sur URL "/ privet / capacités": GET / privet / capacités HTTP / 1.1 Lorsque le périphérique reçoit / appel de l'API de fonctionnalités, si le périphérique est capable, il DEVRAIT contacter le serveur pour obtenir des capacités mises à jour. Par exemple, si une imprimante prend en charge la publication d'un travail d'impression (reçu localement) à travers le service Cloud Print, il devrait renvoyer les fonctionnalités que le Le service d'impression en nuage reviendrait. Cloud Print dans ce cas peut altérer l'imprimante d'origine fonctions en ajoutant de nouvelles fonctionnalités avant d’envoyer le travail à l’imprimante. Le plus Le cas courant est une liste de types de documents pris en charge. Si l'imprimante est hors ligne, elle devrait renvoyer types de documents qu'il prend en charge. Cependant, si l'imprimante est en ligne et enregistrée auprès de Cloud Print it DOIT retourner "* / *" parmi les types pris en charge. Le service Cloud Print sera exécuté la conversion nécessaire dans ce cas. Pour l’impression hors ligne, l’imprimante DOIT prendre en charge au moins la format "image / pwg-raster". 4.5.1. Contribution L'API / privet / functions a les paramètres d'entrée suivants:

Nom Valeur

hors ligne (facultatif) Ne peut être que "hors ligne = 1". Dans ce cas, l'appareil doit retourner     capacités pour une utilisation hors connexion (si elles sont différentes des capacités "en ligne").

4.5.2. Revenir L'API / privet / features renvoie les fonctionnalités de périphérique dans le fichier JSON CDD (Cloud Device Description) format (voir le document CDD pour plus de détails). Les imprimantes au minimum DOIVENT renvoyer une liste des types pris en charge ici. Par exemple, une imprimante Cloud Ready actuellement en ligne peut renvoyer quelque chose comme ceci (à le minimum):

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

et quand il est déconnecté du serveur, il peut retourner:

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

Remarque: Les imprimantes expriment la priorité du type de contenu pris en charge en utilisant la commande. Pour   Par exemple, dans les exemples ci-dessus, l’imprimante indique qu’elle préfère les données "application / pdf" à   "image / pwg-raster" et "image / jpeg". Les clients doivent respecter les priorités des imprimantes si possible   (voir le document CDD pour plus de détails). 4.5.3. les erreurs L'API / privet / features peut renvoyer les erreurs suivantes (voir la section Erreurs pour plus de détails):

Erreur La description

invalid_x_privet_token X-Privet-Token est invalide ou vide dans la requête.

Si le périphérique n'expose pas l'API / privet / features, il DOIT renvoyer HTTP 404.   Erreur. Si l'en-tête X-Privet-Token est manquant, le périphérique DOIT renvoyer une erreur HTTP 400. 4.6. les erreurs Les erreurs sont renvoyées par les API ci-dessus au format suivant:

Nom de la valeur Type de valeur La description

Erreur chaîne Type d'erreur (défini par API)

la description chaîne (optionnel) Description lisible par l'homme de l'erreur.

server_api chaîne (optionnel) En cas d'erreur de serveur, ce champ contient     l'API du serveur qui a échoué.

code_serveur int (facultatif) En cas d'erreur de serveur, ce champ contient     ce code d'erreur que le serveur a renvoyé.

code_http_serveur int (facultatif) En cas d'erreur HTTP du serveur, ce champ     contient le code d'erreur HTTP serveur renvoyé.

temps libre int (facultatif) Nombre de secondes que le client attend avant     nouvelle tentative (pour les erreurs récupérables uniquement). Le client DOIT randomiser le délai d’expiration réel de cette valeur sur     une valeur de + 20%.

Toutes les API DOIVENT renvoyer une erreur HTTP 400 si l'en-tête X-Privet-Token est manquant. HTTP / 1.1 400 En-tête X-Privet-Token manquant. Exemple 1:

        "erreur": "erreur_serveur",         "description": "Service indisponible",         "server_api": "/ submit",         "code_http_serveur": 503

Exemple 2:

        "error": "printer_busy",         "description": "L'imprimante est en train d'imprimer un autre travail",         "timeout": 15

5. API d'imprimante L'un des types de périphérique pris en charge par ce protocole est le type imprimante. Les appareils supportant ce type PEUVENT   implémenter certaines fonctionnalités spécifiques aux imprimantes. Idéalement, l’impression sur des imprimantes prêtes au cloud   passer par un serveur Cloud Print:

Dans certains cas, un client peut avoir besoin d’envoyer un document localement. Cela peut être nécessaire lorsque le client ne le fait pas   avoir un identifiant Google ou est incapable de parler au serveur Cloud Print. Dans ce cas, le travail d'impression sera   être soumis localement à l'imprimante. L’imprimante utilisera à son tour le service Cloud Print pour   mise en file d'attente et conversion. L’imprimante republiera le travail soumis localement sur le Cloud. Print   service, puis demandez-le, car il a été envoyé via le cloud. Ce processus fournira une   expérience utilisateur flexible en termes de service (conversion) et de gestion / suivi des travaux d'impression.

Since the Cloud Print service implements conversion, the printer SHOULD advertise supporting all   input formats ("*/*") among the list of the supported content types:

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

In some cases a completely offline solution is desired. Since printers support a limited number   of input formats, a client will need to convert documents to a few natively supported printer   formats.

This spec REQUIRES all printers to support at least the PWG Raster ("image/pwg-raster") format   for the offline printing case. A printer may support other formats (for example JPEG) and if a   client supports it, it may send documents in that format. The printer MUST expose supported types   through the /capabilities API, for example:

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

There are two ways a client may initiate printing over the local network. Simple printing – client sends the document over the local network to /submitdoc API   (without specifying the job_id parameter). The submitted document will be printed using default   print ticket settings and no print job statuses are needed. If the printer ONLY supports this type   of printing, it MUST advertise ONLY /submitdoc API in the /privet/info API response.

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

Advanced printing – client should first create a print job on the printer by calling the /privet/printer/createjob API with a valid CJT job ticket in the request. The printer   MUST store the print ticket in memory and return a job_id back to the client. Then the client will   call the /printer/submitdoc API and specify the previously received job_id. At that time   the printer will start printing. The client will poll the printer for print job status by calling   le /privet/printer/jobstate API. In a multi-client environment, there is no guarantee how this API is called. It is possible for   one client to call /createjob between another client’s /createjob->/submitdoc   calls. To eliminate possible deadlocks and improve usability, we recommended having a small queue   of pending print jobs on the printer (at least 3-5):

/createjob takes the first available spot in the queue. Job lifetime (in the queue) is at least 5 minutes. If all spots in the queue are taken, then the oldest, non-printing job shall be removed and a     new one will be placed there. If there is a print job currently printing on the device (simple or advanced printing), /submitdoc should return status busy and propose a timeout to retry this print job. Si /submitdoc refers to a job that has been removed from the queue (due to     replacement or timeout), the printer should return an error invalid_print_job et le     client will retry the process from the /createjob step. The client MUST wait for a     random timeout period of up to 5 seconds before retrying.

If memory constraints prevent storing multiple pending jobs on the device, it is possible to have   a queue of 1 print job long. It should still follow the same protocol as above. After a job has   completed or failed with an error, the printer should store information about the job’s   status for at least 5 minutes. The queue size for storing completed job statuses should be at   least 10. If there are more job statuses that need to be stored, the oldest one may be removed   from the queue before the 5 minute timeout. Remarque: For now clients will poll for job status. In the future, we may require   the printer to send TXT DNS notification when ANY print job status has changed. 5.1. /privet/printer/createjob API /privet/printer/createjob API is OPTIONAL (see Simple Printing above). It is an HTTP POST   request. /privet/printer/createjob API MUST check for a valid "X-Privet-Token" header.   The device MUST implement this API on "/privet/printer/createjob" url: POST /privet/printer/createjob HTTP/1.1 When receiving /privet/printer/createjob API call, the printer MUST create a new print job ID, store the received print ticket in the CJT format, and return print job id back to the client. 5.1.1. Input /privet/printer/createjob API has no input parameters in URL. The request body should contain the print job ticket data in CJT format. 5.1.2. Return /privet/printer/createjob API returns the following data:

Value name Value type La description

job_id chaîne ID of the newly created print job.

expires_in int Number of seconds this print job is valid.

Exemple:

        "job_id": "123",         "expires_in": 600

5.1.3. les erreurs /privet/printer/createjob API may return the following errors (see Errors section for details):

Erreur La description

invalid_ticket Submitted print ticket is invalid.

printer_busy Printer is busy and can’t currently process /createjob. Recommencez     after timeout.

printer_error Printer is in error state and requires user interaction to fix it.     Description should contain more detailed explanation (e.g. "Paper jam in Tray 1").

invalid_x_privet_token X-Privet-Token is invalid or empty in the request.

If device is not exposing /privet/printer/createjob it MUST return HTTP 404 error. Si   X-Privet-Token header is missing, the device MUST return HTTP 400 error. 5.2. /privet/printer/submitdoc API /privet/printer/submitdoc API is REQUIRED to implement printing over a local network (offline or repost to Cloud Print). It is an HTTP POST request. /privet/printer/submitdoc API MUST check for a valid "X-Privet-Token" header. The device MUST implement this API on "/privet/printer/submitdoc" url: POST /privet/printer/submitdoc HTTP/1.1 When receiving the /privet/printer/submitdoc API call, the printer should start printing. If it is unable to begin printing, it MUST return the error printer_busy and a recommended timeout period for the client to wait before trying again. If the printer is not able to hold all of the data in its internal buffer, it SHOULD use TCP   mechanisms to slow down data transfer until it prints a portion of the document, making part of   the buffer available again. (For example, the printer may set windowsize=0 on TCP layers, which   will make the client wait.) Submitting a document to the printer may take a significant amount of time. The client should be   able to check the state of the printer and job (advanced printing) while printing is in progress.   In order to do that, the printer MUST allow the client to call the /privet/info and   /privet/printer/jobstate APIs while processing /privet/printer/submitdoc API calls. Il est   recommended for all clients to start a new thread to execute the /privet/printer/submitdoc API   call, so that the main thread can use the /privet/info and /privet/printer/jobstate APIs to check   printer and job states. Remarque: Upon completion or abortion of the local print job, it is strongly   recommended (and will be required in a future version of this spec) to report the final state of   the job to the /cloudprint/submit interface for accounting and user experience purposes. le   parameters "printerid", "title", "contentType" and "final_semantic_state" (in   PrintJobState format) are required, and the parameters "tag" (repeated   parameter) and "ticket" (the ticket of the job in CloudJobTicket format).   Note that the provided PrintJobState must actually be final, i.e. its type must be DONE or   ABORTED, and a cause must be provided in the case that it is ABORTED (see   JobState for details). Also note that this use of the   /cloudprint/submit interface to report local print jobs is not mentioned in   its specification because that section is intended to describe   the interface's primary use: submitting a print job with the document to print provided in the   "content" parameter. 5.2.1. Input /privet/printer/submitdoc API has the following input parameters:

Name Valeur

job_id (optional) Print job id. May be omitted for simple printing case     (voir au dessus). Must match the one returned by the printer.

user_name (optional) Human readable user name. This is not definitive, and should     only be used for print job annotations. If job is re-posted to the Cloud Print service this     string should be attached to the Cloud Print job.

client_name (optional) Name of the client application making this request. Pour     display purposes only. If job is re-posted to the Cloud Print service this string should be     attached to the Cloud Print job.

job_name (optional) Name of the print job to be recorded. If job is re-posted to     the Cloud Print service this string should be attached to the Cloud Print job.

offline (optional) Could only be "offline=1". In this case printer should     only try printing offline (no re-post to Cloud Print server).

Request body should contain a valid document for printing. "Content-Length" should   include the correct length of the request. "Content-Type" header should be set to   document MIME type and match one of the types in the CDD (unless CDD specifies "*/*"). Clients are HIGHLY recommended to provide a valid user name (or email), a client name and a job   name with this request. Those fields are only used in UIs to improve user experience. 5.2.2. Return /privet/printer/submitdoc API returns following data:

Value name Value type La description

job_id chaîne ID of the newly created print job (simple printing) or     job_id specified in the request (advanced printing).

expires_in int Number of seconds this print job is valid.

job_type chaîne Content-type of the submitted document.

job_size int 64 bit Size of the print data in bytes.

job_name chaîne (optional) Same job name as in input (if any).

Exemple:

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

5.2.3. les erreurs /privet/printer/submitdoc API may return the following errors (see Errors section for details):

Erreur La description

invalid_print_job Invalid/expired job id is specified in the request. Retry after     timeout.

invalid_document_type Document MIME-type is not supported by the printer.

invalid_document Submitted document is invalid.

document_too_large Document exceeds maximum size allowed.

printer_busy Printer is busy and can’t currently process document. Recommencez     after timeout.

printer_error Printer is in error state and requires user interaction to fix it.     Description should contain more detailed explanation (e.g. "Paper jam in Tray 1").

invalid_params Invalid parameters specified in the request. (Unknown parameters     should be safely ignored for future compatibility)

user_cancel User explicitly cancelled printing process from the device.

server_error Posting document to Cloud Print has failed.

invalid_x_privet_token X-Privet-Token is invalid or empty in the request.

If the device is not exposing /privet/printer/submitdoc, it MUST return HTTP 404 error. Si la   X-Privet-Token header is missing, the device MUST return HTTP 400 error. Remarque: /privet/printer/submitdoc API may require special handling on printer   side (because of the large payload attached). In some cases (depends on the printer HTTP server   implementation and platform), printer may close socket BEFORE returning HTTP error. In other,   printer may return 503 error (instead of Privet error). Printers SHOULD try as much as possible to   return Privet. However, every client implementing Privet specification SHOULD be able to handle   socket close (no HTTP error) and 503 HTTP error cases for /privet/printer/submitdoc API. Dans ce   case, client SHOULD handle it as a Privet "printer_busy" error with   "timeout" set to 15 seconds. To avoid infinite retries, client may stop retrying after   a reasonable number of attempts (for example, 3). 5.3. /privet/printer/jobstate API /privet/printer/jobstate API is OPTIONAL (see Simple Printing above). It is an HTTP GET request. /privet/printer/jobstate API MUST check for a valid "X-Privet-Token" header. The device MUST implement this API on "/privet/printer/jobstate" url: GET /privet/printer/jobstate HTTP/1.1 When receiving a /privet/printer/jobstate API call, a printer should return the status of the requested print job or invalid_print_job error. 5.3.1. Input /privet/printer/jobstate API has following input parameters:

Name Valeur

job_id Print job ID to return status for.

5.3.2. Return /privet/printer/jobstate API returns the following data:

Value name Value type La description

job_id chaîne Print job id there status information is for.

state chaîne draft – print job has been created on the device (no     /privet/printer/submitdoc calls have been received yet). queued – print job has been received and queued, but printing has not started yet. in_progress – print job is in the progress of printing. stopped – print job has been paused, but can be restarted manually or automatically. terminé – print job is done. aborted – print job failed.

la description chaîne (optional) Human readable description of the print job     status. Should include additional information if statestopped or aborted. le semantic_state field usually provides better and more meaningful     description to the client.

expires_in int Number of seconds this print job is valid.

job_type chaîne (optional) Content-type of the submitted document.

job_size int 64 bit (optional) Size of the print data in bytes.

job_name chaîne (optional) Same job name as in input (if any).

server_job_id chaîne (optional) ID of the job returned from the server (if     job has been posted to Cloud Print service). Omitted for offline printing.

semantic_state JSON (optional) Semantic state of the job in     PrintJobState format.

Example (printing by reporting through 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"

Example (offline printing error):

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

Example (print job aborted by the user):

        "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         

Example (print job stopped due to out of paper). Notice the reference to the device state. le client will need to call the /privet/info API to get more details about the device state:

        "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. les erreurs /privet/printer/jobstate API may return the following errors (see Errors section for details):

Erreur La description

invalid_print_job Invalid/expired job ID is specified in the request.

server_error Getting print job status (for print jobs posted to Cloud Print) has     failed.

invalid_x_privet_token X-Privet-Token is invalid or empty in the request.

If device is not exposing /privet/printer/jobstate, it MUST return HTTP 404 error. Si la   X-Privet-Token header is missing, the device MUST return HTTP 400 error. 6. Appendix 6.1. Default behavior and settings This section will explain the default behavior we expect from ALL Privet-compatible devices.

Out-of-the-box devices should support only /privet/info et /privet/register APIs. All other APIs (e.g. /privet/accesstoken, local printing) should     be disabled. Registration requires physical interaction with a device.

User MUST take a physical action on the device (e.g., pressing a button) to confirm their       access to the device. After the user takes the action noted above, the printer should send the       /cloudprint/register request. It should not send this request until after the action is taken       (see Sequence Diagram 1). If the device is processing a /privet/register request (for instance, waiting on the action       above), it must reject all other /privet/register requests. The device MUST return the       device_busy error in this case. The device should timeout any /register request that does not receive the physical action       mentioned above within 60 seconds. The device MUST return the confirmation_timeout error in       this case. Optional: Recommended but not required, the following may improve user experience:

The printer might flash a light or its screen to indicate that the user needs to take an         action to confirm registration. The printer might state on its screen that ‘it is being registered to Google Cloud         Print for user ‘abc@def.com’ – press OK to         continue’, where abc@def.com  is the user         parameter from the /register API call. This would make it clearer to a user that:

it is their registration request that s/he is confirming what is happening if s/he didn’t trigger the request.

In addition to a physical action to confirm from the printer (e.g., ‘Press the OK         button’), a printer may also offer the user a button to cancel the request (e.g.,         ‘Press Cancel to reject’). This would allow users who did not trigger the         registration request to cancel it before the 60 second timeout. The device MUST return the         user_cancel error in this case.

Ownership transfers:

The device may be deleted explicitly from the Cloud service.

If the device receives success, but no device description as a result of         /cloudprint/printer (for GCP) call, it MUST revert to default (out-of-the-box) mode. If the device’s credentials no longer work (explicitly because of "invalid         credentials" response from the server), it MUST revert to default (out-of-the-box)         mode.

Local factory reset MUST clear device’s credentials and set it to default state. Optional: The device may provide a menu item to clear credentials and put it into default       mode.

Devices supporting XMPP notifications MUST include the ability to ping the server. The ping     timeout MUST be controllable from the server through "local_settings". The device may explicitly ping the server (/cloudprint/printer API for GCP, in addition to     XMPP pings)  no more often than once a day (24 hours) to make sure they are in sync. Il est     recommended to randomize the check window within 24-32 hour window. Optional: For Cloud Print devices, it is recommended but not required to have a manual way     (button) to allow the user to initiate a check for new print jobs from the device. Some printers     already have this. Optional. Enterprise printers may have an option to disable local discovery completely. Dans     such case, the device MUST update these local settings on the server. New local settings MUST be     empty (setting "local_discovery" to "false", means that it can be     re-enabled from the GCP Service).

6.1.2 Default Registration Diagram

6.2. XSSI and XSRF attacks and prevention This section will explain the possibility of XSSI and XSRF attacks on the device and how to protect from them (including token generation techniques). More details are here:

http://googleonlinesecurity.blogspot.com/2011/05/website-security-for-webmasters.html Normally, XSSI and XSRF attacks are possible when a site is using cookie authentication mechanisms. While Google doesn’t use cookies with their Cloud Print Service, such attacks are still possible. Local network access, by design, implicitly trusts requests. 6.2.1. XSSI It is possible for a malicious website to guess the IP address and port number of a Privet-compatible device and to try to call the Privet API using "src="http://developers.google.com/inside of a tag:

Without protection, malicious websites would be able to execute API calls and access results. To prevent this type of attack, ALL Privet API calls MUST require the "X-Privet-Token" header in the request. "src="http://developers.google.com/script tags are not able to add headers, effectively guarding against this type of attack. 6.2.2. XSRF

http://en.wikipedia.org/wiki/Cross-site_request_forgery It is possible for a malicious website to guess the IP address and port number of a Privet-compatible device and try to call Privet API using an , forms, or some other cross-website loading mechanism. Attackers would not be able to access the results of the request, but if the request would perform an action (e.g. printing), they could trigger it. To prevent this attack, we require the following protection:

Leave /privet/info API open to XSRF /privet/info API MUST NOT perform any actions on the device Use /privet/info API to receive x-privet-token All other APIs MUST check for a valid x-privet-token in "X-Privet-Token" header. x-privet-token SHOULD be valid for only 24 hours.

Even if an attacker is able to execute the /privet/info API, they would not be able to read x-privet-token from the response and therefore would not be able to call any other API. It is strongly recommended to generate the XSRF token using the following algorithm: XSRF_token = base64( SHA1(device_secret + DELIMITER + issue_timecounter) + DELIMITER + issue_timecounter ) XSRF Token Generation Elements:

DELIMITER is a special character, usually ‘:’ issue_timecounter is a number of seconds since some event (epoch for timestamp) or     device boot time (for CPU counters). issue_timecounter is constantly increasing when     the device is up and running (see token verification below). SHA1 – hash function using SHA1 algorithm base64 – base64 encoding device_secret – secret specific to the device. Device secret MUST be updated on every     restart.

Recommended ways to generate device secret:

Generate a new UUID on every restart Generate a 64 bit random number on every restart

The device is not required to store all of the XSRF tokens it has issued. When the device needs   to verify a XSRF token for validity, it should base64-decode the token. Get the issue_timecounter from the second half (cleartext), and try to produce SHA1 hash of device_secret + DELIMITER + issue_timecounter où issue_timecounter is from   the token. If the newly generated SHA1 matches the one in the token, device must now check if the issue_timecounter is within the validity period from (24 hours) of the current time   counter. To do so, device takes the current time counter (CPU counter for example) and subtracts issue_timecounter à partir de cela. The result MUST be the number of seconds since token   issue. Important: This is the recommended way to implement XSRF   protection. Clients of the Privet specification shall not try to understand XSRF token, instead   they shall treat is as a blackbox. Figure 6.2.3 illustrates a recommended way to implement the   X-Privet-Token and verification of a typical request. 6.2.3 X-Privet Token Generation and Verification Sequence Diagram

6.3. Workflow diagrams This section will illustrate a workflow in different cases. 6.3.1. Printer out of the box workflow

6.3.2. Registered printer startup

6.3.3 XMPP notifications handling workflow

6.3.4. Check printer settings workflow

Click to rate this post! [Total: 0 Average: 0]