CheckForUpdates

The /osc/checkForUpdates API identifies state updates by comparing the client’s last known stateFingerprint to the camera’s current fingerprint.

Input

Name Type Description
stateFingerprint String Camera state fingerprint from the last time the client called /osc/state or /osc/checkForUpdates.
waitTimeout Integer (optional) Number of seconds to wait for state change on the camera to occur before returning the response. When waitTimeout expires, the camera should return a response even if the fingerprint hasn’t changed. If a state change is detected before waitTimeout expires, or if waitTimeout is omitted, the camera should immediately return the response.Note: the camera can return a response before waitTimeout has expired even if the fingerprint hasn’t changed, but the best practice is to wait until waitTimeout expires.

Camera implementation notes:

  • Upon receiving this call, the camera compares its current state fingerprint with the received stateFingerprint parameter. If the fingerprint has changed, the camera must immediately return the new fingerprint.

Output

Name Type Description
stateFingerprint String New fingerprint of the camera state (same as in /osc/state API).
throttleTimeout Integer Recommended number of seconds for client to wait before next checkForUpdates call. Clients can make requests before throttleTimeout expires, and cameras should allow these early requests if possible.

Client implementation notes:

  • Upon receiving a response, the client should compare the received stateFingerprint with its copy. If they don’t match, the client should request the camera’s current state using the _/osc/state API.
  • Smart clients will throttle requests regardless of the camera response. For example, if a camera returns a non-standard response (immediately, with no change and a low or 0 throttleTimeout), the client should impose its own throttleTimeout before requesting another checkForUpdates from the camera.

Camera implementation notes:

  • When responding to checkForUpdates, the camera should determine a reasonable throttleTimeout. If the camera supports long standing request logic (respond only after waitTimeout if state hasn’t changed), it is OK to return throttleTimeout as 0. In this case, clients can immediately request updates.
  • If the camera supports only fast responses (not recommended), it should return a reasonable throttleTimeout to avoid constant request/response traffic with the client. For example, a reasonable throttleTimeout would be 60 seconds, to allow one client request per minute.
  • The best practice is to return a throttleTimeout appropriate for the camera’s capabilities. If the server cannot determine an appropriate throttleTimeout due to a server issue, the camera should respond with a 5XX status code and a JSON body containing serverError error code.

Error

Error code Description
missingParameter stateFingerprint is not specified.
invalidParameterName One or more input parameter names is unrecognized.
invalidParameterValue The parameter names are recognized, but one or more values is invalid; for example, waitTimeout is out of range or its type is incorrect.
serverError The server was unable to determine an appropriate throttleTimeout value for its response. The server problem will be identified by the 5XX value returned in the response. Camera manufacturers should supply a table of 5XX codes and corresponding server states that can throw this error.

Example
Request 
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
}
Response 
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
}
Request 
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
}
Response 
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."
    }
}