/*
 * 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 Common BONDI functionality.
 *
 * These definitions can be used in all other BONDI modules as dependencies.
  * \version 1.1
 */
module bondi {

	/**
	 * \brief Array of DOMStrings.
	 */
	typedef sequence<DOMString> StringArray;

	/**
	 * \brief Array of 8-bit unsigned integer values.
	 */
	typedef sequence<octet>     ByteArray;

	/**
	 * \brief Array of 16-bit signed integer values.
	 */
	typedef sequence<short>     ShortArray;

	/**
	 * \brief Array of 32-bit signed integer values.
	 */
	typedef sequence<long>      LongArray;

	/**
	 * \brief Array of floating point values.
	 */
	typedef sequence<float>     FloatArray;

	/**
	 * \brief Generic Map object.
	 */
	typedef Object              Map;

	/**
	 * \brief Generic success callback interface.
	 */
	[Callback=FunctionOnly, NoInterfaceObject] interface SuccessCallback {
	   /**
	    * \brief Method invoked when the asynchronous call completes successfully
	    */
		void onSuccess();
	};


	/**
	 * \brief Success callback interface for requestFeature invocations
	 */
    [Callback=FunctionOnly, NoInterfaceObject] interface RequestFeatureSuccessCallback {
       /**
	    * \brief Method invoked upon a succesful requestFeature invocation
	    *
	    * \param ob Object implementing the JavaScript API associated with the requested Feature.
	    */
        void onSuccess(in Object ob);
     };


	/**
	 * \brief Generic error callback interface.
	 */
	[Callback=FunctionOnly, NoInterfaceObject] interface ErrorCallback {
	   /**
	    * \brief Method invoked when an error occurs
	    *
	    * \param error The error that is raised.
	    */
		void onError(in GenericError error);
	};

	/**
	 * \brief Generic error interface.
	 *
	 * 
	 */


	interface GenericError {

		/**
		 * \brief 16-bit error code.
		 */
		readonly attribute unsigned short code;
	};
		
	/**
	 * \brief DeviceApiError error interface.
	 *
	 * The error codes must be in the range 10000-19999.
	 */

	interface DeviceAPIError : GenericError {

		/**
		 * \brief Unknown error.
		 */
		const unsigned short UNKNOWN_ERROR           = 10000;

		/**
		 * \brief Invalid value was specified as input parameter.
		 */
		const unsigned short INVALID_ARGUMENT_ERROR  = 10001;

		/**
		 * \brief The searched value or object was not found.
		 */
		const unsigned short NOT_FOUND_ERROR         = 10002;

		/**
		 * \brief Operation is pending.
		 */
		const unsigned short PENDING_OPERATION_ERROR = 10003;

		/**
		 * \brief Input/Output error.
		 */
		const unsigned short IO_ERROR                = 10004;

		/**
		 * \brief Not supported error.
		 */
		const unsigned short NOT_SUPPORTED_ERROR     = 10005;
	};

	/**
	 * \brief Security error interface.
	 *
	 * The error codes must be in the range 20000-29999
	 */
	interface SecurityError : GenericError {
		const unsigned short PERMISSION_DENIED_ERROR = 20000;
	};

	/**
	 * \brief PendingOperation.
	 *
	 * Interface that is returned by asynchronous operations in order to
	 * provide a cancellation operation.
	 */
	interface PendingOperation {
		/**
		 * \brief Call to cancel the underlying asynchronous operation.
		 *
		 * This call is always successful, i.e. the pending operation i.e.
		 * either cancelled or one of the callback is called.
		 *
		 * \return <em>false</em> if the cancellation did not succeed
		 * either because the pending operation finished already or because
		 * the cancellation cannot succeed due to technical limitations in
		 * the underlying implementation. Consquently the pending operation 
		 * completes and depending on the success or failure the appropriate
		 * callbacks will be called.
		 * <em>true</em> if the cancellation did succeed. No callbacks will
		 * be called by the cancelled pending operation.
		 */
		boolean cancel();
	};

	/**
	 * \brief BONDI root API.
	 * bondi root property exists in the global object
	 * \def-api-feature http://bondi.omtp.org/api/bondi.requestfeature
	 */
	interface Bondi {
		/**
		 * \brief Requests a feature.
		 *
		 * This function requests a named feature
		 * asynchronously and returns a pending operation object.
		 * If it succeeds it calls the successCallback and passes in
		 * the object of the requested feature. If it fails it calls
		 * the errorCallback passing in a DeviceAPIError which provides 
		 * an error message and error code indicating the nature of the error.
		 *
		 * If the requested feature binds itself to a root namespace
		 * ( for example, "bondi.pim.contact") this will happen prior to the
		 * successCallback being invoked.
		 *
		 * \param successCallback  the success callback function
		 * \param errorCallback    the error callback function
		 * \param name             the feature name IRI
		 *
		 * \return PendingOperation enabling the requester to cancel this request.
		 *
		 * The errorCallback will receive one of the following errors:
		 * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if a malformed
		 * argument has been supplied or a required argument has been omitted.
		 * \throw DeviceAPIError NOT_FOUND_ERROR if the requested feature could not be found.
		 * \throw SecurityError PERMISSION_DENIED_ERROR if the
		 * requested feature is not permitted to load/bind or that
		 * access to a required device capability has been denied.
		 * \throw DeviceAPIError UNKNOWN_ERROR if an error occurred and a pending
		 * operation object can't be returned.
		 */
		PendingOperation requestFeature(in RequestFeatureSuccessCallback successCallback,
		                                in ErrorCallback   errorCallback,
		                                in DOMString       name)
			raises(DeviceAPIError, SecurityError);
	};
	interface BondiObject {
		readonly attribute Bondi bondi; 
	};
	Window implements bondiObject;
};