/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2011 Raritan Inc. All rights reserved.
 */

#include <UserEvent.idl>
#include <Webcam.idl>

/** Webcam Management */
module webcam {

    /** The storage manager interface */
    interface StorageManager_1_0_2 {
	/**
	 * Error codes
	 */
	constant int NO_ERROR			  = 0; ///< Operation successful, no error
	constant int ERR_INVALID_PARAM            = 1; ///< Invalid parameter for an operation
	constant int ERR_INIT_IN_PROGRESS         = 2; ///< Storage information is going to be initialized
	constant int ERR_ALREADY_RUNNING          = 3; ///< The activity is already running
	constant int ERR_TOO_LARGE                = 4; ///< The requested result is too large
	constant int ERR_OPERATION_NOT_SUPPORTED  = 5; ///< The requested operation is not supported on the current storage type

        /** StorageType */
        enumeration StorageType {
            LOCAL,    ///< Local
            FTP,      ///< FTP
            CIFS,     ///< CIFS
            NFS       ///< NFS
        };

        /** Direction */
        enumeration Direction {
            ASCENDING,            ///< ascending
            DESCENDING            ///< descending
        };

        /** StorageStatus */
        enumeration StorageStatus {
            INITIALIZING,         ///< Initializing is in progress,
            READY                 ///< Storage is ready for usage
        };

        /** Webcam Storage Info */
        structure WebcamStorageInfo {
            Webcam_2_0_1 webcam;   ///< webcam object
            long newestIndex;      ///< newest know index
            long oldestIndex;      ///< oldest know index
            int count;             ///< nr of stored images from this webcam
        };

        /** Information */
        structure StorageInformation {
            StorageStatus status;  ///< storage status
            int capacity;          ///< over-all nr of storable images
            int used;              ///< nr of stored images (local storage only)
            vector<WebcamStorageInfo> webcamStorageInfo; ///< List of storage information for each webcam (local storage only)
        };

        /** Settings */
        structure StorageSettings {
            StorageType type;      ///< storage type
            int capacity;          ///< maximum number of stored images; obsolete, no longer used
            string server;         ///< server ip, share and path (empty/ignored for LOCAL storage type)
            string username;       ///< username  (empty/ignored for LOCAL storage type)
            string password;       ///< password  (empty/ignored for LOCAL storage type)
        };

        /** StorageMetaData */
        structure StorageMetaData {
            long index;            ///< current image index
            Webcam_2_0_1 webcam;   ///< source webcam
        };

        /** StorageMetaData */
        structure ImageStorageMetaData {
            ImageMetaData imageMeta;    ///< image related meta data
	    int fileSize;               ///< image file size in bytes
            StorageMetaData storageMeta;///< store related meta data
        };

        /** StorageImage */
        structure StorageImage {
            Image_2_0_0 image;          ///< image object
            StorageMetaData metaData;   ///< meta data
        };

        /** Activity */
	structure Activity {
            Webcam_2_0_1 webcam;   ///< webcam object
            int interval;          ///< capture interval
            int count;             ///< nr of images to take
            int done;              ///< nr of images taken
	};

	/** Event: image upload to storage started */
	valueobject ImageUploadStartedEvent extends event.UserEvent {
            Webcam_2_0_1 webcam;   ///< webcam object
	    string folderUrl;      ///< URL under which the containing folder can be accessed
	};

        /**
	 * Get supported storage types
         *
         * @return a list of supported storage types
	 */
        vector<StorageType> getSupportedStorageTypes();

	/**
	 * get storage information
	 *
         * @return StorageInformation
	 */
	StorageInformation getInformation();

	/**
	 * get storage settings
	 *
         * @return StorageSettings
	 */
	StorageSettings getSettings();

	/**
	 * set storage settings
	 *
	 * @param  settings	        settings structure
         *
         * @return NO_ERROR             on success
         * @return ERR_INVALID_PARAM    invalid settings
	 */
	int setSettings(in StorageSettings settings);

	/**
	 * add an image to the storage
	 *
	 * @param  webcam	        image source webcam
	 * @param  image	        image
	 * @param  index	        index of the added image
         *
         * @return NO_ERROR             on success
	 */
	int addImage(in Webcam_2_0_1 webcam, in Image_2_0_0 image, out long index);

	/**
	 * remove an image of the storage
	 *
	 * @note not supported for remote storage (CIFS and FTP)
	 *
	 * @param  webcam	        image source webcam
	 * @param  start	        start index
	 * @param  count	        number of images
	 * @param  direction	        index counting direction
         *
         * @return NO_ERROR             on success
	 */
	int removeImages(in Webcam_2_0_1 webcam, in long start, in int count, in Direction direction);

	/**
	 * get meta data of images from storage
	 *
	 * @note not supported for remote storage (CIFS and FTP)
	 *
	 * @param  webcam	        image source webcam
	 * @param  start	        start index
	 * @param  count	        number of images
	 * @param  direction	        index counting direction
	 * @param  meta	                result: list of storage meta data
         *
         * @return NO_ERROR             on success
         * @return ERR_TOO_LARGE        too many information requested
	 */
	int getMetaData(in Webcam_2_0_1 webcam, in long start, in int count,
                        in Direction direction, out vector<ImageStorageMetaData> meta);

	/**
	 * retrieve images from the storage
	 *
	 * @note not supported for remote storage (CIFS and FTP)
	 *
	 * @param  webcam	        image source webcam
	 * @param  start	        start index
	 * @param  count	        number of images
	 * @param  direction	        index counting direction
	 * @param  image	        result: list of storage images
         *
         * @return NO_ERROR             on success
         * @return ERR_TOO_LARGE        too many images requested
	 */
	int getImages(in Webcam_2_0_1 webcam, in long start, in int count,
                      in Direction direction, out vector<StorageImage> image);

	/**
	 * get all running activities
         *
         * @return list of running activities
	 */
	vector<Activity> getActivities();

	/**
	 * start a capture activity
	 *
	 * @param  webcam	        webcam
	 * @param  count                number of images to store, zero is interpreted as infinite
	 * @param  interval             interval in ms
         *
         * @return NO_ERROR             on success
         * @return ERR_INVALID_PARAM    webcam not found
	 */
	int startActivity(in Webcam_2_0_1 webcam, in int count, in int interval);

	/**
	 * Start a capture activity, storing the images to a specific storage folder
	 *
	 * @param  webcam	        webcam
	 * @param  count                number of images to store, zero is interpreted as infinite
	 * @param  interval             interval in ms
	 * @param  folder               folder path to store the images into
         *
         * @return NO_ERROR             on success
         * @return ERR_INVALID_PARAM    webcam not found
	 */
	int startActivityWithFolder(in Webcam_2_0_1 webcam, in int count, in int interval, in string folder);

	/**
	 * stop a capture activity
	 *
	 * @param  webcam	        webcam
         *
         * @return NO_ERROR             on success
         * @return ERR_INVALID_PARAM    no matching activity found
	 */
	int stopActivity(in Webcam_2_0_1 webcam);
    };
}
