camera.listFiles

Lists all images/all videos/all images and videos in the camera. It might take several requests to list all files. This command was added in API level 2.

If a camera doesn’t support the requested parameters, the camera must return the maximum capability available for the hardware. For example, a rare case might be the request: {entryCount: 500, maxSize: 2000}. Instead of throwing an error, the response should be based on the maximum capability supported by the camera, such as: {entryCount: 100, maxSize: 200}. Please throw errors for all other cases; for example, when the request is, {entryCount: 500, maxSize: -500}, it should throw the error invalidParameterValue since maxSize is negative.

Parameters

  • fileType: Type of the files to be listed, should be any of the three: “image”, ”video”, ”all”.
  • startPosition: (Optional) The position of the first file to be returned in the list. If omitted, start position is 0, which represents the first file. If it is larger than the position of the last file, return a normal response with empty entries in results instead of an error response.
  • entryCount: Desired number of entries to return. If it is more than the number of remaining files, just return a normal response with the actual files remaining instead of an error response.
  • maxThumbSize: Maximum size of thumbnail images; max(thumbnail_width, thumbnail_height). It is set to null when the client wants to omit thumbnail images from the result.

Results

  • entries: A list of image properties. Each entry should contain the following fields except for latitude and longitude, which are optional:
    • name: Name of the file.
    • fileUrl: Absolute URL of the file, which can be used to download from the camera directly.
    • size: Size in bytes of the file.
    • dateTimeZone: Date, time, and time zone for the file, in the format: YYYY:MM:DD HH:MM:SS+(-)HH:MM. Use 24-hour format for the time. Date and time are separated by one blank character. Time zone is offset from UTC time. Please note this represents the ending of the capture for videos.
    • lat: (Optional) Latitude of the location at the time of file capture.
    • lng: (Optional) Longitude of the location at the time of file capture.
    • width: Width of the image or each video frame.
    • height: Height of the image or each video frame.
    • thumbnail: Base64 encoded string for thumbnail image of the file (when maxThumbSize != null).
    • isProcessed: A boolean value indicating if the file is processed (e.g. stitched) or it is only a preview. This should be true by default unless delayProcessing is set to true. If a processed image exists, the corresponding preview image shouldn’t be listed even if it exists, otherwise, list the preview image.
    • previewUrl: Default to empty string if delayProcessing is not supported or when isProcessed equals false or when preview image was never generated as an intermediate result, otherwise, it is the URL of the preview image corresponding to the final image. This is used to build the correspondence between the preview image and the final image.
  • totalEntries: Total number of entries of fileType in storage, e.g. if fileType is "image", it is the total number of images in storage.

Errors

  • missingParameter: Any required parameter is not specified; for example, entryCount is not specified.
  • invalidParameterName: The input parameter name is unrecognized.
  • invalidParameterValue: The input parameter name is recognized, but its value is invalid; for example, the entryCount is negative or its data type is incorrect.

Command I/O
Command Input 
{
    "parameters": {
        "entryCount": 50,
        "maxThumbSize": 100
    }
}
Command Output 
{
    "results": {
        "entries": [
            {
                "name": "abc",
                "fileUrl": "file URL",
                "size":  file size, # of bytes,
                "dateTimeZone": "2014:12:27 08:00:00+08:00",
                "lat": 50.5324,
                "lng": -120.2332,
                "width": 2000,
                "height": 1000,
                "thumbnail": "ENCODEDSTRING",
                "isProcessed": true,
                "previewUrl": ""
            }
            ...
            {
                ...
            }
        ],
        "totalEntries": 250
    }
}
Command Output (Error) 
{
    "error": {
        "code": "invalidParameterValue",
        "message": "Parameter entryCount is negative."
    }
}