CheckForUpdates

L'API /osc/checkForUpdates identifie les mises à jour de l'état en comparant la dernière valeur stateFingerprint connue du client à la valeur fingerprint actuelle de la caméra.

Entrée

Nom Type Description
stateFingerprint Chaîne Empreinte numérique de l'état de l'appareil photo utilisée pour la dernière fois que le client a appelé /osc/state ou /osc/checkForUpdates.
waitTimeout Entier (facultatif) Nombre de secondes d'attente du changement d'état de la caméra avant de renvoyer la réponse. Lorsque waitTimeout expire, l'appareil photo doit renvoyer une réponse même si l'empreinte digitale n'a pas changé. Si un changement d'état est détecté avant l'expiration de waitTimeout, ou si waitTimeout est omis, la caméra doit immédiatement renvoyer la réponse.Remarque:la caméra peut renvoyer une réponse avant l'expiration de waitTimeout, même si l'empreinte digitale n'a pas changé. Toutefois, il est recommandé d'attendre que waitTimeout expire.

Remarques sur l'implémentation de la caméra:

  • À la réception de cet appel, la caméra compare son empreinte numérique d'état actuel au paramètre stateFingerprint reçu. Si l'empreinte a changé, elle doit renvoyer immédiatement la nouvelle empreinte.

Sortie

Nom Type Description
stateFingerprint Chaîne Nouvelle empreinte de l'état de l'appareil photo (comme dans l'API /osc/state).
throttleTimeout Entier Nombre de secondes recommandé pour que le client attende avant le prochain appel checkForUpdates. Les clients peuvent envoyer des requêtes avant l'expiration de throttleTimeout. Si possible, les caméras doivent autoriser ces requêtes anticipées.

Remarques concernant l'implémentation chez le client:

  • Après avoir reçu une réponse, le client doit comparer le stateFingerprint reçu avec sa copie. Si ce n'est pas le cas, le client doit demander l'état actuel de la caméra à l'aide de l'API _/osc/state.
  • Les clients intelligents limitent les requêtes, quelle que soit la réponse de la caméra. Par exemple, si une caméra renvoie une réponse non standard (immédiatement, avec aucune modification et une valeur throttleTimeout) faible ou nulle), le client doit imposer son propre throttleTimeout avant de demander un autre checkForUpdates à la caméra.

Remarques sur l'implémentation de la caméra:

  • Lorsqu'il répond à checkForUpdates, l'appareil photo doit déterminer une throttleTimeout raisonnable. Si la caméra est compatible avec une logique de requête de longue durée (ne répond qu'après waitTimeout si l'état n'a pas changé), vous pouvez renvoyer throttleTimeout en tant que 0. Dans ce cas, les clients peuvent demander immédiatement des mises à jour.
  • Si la caméra n'accepte que les réponses rapides (déconseillé), elle doit renvoyer une valeur throttleTimeout raisonnable pour éviter un trafic constant de requête/réponse avec le client. Par exemple, une throttleTimeout raisonnable serait de 60 secondes, pour permettre une requête client par minute.
  • La bonne pratique consiste à renvoyer un throttleTimeout adapté aux capacités de la caméra. Si le serveur ne parvient pas à identifier un throttleTimeout approprié en raison d'un problème, la caméra doit renvoyer un code d'état 5XX et un corps JSON contenant un code d'erreur serverError.

Erreur

Code d'erreur Description
missingParameter stateFingerprint n'est pas spécifié.
invalidParameterName Un ou plusieurs noms de paramètres d'entrée ne sont pas reconnus.
invalidParameterValue Les noms des paramètres sont reconnus, mais une ou plusieurs valeurs ne sont pas valides. Par exemple, waitTimeout n'est pas autorisé ou son type est incorrect.
serverError Le serveur n'a pas pu déterminer une valeur throttleTimeout appropriée pour sa réponse. L'erreur serveur est identifiée par la valeur 5XX renvoyée dans la réponse. Les fabricants de caméras doivent fournir un tableau contenant les codes 5XX et les états de serveur correspondants qui peuvent générer cette erreur.

Exemple
Requête 
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
}
Réponse 
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
}
Requête 
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
}
Réponse 
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."
    }
}