A partir del 31 de diciembre de 2020, Google Cloud Print dejará de ser compatible. Consulta el artículo de asistencia para obtener ayuda con la migración.

Se usó la API de Cloud Translation para traducir esta página.

Privet

Privet es una API de detección de dispositivos locales en la nube que usan los servicios en la nube. Este documento está organizado en las siguientes secciones:

Introducción: Introducción a Privet
Descubrimiento: Mecanismos de descubrimiento locales
Anuncios: Avisos de descubrimiento locales
API: API de Privet para dispositivos de nube generales
API de impresora: Incluye las API de Privet que utilizan las impresoras.
Apéndice: diagramas complementarios

1. Introducción

Los dispositivos conectados a la nube tienen muchos beneficios. Pueden usar los servicios de conversión en línea, alojar colas de trabajos mientras el dispositivo está sin conexión y se puede acceder a ellos desde cualquier lugar del mundo. Sin embargo, dado que un usuario determinado puede acceder a muchos dispositivos en la nube, debemos proporcionar un método para encontrar el dispositivo más cercano en función de la ubicación. El objetivo del protocolo Privet es vincular la flexibilidad de los dispositivos en la nube con un mecanismo de descubrimiento local adecuado para que los dispositivos se descubran con facilidad en entornos nuevos.

Los objetivos de este protocolo son los siguientes:

hacer que los dispositivos en la nube sean detectables localmente
registrar dispositivos en la nube con un servicio en la nube
asociar dispositivos registrados a su representación en la nube
habilitar funcionalidad sin conexión
Simplifique la implementación para que los dispositivos pequeños puedan usarla.

El protocolo Privet consta de 2 partes principales: descubrimiento y API. La detección se usa para encontrar el dispositivo en la red local, y la API se usa para obtener información sobre el dispositivo y realizar algunas acciones. En este documento, el dispositivo hace referencia a un dispositivo conectado a la nube que implementa el protocolo Privet.

2. Discovery

Discovery es un protocolo basado en zeroconf (mDNS y DNS-SD). El dispositivo DEBE implementar el direccionamiento IPv4 de vínculo local. El dispositivo DEBE cumplir con las especificaciones de mDNS y DNS-SD.

http://www.rfc-editor.org/rfc/rfc3927.txt (IPv4 Vínculo local)
http://www.rfc-editor.org/rfc/rfc4862.txt (IPv6 Vínculo local)
http://www.rfc-editor.org/rfc/rfc6762.txt (mDNS)
http://www.rfc-editor.org/rfc/rfc6763.txt (DNS-SD)

El dispositivo DEBE realizar la resolución de conflictos de nombres de acuerdo con las especificaciones anteriores.

2.1. Tipo de servicio

DNS Service Discovery usa el siguiente formato para los tipos de servicio: _applicationprotocol._transportprotocol. En el caso del protocolo Privet, el tipo de servicio para DNS-SD debe ser: _privet._tcp

El dispositivo también puede implementar otros tipos de servicios. Se recomienda usar el mismo nombre de instancia de servicio para todos los tipos de servicios que implementa el dispositivo. Por ejemplo, una impresora puede implementar servicios de "Impresora XYZ._privet._tcp" e "Impresora XYZ._printer._tcp". Simplificará la configuración para el usuario. Sin embargo, los clientes de Privet solo buscarán "_privet._tcp".

Además del tipo de servicio principal, el dispositivo DEBE anunciar los registros PTR de sus subtipos correspondientes (consulta las especificaciones de DNS-SD: &7.1. Enumeración de instancias selectiva (subtipos)". El formato debe ser el siguiente: _<subtype>.sub._privet._tcp

Actualmente, el único subtipo de dispositivo compatible es printer. Por lo tanto, todas las impresoras DEBEN crear dos registros PTR:

_privet._tcp.local
_impresión._sub._privet._tcp.local.

2.2. registro TXT

El Descubrimiento de servicios de DNS define campos para agregar información opcional sobre un servicio en los registros TXT. Un registro TXT consta de pares clave-valor. Cada par clave-valor comienza desde el byte de longitud seguido de hasta 255 bytes de texto. La clave es el texto que aparece antes del primer carácter “=” y el valor es el texto que está después del primer carácter “=” hasta el final. La especificación no permite ningún valor en el registro; en ese caso, no será un carácter "=" O ningún texto después del carácter "=". (Consulta las especificaciones de DNS-SD: "6.1. Reglas de formato general para los registros TXT de DNS" para el formato de registro TXT de DNS & &tt;6.2. DNS-SD TXT Record Size" para la longitud recomendada).

Privet requiere que el dispositivo envíe los siguientes pares clave-valor en el registro TXT. Las strings de clave-valor no distinguen entre mayúsculas y minúsculas. Por ejemplo, “CS=online” y “cs=ONLINE” son iguales. La información del registro TXT DEBE ser la misma a la que se puede acceder a través de la /info API (consulte la sección 4.1. API).

Se recomienda mantener un tamaño de registro TXT inferior a 512 bytes.

2.2.1. txtver

Versión de la estructura TXT. Los archivos TXT DEBEN ser el primer registro de la estructura TXT. Actualmente, la única versión compatible es 1.

txtvers=1

2.2.2. ty

Proporciona un nombre legible para el dispositivo. Por ejemplo:

ty=Google Cloud Ready Printer Model XYZ

2.2.3. Nota (opcional)

Proporciona un nombre legible para el dispositivo. Por ejemplo:

note=1st floor lobby printer

Nota: Esta es una clave opcional y se puede omitir. Sin embargo, si está presente, el usuario DEBE poder modificar este valor. Se debe usar la misma descripción cuando se registra el dispositivo.

2.2.4. url

URL del servidor al que está conectado este dispositivo (incluido el protocolo). Por ejemplo:

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

2.2.5. Tipo

Lista de subtipos de dispositivos compatibles con este dispositivo separados por comas. El formato es: "type=_subtype1,_subtype2". Actualmente, el único subtipo de dispositivo admitido es printer.

type=printer

Cada subtipo enumerado debe anunciarse con un registro PTR correspondiente. Para cada subtipo de servicio admitido, debe haber un elemento correspondiente. El nombre del subtipo de servicio (<subtype>.sub._privet._tcp) debe ser igual al tipo de dispositivo.

2.2.6. ID

ID del dispositivo. Si el dispositivo aún no se registró, esta clave debería estar presente, pero el valor debería estar vacío. Por ejemplo:

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

2.2.7. cs

Indica el estado de conexión actual del dispositivo. Se definen cuatro valores posibles en esta especificación.

"online" indica que el dispositivo está conectado actualmente a la nube.
"offline&; indica que el dispositivo está disponible en la red local, pero no puede comunicarse con el servidor.
"Conectando" indica que el dispositivo está realizando su secuencia de inicio y aún no está completamente en línea.
"not-configured" indica que el acceso a Internet del dispositivo aún no se configuró. Este valor no se usa actualmente, pero puede ser útil en versiones futuras de la especificación.

Por ejemplo:

cs=en línea
cs=sin conexión
cs=conexión

Si el dispositivo se registró con una nube, durante el inicio debe verificar la conectividad con un servidor para detectar su estado de conexión (por ejemplo, llamar a la API de Cloud para obtener la configuración del dispositivo). El dispositivo puede usar el estado de conexión de su canal de notificaciones (p.ej., XMPP) para informar este valor. Es posible que los dispositivos no registrados en el inicio hagan ping a un dominio para detectar su estado de conexión (por ejemplo, hacer ping en www.google.com para dispositivos de impresión en la nube).

3. Anuncios

Cuando se inicia el dispositivo, se apaga o cambia de estado, el dispositivo DEBE realizar el paso del anuncio como se describe en la especificación de mDNS. DEBE enviar el anuncio correspondiente al menos dos veces con un intervalo de, al menos, un segundo.

3.1. Inicio

Cuando se inicia el dispositivo, DEBES realizar los pasos de sondeo y anuncio como se describe en la especificación de mDNS. En este caso, se deben enviar los registros SRV, PTR y TXT. Se recomienda agrupar todos los registros en una respuesta de DNS, si es posible. De lo contrario, se recomienda el siguiente orden: SRV, PTR, registros TXT.

3.2. Cierre

Al apagar un dispositivo, DEBE tratar de notificar a todas las partes interesadas al respecto mediante el envío de un "paquete de despedida" con TTL=0 (como se describe en la documentación de mDNS).

3.3. Actualizar

Si se modificó la información que se describe en TXT, el dispositivo DEBE enviar un anuncio de actualización. En este caso, basta con enviar el nuevo registro TXT. Por ejemplo, después de registrar un dispositivo, DEBE enviar un anuncio de actualización con el nuevo ID de dispositivo.

4. API

Después de descubrir un dispositivo en la nube, se habilita la comunicación con el cliente directamente en la red local. Todas las API están basadas en HTTP 1.1. Los formatos de datos se basan en JSON. Las solicitudes a la API pueden ser solicitudes GET o POST.

Cada solicitud DEBE contener un encabezado X-Privet-Token válido. La ÚNICA solicitud que se permite que tenga un encabezado vacío "X-Privet-Token" es la solicitud /privet/info (ten en cuenta que el encabezado aún DEBE estar presente). Si falta el encabezado &X-Privet-Token, el dispositivo DEBE responder con el siguiente error HTTP 400:

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

Si el encabezado X-Privet-Token está vacío o no es válido, el dispositivo DEBE responder con un error de X-Privet-Token no válido (invalid_x_privet_token, consulta la sección Errores para obtener más detalles). La única excepción es la API /info. Para obtener más información sobre por qué se hace esto y cómo se deben generar los tokens, consulta el Apéndice A: Prevención y ataques de XSSI y XSRF.

Si una API solicitada no existe o no es compatible, el dispositivo DEBE mostrar un error HTTP 404.

4.1. de disponibilidad de API

Antes de exponer CUALQUIER API (incluida la API /info), el dispositivo DEBE comunicarse con el servidor para verificar la configuración local. La configuración local DEBE conservarse entre los reinicios. Si el servidor no está disponible, se debe usar la última configuración local conocida. Si el dispositivo aún no se registró, debe seguir la configuración predeterminada.

Los dispositivos de Google Cloud Print DEBEN seguir estos pasos para registrar, recibir y actualizar la configuración local.

4.1.1. Registro

Cuando el dispositivo se registra, DEBE especificar el parámetro "local_settings" de la siguiente manera:

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

Puede establecer las siguientes opciones de configuración:

Nombre del valor	Tipo de valor	Descripción
descubrimiento_local	boolean	Indica si se permite la funcionalidad de descubrimiento local. Si &false; falso, se deben inhabilitar todas las API locales (incluida /info) y la detección de DNS-SD. De forma predeterminada, los dispositivos que se registran recientemente deben pasar "true".
acceso_token_habilitado	booleano (opcional)	Indica si la API /accesstoken debe exponerse en la red local. De forma predeterminada, debe ser "verdadero".
impresoras/local_printing_enabled	booleano (opcional)	Indica si la funcionalidad de impresión local (/printer/createjob, /printer/submitdoc) o /printer/jobstate) debe exponerse en la red local. De forma predeterminada, debe ser "verdadero".
impresora/conversión_habilitada	booleano (opcional)	Indica si la impresión local puede enviar un trabajo al servidor para la conversión. Solo tiene sentido cuando la impresión local está habilitada.
xmpp_timeout_value	int (opcional)	Indica la cantidad de segundos entre los pings del canal XMPP. La configuración predeterminada DEBE ser 300 (5 minutos) o más.

Importante: La ausencia de un valor opcional indica que el dispositivo no admite la funcionalidad correspondiente.

4.1.2. Inicio

Al iniciarse el dispositivo, debe ponerse en contacto con el servidor a fin de verificar qué API están disponibles para exponerse en la red local. Para las impresoras conectadas a Cloud Print, deben llamar a:

/cloudprint/printer?printerid=<printer_id>

/cloudprint/list

/cloudprint/printer es preferible a /cloudprint/list, pero ambas funcionan.

Esta API muestra los parámetros actuales del dispositivo, incluida la configuración de la API local. La respuesta del servidor tendrá el siguiente formato:

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

"current" indica la configuración que está activa en este momento.

"pending" indica la configuración que debe aplicarse al dispositivo (puede faltar este objeto).

Una vez que el dispositivo vea la configuración “Pendiente”, DEBES actualizar su estado (consulta a continuación).

4.1.3. Actualizar

Si se necesita actualizar la configuración, se enviará una notificación XMPP al dispositivo. La notificación tendrá el siguiente formato:

<device_id>/update_settings

Al recibir esta notificación, el dispositivo DEBE consultar al servidor para obtener la última configuración. Los dispositivos de Google Cloud Print DEBEN usar:

/cloudprint/printer?printerid=<printer_id>

Una vez que el dispositivo ve la sección "pendiente" como resultado de la API /cloudprint/printer (en el inicio o debido a la notificación), DEBE actualizar su estado interno para recordar la nueva configuración. DEBE llamar a la API del servidor para confirmar la nueva configuración. En el caso de las impresoras en la nube, el dispositivo DEBE llamar a la API /cloudprint/update y usar el parámetro "local_settings" durante el registro.

Cuando vuelvas a conectarte al canal XMPP, el dispositivo DEBE llamar a la API /cloudprint/printer para verificar si se modificó la configuración local desde la última vez.

4.1.3.1. Configuración local pendiente

El parámetro "local_settings" que el dispositivo usa para llamar a la API del servidor NO DEBE contener la sección "pendiente".

4.1.3.2. Configuración local actual

ÚNICAMENTE el dispositivo puede cambiar la sección "actual" de la &configuración local. Todos los demás cambiarán la sección "pendiente" y esperarán a que el dispositivo propague los cambios en la sección "actual".

4.1.4. Sin conexión

Si no puedes comunicarte con el servidor durante el inicio, después de la notificación, el dispositivo DEBE usar la última configuración local conocida.

4.1.5. Borrando dispositivo del servicio

Si se borró el dispositivo del servicio (por ejemplo, GCP), se enviará una notificación XMPP. La notificación tendrá el siguiente formato:

<device_id>/delete

Al recibir esta notificación, el dispositivo DEBE ir al servidor para comprobar su estado. Los dispositivos de Google Cloud Print DEBEN usar:

/cloudprint/printer?printerid=<printer_id>

El dispositivo DEBE recibir una respuesta HTTP correcta, con éxito=falso y sin descripción de dispositivo/impresora. Significa que se quitó el dispositivo del servidor y que el dispositivo DEBE borrar sus credenciales y activar el modo de configuración de fábrica predeterminado.

Cada vez que el dispositivo recibe una respuesta que indica que se borró como resultado de la API /cloudprint/printer (inicio, notificación de configuración de actualización, ping diario), DEBE borrar sus credenciales y activar el modo predeterminado.

4.2. API de /privet/info

La API de información es OBLIGATORIA y DEBE implementarla por cada dispositivo. Es una solicitud HTTP GET para "/privet/info&url: GET /privet/info HTTP/1.1

La API de información muestra información básica sobre un dispositivo y las funciones que admite. Esta API NO DEBE cambiar el estado del dispositivo ni realizar ninguna acción, ya que es vulnerable a los ataques de XSRF. Esta es la ÚNICA API que puede tener un encabezado de &X-Privet-Token vacío. Los clientes deben llamar a la API de /privet/info con el encabezado "X-Privet-Token" establecido en X-Privet-Token: & &;

La API de información DEBE mostrar datos coherentes con los datos disponibles en el registro TXT durante el descubrimiento.

4.2.1. Entrada

La API de /privet/info no tiene parámetros de entrada.

4.2.2. Volver

La API de /privet/info muestra información básica sobre el dispositivo y la funcionalidad compatible.

La columna TXT indica el campo correspondiente en el registro TXT de DNS-SD.

Nombre del valor	Tipo de valor	Descripción	TXT
version	string	La versión más alta (principal) de la API compatible, actualmente 1.0
name	string	Es el nombre legible del dispositivo.	ty
descripción	string	(Opcional) Descripción del dispositivo. El usuario debe poder modificarlo.	nota
url	string	URL del servidor con el que está hablando este dispositivo. La URL DEBE incluir la especificación del protocolo, por ejemplo: https://www.google.com/cloudprint.	url
type	lista de strings	Lista de tipos de dispositivos compatibles.	type
id	string	ID de dispositivo, vacío si aún no se registró el dispositivo.	id
dispositivo_estado	string	Estado del dispositivo: inactivo significa que el dispositivo está listo. Procesando: significa que el dispositivo está ocupado y su funcionalidad puede estar limitada durante un tiempo. detenido significa que el dispositivo no funciona y se requiere la intervención del usuario.
estado_de_conexión	string	Estado de la conexión con el servidor (base_url) en línea - conexión disponible sin conexión - sin conexión conexión - realizando pasos de inicio no configurado - aún no se configuró	cs
fabricante	string	Nombre del fabricante del dispositivo
modelo	string	Modelo del dispositivo
número_de_serie	string	Es un identificador de dispositivo único. En esta especificación, DEBE ser un UUID. (Especificación de GCP 1.1) (opcional) Recomendamos usar el mismo ID de número de serie en todas partes para que diferentes clientes puedan identificar el mismo dispositivo. Por ejemplo, las impresoras que implementan IPP pueden usar este ID de número de serie en el campo &printt-device-id".
firmware	string	Versión de firmware del dispositivo
uptime	int	Cantidad de segundos desde el inicio del dispositivo.
URL_configuración	string	(Opcional) URL (incluido el protocolo) de la página con instrucciones de configuración
URL_de_asistencia	string	(Opcional) URL (incluido el protocolo) de la página con asistencia, información sobre las Preguntas frecuentes
actualizar URL	string	(Opcional) URL (incluido el protocolo) de la página con instrucciones de firmware de actualización
token-privet-x	string	Valor del encabezado X-Privet-Token que se debe pasar a todas las API para evitar ataques XSSI y XSRF. Consulta 6.1 para obtener más detalles.
api	descripción de las API	Lista de API compatibles (que se describen a continuación)
estado_semántico	JSON	Es un estado semántico del dispositivo en formato CloudDeviceState (opcional).

api: Es una lista JSON que contiene la lista de las API disponibles a través de la red local. Ten en cuenta que es posible que no todas las API estén disponibles al mismo tiempo en la red local. Por ejemplo, un dispositivo conectado recientemente solo debería admitir la API de /register:

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

Una vez que se completa el registro del dispositivo, este DEBE admitir la API de /register. El dispositivo también debe verificar con el servicio qué API pueden exponerse en la red local. Por ejemplo:

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

En este momento, están disponibles las siguientes API:

/privet/register: API para el registro de dispositivos en la red local (consulta la API /privet/register para obtener más información). Esta API DEBE ocultarse una vez que el dispositivo se registra correctamente en la nube.
/privet/accesstoken: API para solicitar token de acceso desde el dispositivo (consulta la API /privet/accesstoken para obtener más información)
/privet/capabilities: API para recuperar funciones del dispositivo (consulta la API /privet/capabilities para obtener más información)
/privet/printer/*: API específica para el tipo de dispositivo "printer" consulta las API específicas para impresoras para obtener más detalles.

Este es un ejemplo de la respuesta /privet/info. (Ten en cuenta la falta de la API de /privet/register, dado que ya se registró el dispositivo):

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

Este es un ejemplo de la respuesta de /privet/info para una impresora que se quedó sin tinta (observa el campo semántica_state):

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

4.2.3. Errores

/privet/info API SOLO debería mostrar un error si falta el encabezado X-Privet-Token. DEBE ser error HTTP 400:

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

4.3. API de /privet/register

La API de /privet/register es OPCIONAL. Es una solicitud HTTP POST. La API de /privet/register DEBE verificar si un encabezado X-Privet-Token es válido. El dispositivo DEBE implementar esta API en la URL &pritt/register":

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

El dispositivo debe exponer la API de /privet/register SOLO cuando permite el registro anónimo en este momento. Por ejemplo:

Cuando el dispositivo está encendido (o después de hacer clic en un botón especial en el dispositivo) y aún no se ha registrado, debería exponer la API /privet/register para permitir que un usuario de la red local pueda reclamar la impresora.
Una vez que se completa el registro, el dispositivo debe dejar de exponer la API de /privet/register para evitar que otro usuario de la red local reclame el dispositivo.
Algunos dispositivos pueden tener diferentes maneras de registrar dispositivos y no deben exponer la API /privet/register (por ejemplo, el conector de Google Cloud Print).

El proceso de registro consta de 3 pasos (consulte el registro anónimo para Cloud Print).

Iniciar el proceso de registro anónimo.
Un cliente inicia este proceso llamando a la API /privet/register. Es posible que el dispositivo espere la confirmación del usuario en ese momento.
Obtener token de reclamo

El cliente realiza un sondeo para saber cuándo el dispositivo está listo para continuar. Una vez que el dispositivo está listo, envía una solicitud al servidor para recuperar el token de registro y la URL de registro. El token y la URL recibidos DEBEN devolverse al cliente. Durante este paso, si el dispositivo recibe otra llamada para inicializar el registro, debería hacer lo siguiente:

Si este es el mismo usuario que inició el registro, descarta todos los datos anteriores (si corresponde) y comienza un nuevo proceso de registro.
Si se trata de otro usuario, se muestra el error device_busy y el tiempo de espera de 30 segundos.

Proceso completo de registro.

Una vez que el cliente haya reclamado el dispositivo, debe notificarlo para completar el registro. Una vez que se completa el proceso de registro, el dispositivo debe enviar un anuncio de actualización, incluido el ID de dispositivo recién adquirido.

Nota: Cuando el dispositivo está procesando una llamada a la API /privet/register, no se pueden procesar otras llamadas a la API /privet/register simultáneamente. El dispositivo DEBE mostrar el error device_busy y el tiempo de espera de 30 segundos.

Recomendamos encarecidamente que el usuario confirme el registro en el dispositivo. Si se implementa, el dispositivo DEBE esperar la confirmación del usuario DESPUÉS de recibir una llamada a la API /privet/register.action=start. El cliente llamará a la API de /privet/register?action=getClaimToken para saber cuándo se completó la confirmación del usuario y si el token de reclamo está disponible. Si el usuario cancela el registro en el dispositivo (por ejemplo, presiona el botón Cancelar), se DEBE mostrar el error user_cancel. Si el usuario no confirmó el registro en un plazo determinado, se DEBE mostrar el error confirm_timeout. Consulta la sección de valores predeterminados para obtener más detalles.

4.3.1. Entrada

La API de /privet/register tiene los siguientes parámetros de entrada:

Nombre	Valor
acción	Puede ser una de las siguientes opciones: start, para iniciar el proceso de registro getClaimToken: Recuperar el token de reclamo del dispositivo cancel o cancelar el proceso de registro complete para completar el proceso de registro
usuario	Correo electrónico del usuario que reclamará este dispositivo.

El dispositivo DEBE verificar que la dirección de correo electrónico de todas las acciones (start, getClaimToken, cancel, complete) coincida.

4.3.2. Volver

La API de /privet/register muestra los siguientes datos:

Nombre del valor	Tipo de valor	Descripción
acción	string	La misma acción que en el parámetro de entrada.
usuario	string (opcional)	Mismo usuario que en el parámetro de entrada (puede faltar, si se omite en la entrada)
token	string (opcional)	Token de registro (obligatorio para la respuesta “getClaimToken”, omitida por “start", “complete” y “cancel”).
URL_reclamo	string (opcional)	URL de registro (obligatorio para la respuesta "getClaimToken", omitida por "start", "completo", "cancelar"). En el caso de las impresoras en la nube, debe ser la dirección "complete_invite_url&quot recibida del servidor.
URL_reclamada_automática	string (opcional)	URL de registro (obligatorio para la respuesta "getClaimToken", omitida por "start", "completo", "cancelar"). En el caso de las impresoras en la nube, debe ser la dirección URL automatizada de invitación recibida del servidor.
id_dispositivo	string (opcional)	ID del dispositivo nuevo (omitido para la respuesta de inicio, obligatorio para la respuesta completa).

El dispositivo DEBE mostrar su ID de dispositivo en la respuesta de la API /privet/info SOLO después de que se completa el registro.

Ejemplo 1:

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

Ejemplo 2:

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

Ejemplo 3:

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

4.3.3. Errores

La API de /privet/register puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):

Error	Descripción
dispositivo_ocupado	El dispositivo está ocupado y no puede realizar la acción solicitada. Vuelve a intentarlo después del tiempo de espera.
acción_usuario_pendiente	En respuesta a &gett;getClaimToken, este error indica que el dispositivo aún está pendiente de confirmación del usuario y se debe reintentar la solicitud después del tiempo de espera.
cancelar_usuario	El usuario canceló explícitamente el proceso de registro del dispositivo.
confirmación_tiempo de espera	Se agotó el tiempo de espera de la confirmación del usuario.
acción_no válida	Se ha llamado a una acción no válida. Por ejemplo, si el cliente llamó a action=complete antes de llamar a action=start y action=getClaimToken.
parámetros_no válidos	Los parámetros especificados en la solicitud no son válidos. (Los parámetros desconocidos se deben ignorar de forma segura para garantizar la compatibilidad en el futuro). Por ejemplo, muestra esto si el cliente llamó a action=unknown o user=.
error_config_dispositivo	La fecha y la hora (o alguna otra configuración) son incorrectas en el dispositivo. El usuario debe ir al sitio web interno del dispositivo y establecer la configuración del dispositivo.
sin conexión	El dispositivo no está conectado y no puede comunicarse con el servidor.
error_servidor	Se produjo un error de servidor durante el proceso de registro.
token_privado_x no válido	X-Privet-Token no es válido o está vacío en la solicitud.

El dispositivo DEBE dejar de exponer la API de /privet/register después de completar el registro correctamente. Si el dispositivo no expone la API /privet/register, DEBE mostrar el error HTTP 404. Por lo tanto, si un dispositivo ya está registrado, la llamada a esta API DEBE mostrar 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.

4.4. API de /privet/accesstoken

La API de /privet/accesstoken es OPCIONAL. Es una solicitud HTTP GET. La API de /privet/accesstoken DEBE verificar si el encabezado X-Privet-Token es válido. El dispositivo DEBE implementar esta API en la URL &pritt/accesstoken"

GET /privet/accesstoken HTTP/1.1

Cuando el dispositivo recibe la llamada a la API /accesstoken, debe llamar al servidor para recuperar el token de acceso del usuario dado y devolver el token al cliente. Luego, el cliente usará el token de acceso para acceder a este dispositivo a través de la nube.

Los dispositivos de Google Cloud Print DEBEN llamar a la siguiente API:

/cloudprint/proximitytoken

y pasa el parámetro &print > userprint de la API local. Si el proceso es satisfactorio, la respuesta del servidor contendrá el siguiente objeto:

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

Los dispositivos de Google Cloud Print DEBEN pasar el valor del objeto "proximity_token" en la respuesta a las llamadas a la API /privet/accesstoken locales. Es más ventajoso (preparado para el futuro) que el dispositivo pase TODOS los parámetros (incluidos los que no se describen en esta especificación).

4.4.1. Entrada

La API de /privet/accesstoken tiene los siguientes parámetros de entrada:

Nombre	Valor
usuario	Correo electrónico del usuario que tenía la intención de usar este token de acceso Puede estar vacío en la solicitud.

4.4.2. Volver

La API de /privet/accesstoken muestra los siguientes datos:

Nombre del valor	Tipo de valor	Descripción
token	string	Token de acceso que muestra el servidor
usuario	string	Mismo usuario que en el parámetro de entrada.
expires_in	int	Cantidad de segundos hasta que venza este token. Se recibe del servidor y se pasa en esta respuesta.

Ejemplo:

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

4.4.3. Errores

La API de /privet/accesstoken puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):

Error	Descripción
sin conexión	El dispositivo no está conectado y no puede comunicarse con el servidor.
access_denied	Derechos insuficientes. Acceso denegado El dispositivo debería mostrar este error cuando el servidor haya rechazado explícitamente la solicitud.
parámetros_no válidos	Los parámetros especificados en la solicitud no son válidos. (Los parámetros desconocidos se deben ignorar de forma segura para garantizar la compatibilidad en el futuro). Por ejemplo, si el cliente llamó a /accesstoken?user= o /accesstoken.
error_servidor	Error del servidor.
token_privado_x no válido	El token X-Privet no es válido o está vacío en la solicitud.

Si el dispositivo no expone la API /privet/accesstoken, DEBE mostrar el error HTTP 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.

4.5. API de /privet/capabilities

La API de /privet/capabilities es OPCIONAL. Es una solicitud HTTP GET. La API /privet/capabilities debe verificar la presencia de un encabezado de &X-Privet-Token válido. El dispositivo DEBE implementar esta API en la URL "privet/capabilities":

GET /privet/capabilities HTTP/1.1

Cuando el dispositivo recibe llamadas a la API de /capabilities, si el dispositivo puede hacerlo, DEBE comunicarse con el servidor para obtener funciones actualizadas. Por ejemplo, si una impresora admite la publicación de un trabajo de impresión (recibido localmente) a sí misma a través del servicio de Cloud Print, debería mostrar las funciones que el servicio de Cloud Print mostraría. En este caso, Cloud Print puede modificar las capacidades originales de la impresora, ya que agrega nuevas funciones que puede realizar antes de enviar el trabajo a la impresora. El caso más común es una lista de tipos de documentos admitidos. Si la impresora está sin conexión, debería mostrar los tipos de documentos que admite. Sin embargo, si la impresora está en línea y está registrada en Cloud Print, DEBE mostrar "*/*" como uno de los tipos compatibles. En este caso, el servicio de Cloud Print realizará la conversión necesaria. Para la impresión sin conexión, la impresora DEBE admitir, al menos, el formato “image/pwg-raster”.

4.5.1. Entrada

La API de /privet/capabilities tiene los siguientes parámetros de entrada:

Nombre	Valor
sin conexión	(Opcional) Solo se puede "offline=1". En este caso, el dispositivo debe mostrar capacidades para uso sin conexión (si son diferentes de las capacidades "en línea").

4.5.2. Volver

La API de /privet/capabilities muestra las capacidades del dispositivo en el formato JSON de descripción del dispositivo en la nube (CDD) (consulta el documento de CDD para obtener más detalles). Como mínimo, las impresoras DEBEN mostrar una lista de los tipos compatibles aquí. Por ejemplo, una impresora lista para imprimir en la nube que está en línea puede mostrar algo como esto (como mínimo):

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

y, cuando se desconecta del servidor, puede mostrar lo siguiente:

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

Nota: Las impresoras expresan el orden de prioridad del tipo de contenido admitido. Por ejemplo, en los ejemplos anteriores, la impresora especifica que prefiere datos de "application/pdf" en lugar de "image/pwg-raster" e "image/jpeg". Si es posible, los clientes deben respetar la priorización de impresoras (consulta el documento de CDD para obtener más detalles).

4.5.3. Errores

La API de /privet/capabilities puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):

Error	Descripción
token_privado_x no válido	X-Privet-Token no es válido o está vacío en la solicitud.

Si el dispositivo no expone la API /privet/capabilities, DEBE mostrar el error HTTP 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.

4.6. Errores

Las API anteriores muestran los errores en el siguiente formato:

Nombre del valor	Tipo de valor	Descripción
error	string	Tipo de error (definido por API)
descripción	string (opcional)	Es una descripción legible del error.
server_api	string (opcional)	En caso de error del servidor, este campo contiene la API del servidor que falló.
código_servidor	int (opcional)	En caso de error del servidor, este campo contiene ese código de error que el servidor mostró.
servidor_http_code	int (opcional)	En el caso del error de HTTP del servidor, este campo contiene el servidor de código de error HTTP que se muestra.
timeout	int (opcional)	Cantidad de segundos que el cliente debe esperar antes de reintentar (solo para errores recuperables). El cliente DEBE aleatorizar el tiempo de espera real de este valor a un valor +20%.

Todas las API DEBEN mostrar el error HTTP 400 si falta el encabezado X-Privet-Token.

HTTP/1.1 400 Falta el encabezado X-Privet-Token.

Ejemplo 1:

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

Ejemplo 2:

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

5. API de Printer

Uno de los tipos de dispositivo compatibles con este protocolo es el tipo de impresora. Los dispositivos que admiten este tipo PUEDEN implementar algunas funciones específicas para las impresoras. Lo ideal es que las impresiones en impresoras listas para imprimir en la nube pasen por un servidor de Cloud Print:

En algunos casos, es posible que un cliente necesite enviar un documento de manera local. Puede ser necesaria cuando el cliente no tiene un ID de Google o no puede comunicarse con el servidor de Google Cloud Print. En ese caso, el trabajo de impresión se enviará de manera local a la impresora. A su vez, la impresora usará el servicio Cloud Print para la cola y la conversión de trabajos. La impresora volverá a publicar el trabajo enviado de manera local en el servicio de Cloud Print y, luego, lo solicitará, ya que se envió a través de la nube. Este proceso proporcionará una experiencia del usuario flexible en términos de servicio (conversión) y administración/seguimiento de trabajos de impresión.

Debido a que el servicio de Cloud Print implementa la conversión, la impresora DEBE anunciar todos los formatos de entrada ("*/*") entre la lista de los tipos de contenido admitidos:

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

En algunos casos, se desea una solución completamente sin conexión. Debido a que las impresoras admiten una cantidad limitada de formatos de entrada, un cliente deberá convertir los documentos a algunos formatos de impresoras compatibles de forma nativa.

Esta especificación REQUIERE que todas las impresoras admitan al menos el formato PWG Raster ("image/pwg-raster") para la funda de impresión sin conexión. Una impresora puede admitir otros formatos (por ejemplo, JPEG) y, si un cliente lo admite, puede enviar documentos en ese formato. La impresora DEBE exponer los tipos admitidos a través de la API de /capabilities, por ejemplo:

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

Un cliente puede iniciar una impresión mediante la red local de dos maneras.

Impresión simple: El cliente envía el documento a través de la red local a la API /submitdoc (sin especificar el parámetro job_id). El documento enviado se imprimirá mediante la configuración predeterminada de los tickets de impresión y no se necesitan estados de trabajo de impresión. Si la impresora SOLO admite este tipo de impresión, DEBE anunciar solamente la API de /submitdoc en la respuesta de la API de /privet/info.

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

Impresión avanzada: El cliente primero debe crear un trabajo de impresión en la impresora llamando a la API /privet/printer/createjob con un ticket de trabajo CJT válido en la solicitud. La impresora DEBE almacenar el ticket de impresión en la memoria y mostrar un job_id al cliente. Luego, el cliente llamará a la API de /printer/submitdoc y especificará el job_id recibido anteriormente. En ese momento, la impresora comenzará a imprimir. El cliente sondeará la impresora para el estado del trabajo de impresión llamando a la API /privet/printer/jobstate.

En un entorno de varios clientes, no hay garantía de cómo se llamará a esta API. Es posible que un cliente llame a /createjob entre las llamadas de otro cliente de /createjob>/submitdoc. Para eliminar los posibles interbloqueos y mejorar la usabilidad, recomendamos que tengas una pequeña cola de trabajos de impresión pendientes en la impresora (al menos de 3 a 5):

/createjob ocupa el primer espacio disponible en la cola.
El ciclo de vida del trabajo (en la cola) es de al menos 5 minutos.
Si se ocupan todos los lugares de la cola, se quitará el trabajo no imprimible más antiguo y se colocará uno nuevo.
Si hay un trabajo de impresión actualmente en impresión en el dispositivo (impresión simple o avanzada), /submitdoc debe mostrar el estado ocupado y proponer un tiempo de espera para reintentar este trabajo de impresión.
Si /submitdoc hace referencia a un trabajo que se quitó de la cola (debido a reemplazo o tiempo de espera), la impresora debería mostrar un error invalid_print_job y el cliente reintentará el proceso con el paso /createjob. El cliente DEBE esperar un tiempo de espera aleatorio de hasta 5 segundos antes de volver a intentarlo.

Si las restricciones de memoria impiden el almacenamiento de varios trabajos pendientes en el dispositivo, es posible tener una cola de 1 trabajo de impresión. Debe seguir el mismo protocolo que el anterior. Después de que un trabajo se completa o falla con un error, la impresora debe almacenar información sobre el estado del trabajo durante al menos 5 minutos. El tamaño de la cola para almacenar estados de trabajo completados debe ser de 10 como mínimo. Si hay más estados de trabajo que se deban almacenar, el más antiguo se puede quitar de la cola antes del tiempo de espera de 5 minutos.

Nota: Por ahora, los clientes sondearán para ver el estado del trabajo. En el futuro, es posible que solicitemos a la impresora que envíe una notificación de DNS TXT cuando cambie el estado de cualquier trabajo de impresión.

5.1. API de /privet/printer/createjob

La API de /privet/printer/createjob es OPCIONAL (consulte Impresión simple más arriba). Es una solicitud HTTP POST. La API /privet/printer/createjob DEBE verificar que el encabezado X-Privet-Token sea válido. El dispositivo DEBE implementar esta API en la URL &pritt/priert/printer/createjob:

POST /privet/printer/createjob HTTP/1.1

Cuando recibes una llamada a la API /privet/printer/createjob, la impresora DEBE crear un ID de trabajo de impresión nuevo, almacenar el ticket de impresión recibido en formato CJT y mostrar el ID del trabajo de impresión al cliente.

5.1.1. Entrada

La API de /privet/printer/createjob no tiene parámetros de entrada en la URL. El cuerpo de la solicitud debe contener los datos del ticket de trabajo de impresión en formato CJT.

5.1.2. Volver

La API de /privet/printer/createjob muestra los siguientes datos:

Nombre del valor	Tipo de valor	Descripción
job_id	string	ID del trabajo de impresión recién creado.
expires_in	int	Cantidad de segundos de validez de este trabajo de impresión.

Ejemplo:

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

5.1.3. Errores

La API de /privet/printer/createjob puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):

Error	Descripción
entrada_no válida	El ticket de impresión enviado no es válido.
impresora_ocupado	La impresora está ocupada y, por el momento, no puede procesar /createjob. Vuelve a intentarlo después del tiempo de espera.
error_impresora	La impresora se encuentra en estado de error y requiere interacción del usuario para corregirla. La descripción debe contener una explicación más detallada (por ejemplo, "Atasco de papel en la bandeja 1").
token_privado_x no válido	X-Privet-Token no es válido o está vacío en la solicitud.

Si el dispositivo no expone /privet/printer/createjob, DEBE mostrar el error HTTP 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.

5.2. API de /privet/printer/submitdoc

Se requiere la API de /privet/printer/submitdoc para implementar la impresión a través de una red local (sin conexión o volver a publicar en Cloud Print). Es una solicitud HTTP POST. La API de /privet/printer/submitdoc DEBE verificar un encabezado "&-Privet-Token" válido. El dispositivo DEBE implementar esta API en la URL"privet/printer/submitdoc":

POST /privet/printer/submitdoc HTTP/1.1

Cuando reciba la llamada a la API /privet/printer/submitdoc, la impresora debería comenzar a imprimir. Si no puede comenzar a imprimir, DEBE mostrar el error print_busy y un tiempo de espera recomendado para que el cliente espere antes de volver a intentarlo.

Si la impresora no puede contener todos los datos en su búfer interno, DEBE usar mecanismos de TCP para disminuir la velocidad de la transferencia de datos hasta que imprime una parte del documento, lo que permite que parte del búfer vuelva a estar disponible. (Por ejemplo, la impresora puede configurar windowsize=0 en las capas TCP, lo que hará que el cliente espere).

Enviar un documento a la impresora puede demorar bastante tiempo. El cliente debe poder verificar el estado de la impresora y del trabajo (impresión avanzada) mientras la impresión está en curso. Para ello, la impresora DEBE permitir que el cliente llame a las API /privet/info y /privet/printer/jobstate mientras procesa las llamadas a la API /privet/printer/submitdoc. Se recomienda que todos los clientes inicien un subproceso nuevo para ejecutar la llamada a la API /privet/printer/submitdoc, de modo que el subproceso principal pueda usar las API /privet/info y /privet/printer/jobstate para verificar los estados de las impresoras y los trabajos.

Nota: Después de completar o realizar el aborto del trabajo de impresión local, se recomienda (y se requerirá en una versión futura de esta especificación) informar el estado final del trabajo a la interfaz /cloudprint/submit para fines contables y de experiencia del usuario. Los parámetros "printerid", "title" y "contentType" y "final_semantic_state" (en formato PrintJobState) son obligatorios, y los parámetros "tag" (etiqueta repetida) y "ticket" del trabajo. Ten en cuenta que el PrintJobState proporcionado debe ser definitivo, es decir, su tipo debe ser DONE o ABORTED, y se debe proporcionar una causa en el caso de que sea ABORTED (consulta JobState para obtener más detalles). Además, ten en cuenta que el uso de la interfaz /cloudprint/submit para informar trabajos de impresión locales no se menciona en su especificación, ya que esa sección tiene como objetivo describir el uso principal de la interfaz: enviar un trabajo de impresión con el documento para imprimir proporcionado en el parámetro &content.

5.2.1. Entrada

La API de /privet/printer/submitdoc tiene los siguientes parámetros de entrada:

Nombre	Valor
job_id	(Opcional) ID de trabajo de impresión. Se puede omitir para casos de impresión simples (consulta arriba). Debe coincidir con el que muestra la impresora.
nombre_usuario	(Opcional) Nombre de usuario legible. Esto no es definitivo y solo se debe usar para las anotaciones del trabajo de impresión. Si el trabajo se vuelve a publicar en el servicio de Cloud Print, esta string debería adjuntarse al trabajo de Cloud Print.
nombre_cliente	(Opcional) Nombre de la aplicación cliente que realiza esta solicitud. Solo con fines de visualización. Si el trabajo se vuelve a publicar en el servicio de Cloud Print, esta string se debe adjuntar al trabajo de Cloud Print.
nombre_trabajo	(Opcional) Nombre del trabajo de impresión que se registrará. Si el trabajo se vuelve a publicar en el servicio de Cloud Print, esta string se debe adjuntar al trabajo de Cloud Print.
sin conexión	(Opcional) Solo se puede "offline=1". En este caso, la impresora solo debe intentar imprimir sin conexión (no se puede volver a publicar en el servidor de Cloud Print).

El cuerpo de la solicitud debe contener un documento válido para imprimir. "Content-Length" debe incluir la longitud correcta de la solicitud. El encabezado "Content-Type" debe configurarse para documentar el tipo de MIME y coincidir con uno de los tipos en el CDD (a menos que CDD especifique "*/*").

Recomendamos a los clientes proporcionar un nombre de usuario (o correo electrónico) válido, un nombre de cliente y un nombre de trabajo con esta solicitud. Esos campos solo se usan en las IU para mejorar la experiencia del usuario.

5.2.2. Volver

La API de /privet/printer/submitdoc muestra los siguientes datos:

Nombre del valor	Tipo de valor	Descripción
job_id	string	ID del trabajo de impresión recién creado (impresión simple) o job_id especificado en la solicitud (impresión avanzada).
expires_in	int	Cantidad de segundos de validez de este trabajo de impresión.
tipo_trabajo	string	Es el tipo de contenido del documento enviado.
tamaño_trabajo	int 64 bits	Tamaño de los datos de impresión en bytes.
nombre_trabajo	string	(Opcional) El mismo nombre de trabajo que en la entrada (si corresponde).

Ejemplo:

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

5.2.3. Errores

La API de /privet/printer/submitdoc puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):

Error	Descripción
trabajo_impreso_no válido	Se especificó un ID de trabajo no válido o vencido en la solicitud. Vuelve a intentarlo después del tiempo de espera.
tipo_documento_no válido	La impresora no admite el tipo de MIME del documento.
documento_no válido	El documento enviado no es válido.
demasiado_documento_grande	El documento supera el tamaño máximo permitido.
impresora_ocupado	La impresora está ocupada y no puede procesar el documento en este momento. Vuelve a intentarlo después del tiempo de espera.
error_impresora	La impresora se encuentra en estado de error y requiere interacción del usuario para corregirla. La descripción debe contener una explicación más detallada (por ejemplo, "Atasco de papel en la bandeja 1").
parámetros_no válidos	Los parámetros especificados en la solicitud no son válidos. (Se deben ignorar de manera segura los parámetros desconocidos para garantizar la compatibilidad en el futuro).
cancelar_usuario	El usuario canceló explícitamente el proceso de impresión desde el dispositivo.
error_servidor	Se produjo un error al publicar el documento en Cloud Print.
token_privado_x no válido	X-Privet-Token no es válido o está vacío en la solicitud.

Si el dispositivo no expone /privet/printer/submitdoc, DEBE mostrar el error HTTP 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.

Nota: Es posible que la API de /privet/printer/submitdoc requiera un manejo especial del lado de la impresora (debido a la gran carga útil adjunta). En algunos casos (depende de la implementación y la plataforma del servidor HTTP de la impresora), la impresora puede cerrar el socket ANTES de mostrar el error HTTP. En otros casos, la impresora puede mostrar el error 503 (en lugar del error de Privet). Las impresoras DEBEN hacer todo lo posible para devolver Privet. Sin embargo, cada cliente que implemente la especificación de Privet DEBE poder manejar el cierre de socket (sin error de HTTP) y los casos de error de HTTP 503 para la API de /privet/printer/submitdoc. En este caso, el cliente DEBERÍA manejarlo como un error de Privet “printer_busy” con un tiempo de espera de 15 segundos. Para evitar los reintentos infinitos, es posible que el cliente deje de reintentar después de una cantidad razonable de intentos (por ejemplo, 3).

5.3. API de /privet/printer/jobstate

/privet/printer/jobstate API es OPCIONAL (consulte Impresión simple más arriba). Es una solicitud HTTP GET. La API de /privet/printer/jobstate DEBE verificar que el encabezado X-Privet-Token sea válido. El dispositivo DEBE implementar esta API en la URL "/privet/printer/jobstate"

GET /privet/printer/jobstate HTTP/1.1

Cuando reciba una llamada a la API /privet/printer/jobstate, una impresora debería mostrar el estado del trabajo de impresión solicitado o de un error invalid_print_job.

5.3.1. Entrada

La API de /privet/printer/jobstate tiene los siguientes parámetros de entrada:

Nombre	Valor
job_id	ID de trabajo de impresión para el que se muestra el estado.

5.3.2. Volver

La API de /privet/printer/jobstate muestra los siguientes datos:

Nombre del valor	Tipo de valor	Descripción
job_id	string	La información de estado del ID de trabajo de impresión es.
state	string	borrador: Se creó un trabajo de impresión en el dispositivo (aún no se recibieron llamadas a /privet/printer/submitdoc). En cola: el trabajo de impresión se recibió y se puso en cola, pero aún no comenzó la impresión. in_progress: el trabajo de impresión está en progreso de impresión. detenido: el trabajo de impresión se detuvo, pero se puede reiniciar de forma manual o automática. done: el trabajo de impresión está listo. abortado: se produjo un error en el trabajo de impresión.
descripción	string	(Opcional) Descripción legible del estado del trabajo de impresión. Deben incluir información adicional si state se detiene o se anula. Por lo general, el campo semantic_state proporciona una descripción mejor y más significativa al cliente.
expires_in	int	Cantidad de segundos de validez de este trabajo de impresión.
tipo_trabajo	string	(Opcional) Tipo de contenido del documento enviado.
tamaño_trabajo	int 64 bits	(Opcional) Tamaño de los datos de impresión en bytes.
nombre_trabajo	string	(Opcional) El mismo nombre de trabajo que en la entrada (si corresponde).
id_trabajo_servidor	string	ID (opcional) del trabajo que muestra el servidor (si el trabajo se publicó en el servicio de Cloud Print). Se omite para la impresión sin conexión.
estado_semántico	JSON	Es un estado semántico del trabajo en formato PrintJobState (opcional).

Ejemplo (impresión mediante informes con 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"
}

Ejemplo (error de impresión sin conexión):

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

Ejemplo (trabajo de impresión anulado por el usuario):

{
        "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
        }
}

Ejemplo (trabajo de impresión detenido debido a que no hay papel). Observa la referencia al estado del dispositivo. El cliente deberá llamar a la API de /privet/info para obtener más detalles sobre el estado del dispositivo:

{
        "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. Errores

La API de /privet/printer/jobstate puede mostrar los siguientes errores (consulta la sección Errores para obtener más detalles):

Error	Descripción
trabajo_impreso_no válido	Se especificó un ID de trabajo no válido o vencido en la solicitud.
error_servidor	Se produjo un error al obtener el estado del trabajo de impresión (para trabajos de impresión publicados en Cloud Print).
token_privado_x no válido	X-Privet-Token no es válido o está vacío en la solicitud.

Si el dispositivo no expone /privet/printer/jobstate, DEBE mostrar el error HTTP 404. Si falta el encabezado X-Privet-Token, el dispositivo DEBE mostrar el error HTTP 400.

6. Apéndice

6.1. Comportamiento y configuración predeterminados

En esta sección, se explica el comportamiento predeterminado que esperamos de TODOS los dispositivos compatibles con Privet.

Los dispositivos listos para usar solo deben admitir las API /privet/info y /privet/register. Se deben inhabilitar todas las demás API (p.ej., /privet/accesstoken), impresión local.
El registro requiere interacción física con un dispositivo.

El usuario DEBE realizar una acción física en el dispositivo (p.ej., presionar un botón) para confirmar su acceso.
Después de que el usuario realiza la acción indicada anteriormente, la impresora debe enviar la solicitud /cloudprint/register. No debería enviar esta solicitud hasta después de que se realice la acción (consulta el diagrama de secuencia 1).
Si el dispositivo está procesando una solicitud /privet/register (por ejemplo, esperando la acción anterior), debe rechazar todas las demás solicitudes /privet/register. En este caso, el dispositivo DEBE mostrar el error device_busy.
El dispositivo debe agotar cualquier solicitud de /register que no reciba la acción física mencionada anteriormente en un plazo de 60 segundos. En este caso, el dispositivo DEBE mostrar el error confirm_timeout.
Opcional: Se recomienda, pero no es obligatorio que lo siguiente pueda mejorar la experiencia del usuario:

Es posible que la impresora encienda una luz o la pantalla para indicar que el usuario debe realizar una acción para confirmar el registro.
Es posible que la impresora indique en la pantalla que "se está registrando en Google Cloud Print para el usuario "abc@def.com"; presiona Aceptar para continuar, donde abc@def.com es el parámetro del usuario de la llamada a la API /register. Esto le dejaría más claro a un usuario lo siguiente:

es la solicitud de registro que confirman
qué sucede si no activa la solicitud;

Además de una acción física para confirmar desde la impresora (p.ej., "Presiona el botón Aceptar", es posible que una impresora también le ofrezca un botón para cancelar la solicitud (p.ej., “Presiona Cancelar para rechazar”). Esto permitiría a los usuarios que no activaron la solicitud de registro cancelarla antes del tiempo de espera de 60 segundos. En este caso, el dispositivo DEBE mostrar el error user_cancel.

Transferencias de propiedad:

El dispositivo se puede borrar explícitamente del servicio de Cloud.

Si el dispositivo recibe el resultado correcto, pero no tiene una descripción como resultado de la llamada con /cloudprint/printer (para GCP), DEBE revertir al modo predeterminado (lista para usar).
Si las credenciales del dispositivo ya no funcionan (explícitamente debido a una respuesta "no válida" del servidor), DEBE volver al modo predeterminado (lista para usar).

El restablecimiento de la configuración de fábrica local DEBE borrar las credenciales del dispositivo y establecer el estado predeterminado.
Opcional: El dispositivo puede proporcionar un elemento de menú para borrar las credenciales y ponerlo en modo predeterminado.

Los dispositivos que admiten notificaciones XMPP DEBEN incluir la capacidad de hacer ping al servidor. El tiempo de espera de ping DEBE controlarse desde el servidor mediante &local;settings.
El dispositivo puede hacer ping de forma explícita en el servidor (API de /cloudprint/impresora para GCP, además de pings XMPP) no más de una vez al día (24 horas) para asegurarse de que estén sincronizados. Se recomienda aleatorizar la ventana de verificación dentro de un período de 24 a 32 horas.
Opcional: Para los dispositivos de Cloud Print, se recomienda tener una forma manual (botón) de permitir que el usuario inicie una verificación de nuevos trabajos de impresión desde el dispositivo, pero no es obligatorio. Algunas impresoras ya lo tienen.
Opcional. Es posible que las impresoras empresariales tengan una opción para inhabilitar completamente el descubrimiento local. En ese caso, el dispositivo DEBE actualizar esta configuración local en el servidor. La nueva configuración local DEBE estar vacía (configurar “local_discovery” como “false”), lo que significa que se puede volver a habilitar desde el servicio de GCP.

6.1.2 Diagrama de registro predeterminado

6.2. Prevención y ataques de XSSI y XSRF

En esta sección, se explicará la posibilidad de que se produzcan ataques de XSSI y XSRF en el dispositivo, y se explica cómo protegerlos de ellos (incluidas las técnicas de generación de tokens).
Puedes obtener más información en el siguiente vínculo: http://googleonlinesecurity.blogspot.com/2011/05/website-security-for-webmasters.html
Por lo general, los ataques de XSSI y XSRF son posibles cuando un sitio usa mecanismos de autenticación de cookies. Si bien Google no utiliza cookies con el servicio Cloud Print, estos ataques aún son posibles. El diseño de acceso a la red local confía implícitamente en las solicitudes.

6.2.1. XSSI

Es posible que un sitio web malicioso adivine la dirección IP y el número de puerto de un dispositivo compatible con Privet y que intente llamar a la API de Privet con una etiqueta &ltt;src=<api name>" dentro de una etiqueta <script>:

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

Sin protección, los sitios web maliciosos podrían ejecutar llamadas a la API y acceder a los resultados.
Para evitar este tipo de ataque, TODAS las llamadas a la API de Privet DEBEN solicitar el encabezado “X-Privet-Token” en la solicitud. Las etiquetas de secuencia de comandos no pueden agregar encabezados para protegerse contra este tipo de ataques.

6.2.2. XSRF

http://en.wikipedia.org/wiki/Cross-site_request_forgery
Un sitio web malicioso puede adivinar la dirección IP y el número de puerto de un dispositivo compatible con Privet e intentar llamar a la API de Privet con un <iframe>, formularios o algún otro mecanismo de carga entre sitios web. Los atacantes no podrían acceder a los resultados de la solicitud, pero si esta realizaría una acción (p.ej., la impresión), podría activarla.

Para evitar este ataque, necesitamos la siguiente protección:

Deja la API de /privet/info abierta en XSRF
/privet/info API NO DEBE realizar ninguna acción en el dispositivo
Usa la API de /privet/info para recibir el token x-privet
Todas las demás API DEBEN buscar un token x-privet válido en el encabezado "X-Privet-Token".
El token "x-privet" DEBE ser válido únicamente durante 24 horas.

Incluso si un atacante puede ejecutar la API /privet/info, no podría leer el token x-privet de la respuesta y, por lo tanto, no podría llamar a ninguna otra API.

Se recomienda generar el token XSRF con el siguiente algoritmo:

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

Elementos de generación del token XSRF:

DELIMITER es un carácter especial, generalmente ":"
issue_timecounter es una cantidad de segundos desde que algún evento (ciclo de entrenamiento para la marca de tiempo) o tiempo de inicio del dispositivo (para contadores de CPU) issue_timecounter aumenta constantemente cuando el dispositivo está en funcionamiento (consulta la verificación de token a continuación).
SHA1: función hash que usa el algoritmo SHA1
base64: codificación en base64
device_secret: el secreto específico del dispositivo El secreto del dispositivo DEBE actualizarse cada vez que se reinicia.

Formas recomendadas para generar un secreto de dispositivo:

Genera un UUID nuevo en cada reinicio
Genera un número aleatorio de 64 bits con cada reinicio

No es necesario que el dispositivo almacene todos los tokens XSRF emitidos. Cuando el dispositivo necesita verificar un token XSRF para su validez, debe decodificar el token en base64. Obtén el issue_timecounter de la segunda mitad (cleartext) e intenta producir el hash SHA1 de device_secret + DELIMITER + issue_timecounter donde issue_timecounter es del token. Si la SHA1 generada recientemente coincide con la del token, el dispositivo ahora debe verificar si el issue_timecounter está dentro del período de validez de (24 horas) del contador de tiempo actual. Para ello, el dispositivo toma el contador de tiempo actual (por ejemplo, el contador de CPU) y resta issue_timecounter a él. El resultado DEBE ser la cantidad de segundos desde la emisión del token.

Importante: Esta es la manera recomendada de implementar la protección XSRF. Los clientes de la especificación Privet no intentarán comprender el token XSRF; en su lugar, lo tratarán como una caja negra. En la figura 6.2.3, se ilustra una forma recomendada de implementar el token X-Privet y la verificación de una solicitud típica.

6.2.3 Diagrama de secuencia de generación y token de X-Privet

6.3 Diagramas de flujo de trabajo

En esta sección, se ilustrará un flujo de trabajo en diferentes casos.

6.3.1. Flujo de trabajo de impresoras listo para usar

6.3.2. Inicio de la impresora registrada

6.3.3 Flujo de trabajo para el manejo de notificaciones de XMPP

6.3.4. Comprobar el flujo de trabajo de la configuración de la impresora