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." } } ``` |