/*
 * Licensed to OMTP Ltd. (OMTP) under one or more contributor license agreements.
 * See the NOTICE file distributed with this work for additional information regarding
 * copyright ownership.
 *
 * The Reference Implementation (save for such parts of the reference implementation made
 * available under separate terms and conditions) is made available under the terms of the
 * Apache License, version 2.0, subject to the condition that any "Works" and "Derivative
 * Works" used or distributed for commercial purposes must be and remain compliant with the
 * BONDI specification as promulgated by OMTP in each release. Your implementation of the
 * Reference Implementation (whether object or source) must maintain these conditions, and
 * you must notify any recipient of this condition in a conspicuous way.
 *
 * You may not use this BONDI Reference Implementation except in compliance with the License.
 *
 * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 or at
 * http://bondi.omtp.org/BONDI-LICENSE-2.0
 */

/**
 * \brief Sensor API
 * Sensors are classified by type. Sensor type names are defined Strings, and
 * creation new type names must be centrally defined (by the owner of this API
 * definition).
 * 
 * There is a Feature defined for each specific sensor type. 
 * as follows:
 * \def-api-feature http://bondi.omtp.org/api/sensor/type
 * 
 * where type is a defined Sensor type.
 *
 * \author Paddy Byers paddy@aplix.co.jp
 * \version 1.5
 */
module sensor {

	typedef sequence<Sensor> SensorArray;

	interface SensorValue {

	};

	interface SensorReadCallback {
		void onSensorRead(in SensorValue sensorValue);
	};

	/**
	 * An abstract class representing the capabilities of a sensor.
	 * 
	 * This is expected to be subclasses for each specific sensor type.
	 */
	interface SensorCapabilities {

	};

	/**
	 * An abstract class representing a set of conditions, triggers or thresholds
	 * associated with sensors.
	 * 
	 * This is expected to be subclassed for specific sensor types where it is not
	 * convenient to express relevant conditions as a DOMString.
	 */
	interface SensorCondition {

	};

	/**
	 * The Sensor class is an abstract class that represents a general sensor.
	 * Specific sensor types do not necessarily extend this API, but will typically
	 * define specific types for sensor-specific aspects of the interface, such as
	 * - a sensor-specific value type representing the data returned when the sensor is read,
	 *   extending SensorValue;
	 * - a sensor-specific value type representing the specific capabilities of the sensor,
	 *   extending SensorCapabilities;
	 * - a sensor-specific condition type, representing specific conditions, triggers and
	 *   thresholds for reading the sensor asynchronously, extending SensorCondition
	 */
	interface Sensor {
		/**
		 * Pre-defined Sensor types
		 */
		const unsigned short SENSOR_TYPE_ACCELEROMETER       = 0; /* "accelerometer" */
		const unsigned short SENSOR_TYPE_AMBIENT_TEMPERATURE = 1; /* "ambient-temperature" */
		const unsigned short SENSOR_TYPE_ALTIMETER           = 2; /* "altimeter" */
		const unsigned short SENSOR_TYPE_AMBIENT_LIGHT       = 3; /* "ambient-light" */

		/**
		 * Get the type of this Sensor
		 * This is one of the known sensor type strings
		 */
		DOMString getType();

		/**
		 * Get the name of this Sensor
		 * For most sensors, the name is simply the type DOMString.
		 * However, if a device has multiple Sensors of the sale type, the name
		 * may be used to distinguish between specific sensors
		 * (eg two different attitude sensing devices, one for each half of a
		 * clamshell device)
		 */
		DOMString getName();

		/**
		 * Get the capabilities of this Sensor.
		 * The object returned is of a specific subclass of SensorCapabilities appropriate to
		 * the type of sensor in question
		 */
		SensorCapabilities getCapabilities();

		/**
		 * Read the current value of the Sensor asynchronously.
		 * If no condition is specified, this will return the current reading of the sensor
		 * as soon as it is available.
		 * If a condition is specified, the operation will complete once the condition is satisfied.
		 * The condition DOMString is optional and specifies sensor-specific condition(s),
		 * in a sensor-specific syntax.
		 */
		PendingOperation read(in SensorReadCallback successCallback,
				      in ErrorCallback errorCallback,
				      in DOMString condition);

		/**
		 * Read the current value of the Sensor asynchronously.
		 * If no condition is specified, this will return the current reading of the sensor
		 * as soon as it is available.
		 * If a condition is specified, the operation will complete once the condition is satisfied.
		 * The Condition object is optional and specifies sensor-specific condition(s),
		 * in a sensor-specific subtype of SensorCondition.
		 */
		PendingOperation read(in SensorReadCallback successCallback,
				      in ErrorCallback errorCallback,
				      in SensorCondition condition);

		/**
		 * Watch this sensor and listen for changes in value.
		 * This method is supported only for discrete sensors, or continuous sensors that support
		 * Conditions with thresholds that ensure a minimum distance or time delay between readings
		 * Each successfully read value that satisfies the condition results in the listener being called.
		 * 
		 * The Condition object is optional and specifies sensor-specific condition(s),
		 * in a sensor-specific subtype of SensorCondition. This is intended to be used in situations
		 * where sensor-specific conditions are not easily specified as a DOMString.
		 * 
		 * Multiple listeners may be active at any time.
		 */
		long watch(in SensorReadCallback listener,
			   in SensorCondition condition);

		/**
		 * Clear a previously registered watch
		 */
		void clearWatch(in long watch);
	};

	interface AccelerometerCapabilities : SensorCapabilities {
		/** indicates whether or not the sensor can measure acceleration on x axis */
		attribute boolean xSupported;
		
		/** indicates whether or not the sensor can measure acceleration on x axis */
		attribute boolean ySupported;

		/** indicates whether or not the sensor can measure acceleration on x axis */
		attribute boolean zSupported;

		/** indicates sensor resolution in x axis in m/s/s */
		attribute double xResolution;

		/** indicates sensor resolution in y axis in m/s/s */
		attribute double yResolution;

		/** indicates sensor resolution in z axis in m/s/s */
		attribute double zResolution;
	};

	interface AccelerometerValue : SensorValue {

		/** x axis acceleration measured in m/s/s */
		attribute double x;

		/** y axis acceleration measured in m/s/s */
		attribute double y;

		/** z axis acceleration measured in m/s/s */
		attribute double z;
	};

	/**
	 * A class representing an accelerometer measuring
	 * acceleration on up to 3 axes.
	 */
	interface Accelerometer : Sensor {

		/**
		 * Returns AccelerometerCapabilities
		 */
		SensorCapabilities getCapabilities();
		
		/**
		 * Conditions are not supported for Accelerometer
		 */
		PendingOperation read(in SensorReadCallback successCallback,
				      in ErrorCallback errorCallback,
				      in DOMString condition);

		/**
		 * Conditions are not supported for Accelerometer
		 */
		PendingOperation read(in SensorReadCallback successCallback,
				      in ErrorCallback errorCallback,
				      in SensorCondition condition);

		/**
		 * Watching accelerometer is not supported
		 */
		void watch(in SensorReadCallback listener,
			   in SensorCondition condition)
			raises(GenericError);

		/**
		 * Watching accelerometer is not supported
		 */
		void clearWatch(in SensorReadCallback listener)
			raises(GenericError);

		DOMString getName();

		DOMString getType();
	};

	/**
	 * The top-level class that provides access to the sensors on a device.
	 */
	interface SensorManager {
		/**
		 * Obtain an instance of a Sensor of specified type.
		 * 
		 * For most sensor types, there is at most one sensor available, and the
		 * params argument is ignored.
		 * 
		 * However, if there are multiple sensors of a given type, the params argument
		 * may be used to select a specific sensor.
		 * 
		 * A SensorManager at least supports "name" as a parameter, which will select
		 * from available sensors based on the name of the particular sensor.
		 * 
		 * Other parameters may be supported, and may be specific to a sensor type.
		 *
		 * This is associated with Feature:
		 * http://bondi.omtp.org/api/sensor/sensorType
		 */
		Sensor getSensor(in DOMString sensorType,
				 in Map params);

		/**
		 * Return an array of all available Sensors.
		 *
		 * This is associated with Feature:
		 * http://bondi.omtp.org/api/sensor
		 */
		SensorArray getSensors();
	};

};