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:

1. Introduction: introduction à Privet
2. Découverte: mécanismes de découverte locaux
3. Annonces: annonces de découverte locale
4. API: API Privet pour les périphériques cloud généraux
5. API d'imprimante: API Privet utilisées par les imprimantes
6. 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:

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.

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).

1. Lancer le processus d'inscription anonyme.
2. Un client initie ce processus en appelant l'API / privet / register. L'appareil peut attendre
       confirmation de l'utilisateur à ce moment.
3. 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:

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:

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):

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:

4.4.2. Revenir

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

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):

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:

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):

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:

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:

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):

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:

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:

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):

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:

5.3.2. Return

/privet/printer/jobstate API returns the following data:

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):

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