CheckForUpdates

La API de /osc/checkForUpdates identifica las actualizaciones de estado comparando el último stateFingerprint conocido del cliente con el fingerprint actual de la cámara.

Entrada

Nombre Tipo Descripción
stateFingerprint String Huella digital del estado de la cámara desde la última vez que el cliente llamó a /osc/state o /osc/checkForUpdates.
waitTimeout Número entero (opcional) Cantidad de segundos que se debe esperar a que ocurra un cambio de estado en la cámara antes de devolver la respuesta. Cuando waitTimeout venza, la cámara debería mostrar una respuesta, incluso si no cambió la huella dactilar. Si se detecta un cambio de estado antes de que venza waitTimeout, o si se omite waitTimeout, la cámara debería mostrar la respuesta de inmediato.Nota: La cámara puede mostrar una respuesta antes de que waitTimeout venza, incluso si la huella digital no cambió, pero la práctica recomendada es esperar hasta que venza waitTimeout.

Notas sobre la implementación de la cámara:

  • Después de recibir esta llamada, la cámara compara su huella digital de estado actual con el parámetro stateFingerprint recibido. Si la huella digital cambió, la cámara debe devolver de inmediato la nueva huella digital.

Salida

Nombre Tipo Descripción
stateFingerprint String Nueva huella digital del estado de la cámara (igual que en la API de /osc/state).
throttleTimeout Número entero Cantidad de segundos recomendada que el cliente debe esperar antes de la próxima llamada a checkForUpdates. Los clientes pueden hacer solicitudes antes de que venza throttleTimeout, y las cámaras deben permitir estas solicitudes anticipadas si es posible.

Notas sobre la implementación del cliente:

  • Después de recibir una respuesta, el cliente debe comparar el stateFingerprint recibido con su copia. Si no coinciden, el cliente debe solicitar el estado actual de la cámara mediante la API de _/osc/state.
  • Los clientes inteligentes limitarán las solicitudes independientemente de la respuesta de la cámara. Por ejemplo, si una cámara muestra una respuesta no estándar (de inmediato, con sin cambios y un throttleTimeout) bajo o de 0, el cliente debe imponer su propio throttleTimeout antes de solicitar otro checkForUpdates a la cámara.

Notas sobre la implementación de la cámara:

  • Cuando se responde a checkForUpdates, la cámara debe determinar un throttleTimeout razonable. Si la cámara admite una lógica de solicitud de larga duración (si el estado no cambió, responde solo después de waitTimeout), puedes mostrar throttleTimeout como 0. En ese caso, los clientes pueden solicitar actualizaciones de inmediato.
  • Si la cámara solo admite respuestas rápidas (no se recomienda), debe mostrar un throttleTimeout razonable para evitar el tráfico constante de solicitudes o respuestas con el cliente. Por ejemplo, un throttleTimeout razonable serían 60 segundos para permitir una solicitud del cliente por minuto.
  • La práctica recomendada es devolver un objeto throttleTimeout adecuado para las capacidades de la cámara. Si el servidor no puede determinar un throttleTimeout adecuado debido a un problema del servidor, la cámara debería responder con un código de estado 5XX y un cuerpo JSON que contenga el código de error serverError.

Error

Código de error Descripción
missingParameter No se especificó stateFingerprint.
invalidParameterName No se reconocen uno o más nombres de parámetros de entrada.
invalidParameterValue Se reconocen los nombres de los parámetros, pero uno o más valores no son válidos. por ejemplo, waitTimeout está fuera del rango o su tipo es incorrecto.
serverError El servidor no pudo determinar un valor de throttleTimeout adecuado para su respuesta. El problema del servidor se identificará con el valor 5XX devuelto en la respuesta. Los fabricantes de cámaras deben proporcionar una tabla de códigos 5XX y los estados de servidor correspondientes que pueden arrojar este error.

Ejemplo
Solicitud 
POST /osc/checkForUpdates HTTP/1.1
Host: [camera ip address]:[httpUpdatesPort]
Content-Type: application/json;charset=utf-8
Accept: application/jsonContent-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1

{
    "stateFingerprint": "12EGA33",
    "waitTimeout": 300
}
Respuesta 
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff

{
    "stateFingerprint": "12EGA86",
    "throttleTimeout": 60
}
Solicitud 
POST /osc/checkForUpdates HTTP/1.1
Host: [camera ip address]:[httpUpdatesPort]
Content-Type: application/json;charset=utf-8
Accept: application/jsonContent-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1

{
    "stateFingerprint": "12EGA33",
    "waitTimeout": 300
}
Respuesta 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff

{
    "name": "camera.checkForUpdates",
    "state": "error",
    "error": {
        "code": "missingParameter",
        "message": "parameter stateFingerprint is missing."
    }
}