/*
 * 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 The BONDI Telephony API. 
 *
 * The BONDI telephony API provides access to call management
 * functionalities with the possibility to use multiple
 * telephony providers if available. Different available
 * operators can be modelled as telephony provider while
 * a default provider can be set.
 *
 * The TAPI allows to subscribe for notifications about
 * incoming calls and therewith the TAPI allows for accepting
 * and rejecting incoming calls.
 *
 * Managing ongoing calls, resp. calls that were not initiated
 * through the TAPI itself, is also possible as well as to
 * manage multiple calls at the same time. Therefore joining
 * multiple calls to one call and migrating a call from one
 * to another telephony provider is supported.
 *
 * The Telephony API also provides access to information on recent
 * calls (missed, received, and initiated). The information contain
 * all meta-information related to the according call. These
 * meta-information may include the telephone number and date of a call.
 *
 * The listing of calls can be filtered in order to reduce the effort for the
 * using application and to fasten the identification of relevant entries.
 *
 * \def-api-feature http://bondi.omtp.org/api/telephony.createcalls
 * \brief Initiating outgoing telephony calls.
 * \device-cap telephony.createcalls
 *
 * \def-api-feature http://bondi.omtp.org/api/telephony.receivecalls
 * \brief Receiving incomming calls.
 * \device-cap telephony.receivecalls
 *
 * \def-api-feature http://bondi.omtp.org/api/telephony.read
 * \brief Accessing available telephony providers.
 * \device-cap telephony.read
 *
 * \def-api-feature http://bondi.omtp.org/api/telephony.write
 * \brief Setting the default telephony provider.
 * \device-cap telephony.write
 *
 * \def-api-feature http://bondi.omtp.org/api/1.1/telephony.log.get
 * \brief Call to CallManager.findLogEntries
 * \device-cap telephony.log.get
 *
 * \def-api-feature http://bondi.omtp.org/api/1.1/telephony.log.delete
 * \brief Call to CallManager.deleteLogEntry and CallManager.clearLog
 * \device-cap telephony.log.delete
 *
 * \def-api-feature-set http://bondi.omtp.org/api/1.1/telephony
 * \brief All the telephony features
 * \api-feature http://bondi.omtp.org/api/1.1/telephony.log.get
 * \api-feature http://bondi.omtp.org/api/1.1/telephony.log.delete
 * 
 * \def-device-cap telephony.createcalls
 * \brief Initiating outgoing telephony calls.
 *
 * \def-device-cap telephony.receivecalls
 * \brief Receiving incomming calls.
 *
 * \def-device-cap telephony.read
 * \brief Accessing available telephony providers.
 *
 * \def-device-cap telephony.write
 * \brief Setting the default telephony provider.
 *
 * \def-device-cap telephony.log.get
 * \brief Get entries from call log
 * \param folders Space-separated list of folder identifiers from which the call entries are to be retrieved.
 *
 * \def-device-cap telephony.log.delete
 * \brief Delete call log entries from a log
 * \param folder Folder identifier from which the call log entry/entries is/are to be deleted.
 * 
 * \author André Paul <andre.paul@fokus.fraunhofer.de>
 * \author Angel Machin <angel.machin@vodafone.com>
  * \version 1.5
 */
module telephony {
	 
	/**
	 * \brief Array that contains a set of calls.
	 */
	typedef sequence<Call> CallArray;
	
	/**
	 * \brief Array that contains a set of telephony providers.
	 */
	typedef sequence<Call> TelephonyProviderArray;

	/**
	 * \brief Array of call log entries.
	 */
	typedef sequence<LogEntry> LogEntries;
	
 	/**
	 * \brief Callback to receive the available telephony providers.
	 *
	 */
	[Callback=FunctionOnly, NoInterfaceObject] interface TelephonyProviderSuccessCallback {
		/**
		 * \brief The success callback handler for retrieved telephony providers.
		 *
		 * \param telephonyProviders
		 */
		void onSuccess(in TelephonyProviderArray telephonyProviders);
	};

 	/**
	 * \brief Callback to receive Telephony API specific Errors.
	 *
	 */
	[Callback=FunctionOnly, NoInterfaceObject] interface TelephonyErrorCallback {
		/**
		 * \brief The error callback handler for telephony errors.
		 *
		 * \param error
		 */
		void onError(in TelephonyError error);
	};
	
 	/**
	 * \brief Callback to receive incomming call events.
	 *
	 */
	[Callback=FunctionOnly, NoInterfaceObject] interface OnIncommingCallEvent{
		/**
		 * \brief The notification callback handler for managing incomming calls.
		 *
		 * The notification callback handler for managing incomming calls is also
		 * used for a successfull migration of a call from one telephony provider
		 * to another one.
		 * 
		 * \param incommingCall
		 */
		void onEvent(in Call incommingCall);
	};
	
 	/**
	 * \brief Callback to receive call events.
	 *
	 */
	[Callback=FunctionOnly, NoInterfaceObject] interface OnCallStateEvent{
		/**
		 * \brief The call event handler for call related notivications.
		 *
		 * \param call
		 * \param event
		 */
		void onEvent(in Call call, in short event);
	};
	
	/**
	 * \brief Success callback for retrieving a list of Calls.
	 *
	 * Success callback that takes an array of Calls as input
	 * argument. It is used in the asynchronous operation to
	 * get the list of Calls.
	 */
	[Callback=FunctionOnly, NoInterfaceObject] interface LogManagerSuccessCallback {
		/**
		 * \brief Method invoked when a list of calls is retrieved successfully
		 *
		 * \param obj The list of calls
		 */
		void onSuccess(in LogEntries obj);
	};
	
 	/**
	 * \brief The Telephony API specific error interface.
	 *
	 * The telephony error interface defines error codes that are unique to
	 * the Telephony API.
	 */
	interface TelephonyError : GenericError {
		/**
		 * \brief Error thrown if the default telephony provider is unavailable.
		 */
		const unsigned short TELEPHONY_PROVIDER_UNAVAILABLE_ERROR = 0;
		
		/**
		 * \brief Error thrown if a call function is not allowed. 
		 */
		const unsigned short TELEPHONY_NOT_ALLOWED_ERROR = 1;
		
		/**
		 * \brief Error thrown if a telephony provider to use is not initialized. 
		 */
		const unsigned short TELEPHONY_PROVIDER_NOT_INITIALIZED = 2;
	};
	
	
	/**
	 * \brief Telephony provider configuration options.
	 *
	 */
	interface TelephonyProviderConfigurationOptions {
        
		/**
		 * \brief The user identifier needed to access a specific telephony provider.
		 */
		attribute DOMString userName;
		
		/**
		 * \brief The password needed to access a specific telephony provider.
		 */
		attribute DOMString password;

	};

	/**
	 * \brief Telephony manager that provides access to available telephony providers.
	 *
	 * The telephony manager provides access to a list of available
	 * telephony providers. The number and type of available telephony
	 * providers depends on the device.
	 *
	 * \code 
	 * 	var telephonyprovider;
	 *  bondi.telephony.getTelephonyProviders(onProviders, onError);
	 *
	 * function onProviders(TelephonyProviderArray providers){
	 * 	for (var i = 0; i &lt; providers.length; i++){
	 * 		//select a telephony provider by checking the provider properties 
	 *		telephonyprovider = providers[i];
	 * 	}
	 * }
	 * 
	 * function onError(error) {
	 *	alert(error.code);
	 * }
	 * \endcode
	 */
	interface TelephonyManager {

		/**
		 * \brief Gets a list of availabe telephony providers.
		 *
		 * The number of telephony providers that are accessible through
		 * the telephony API depends on the number of available CS and PS
		 * providers installed on the device. To distinguish between
		 * multiple telephony providers the provider description and
		 * properties can be used to select the telephony provider to use.
		 *
         * If the method is executed succcessfuly, telephony providers can
         * be provided, the successcallback is raised. If access is denied
         * by the Security Policy, the errorCallback is invoked with an
         * SecurityError PERMISSION_DENIED_ERROR. If an invalid parameter
         * is passed in the ErrorCallback is invoked with an DeviceAPIError
         * INVALID_ARGUMENT_ERROR.
         *
		 * \api-feature http://bondi.omtp.org/api/telephony.read 
		 *
		 * \param successCallback The callback handler that is fired when all available
		 *			telephony providers were identified and a list of them can be provided.
		 * \param errorCallback The callback handler that is fired if any error occurs.
		 * \return PendingOperation in order to cancel the async call.
		 */
		PendingOperation getTelephonyProviders(
				in TelephonyProviderSuccessCallback successCallback,
				in TelephonyErrorCallback errorCallback);
		
		/**
		 * \brief Gets the default telephony provider.
		 *
		 * Get the default telephony provider that is commonly
		 * used on the device.
		 *
		 * \return TelephonyProvider The default telephony provider.
		 */
		TelephonyProvider getDefaultProvider();
		
		/**
		 * \brief Sets the default telephony provider.
		 *
		 * \api-feature http://bondi.omtp.org/api/telephony.write
		 *
		 * \param provider The default telephony provider to set.
		 * \throw SecurityError if setting a new default telephony provider is not allowed
		 * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if input parameters are
		 *						 invalid.
		 */
		boolean setDefaultProvider(in TelephonyProvider provider)
		  raises(SecurityError, DeviceAPIError);
		  
	};
	
	/**
	 * \brief The TelephonyProvider interface.
	 *
	 * The TelephonyProvider interface is used to abstract
	 * a concrete telephony provider that can be used
	 * to manage calls.
	 *
	 */
	interface TelephonyProvider {
		
		/**
		 * \brief Represents a circuit switched telephony provider type.
		 * 
		 * The circuit switched telephony provider type should use network
		 * connections that are based on telephony tariffs. Commonly this
		 * are GSM or UMTS telephony connections.
		 */
		const short TELEPHONY_PROVIDER_TYPE_CS = 0;
		
		/**
		 * \brief Represents a packet switched telephony provider type.
		 *
		 * The packet switched telephony provider type should use network
		 * connections that are based on data tariffs. Commonly this
		 * are telephony connections based on Voice over IP protocols
		 * or other IP based voice protocols.
		 */
		const short TELEPHONY_PROVIDER_TYPE_PS = 1;
		
		/**
		 * \brief The telephony provider name.
		 *
		 * The telephony provider name that has to provide sufficient information
		 * to distinguish between the providers. For example the company name
		 * that realizes the connections of the telephony provider.
		 */
		attribute DOMString providerName;
		
		/**
		 * \brief The type of the telephony provider.
		 *
		 * The telephony provider type that is either TELEPHONY_PROVIDER_TYPE_PS
		 * or TELEPHONY_PROVIDER_TYPE_CS to distinguish between packet and circuit
		 * switched telephony providers.
		 */
		readonly attribute short type;
		
		/**
		 * \brief Initialize the telephony provider.
		 *
		 * Initializes the telephony provider which usually means that
		 * needed connections to the related telephony provider's network
		 * are established and the user is allowed to make calls (from the
		 * backend point of view).
		 *
		 * If using init without any parameters was not successful the user
		 * could be ask to enter a user name and password for accessing the
		 * telephony provider.
		 *
		 * Telephony tariff based telephony providers usually don't need any
		 * additional user credentials.
		 *
		 * The ErrorCallback receives a DeviceAPIError with code
		 * INVALID_ARGUMENT_ERROR if any of the passed in parameters is
		 * invalid. The ErrorCallback receives a TelephonyError
		 * with code TELEPHONY_PROVIDER_NOT_INITIALIZED if initializing the
		 * provider was not successful for any other reason.
		 *
		 * \api-feature http://bondi.omtp.org/api/telephony.init
		 *
		 * \param successCallback The function that is called after successfull initialisation.
		 * \param errorCallback The function that is called in case of errors.
		 * \param options Options that may be needed to initialize the telephony provider.
		 *				  Usually these are the user credentials.
		 * \return PendingOperation in order to cancel the async call.
		 */
		PendingOperation init(in SuccessCallback successCallback, in ErrorCallback errorCallback, [Optional] in TelephonyProviderConfigurationOptions options);
		
		/**
		 * \brief Sets an event listener to get notifications about
		 *		  incomming calls related to the telephony provider.
		 *
		 * Sets the event listener that receives incomming calls to this
		 * telephony provider. If setIncommingCallEventListener is called
		 * and a listener was registered before only the newer one will
		 * receive incomming calls.
		 *
		 * \api-feature http://bondi.omtp.org/api/telephony.receivecalls
		 *
		 * \param incommingCallEventListener The listener that receives incomming calls.
		 *									 Insert NULL to stop notivifications to a
		 *									 previously set listener. 
		 * \return void
		 * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if input parameters are
		 *						 invalid.
		 * \throw TelephonyError if the telephony provider is not initialized.
		 * \throw SecurityError if receiving calls is not allowed.
		 */
		void setIncommingCallEventListener(in OnIncommingCallEvent incommingCallEventListener)
			raises(SecurityError, DeviceAPIError,TelephonyError);

		/**
		 * \brief Get the own calling address.
		 *
		 * The address is either a valid phone number that
		 * follows the e.164 phone number scheme if the
		 * associated telephony provider is a circuit switched
		 * telephony provider or it should be a valid SIP URI
		 * if the associated telephony provider is a packet
		 * switched telephony provider.
		 *
		 * \return DOMString the address under which this provider is callable
		 * \throw TelephonyError if the telephony provider is not initialized.
		 */
		DOMString getMyAddress()
			raises(TelephonyError);
		
		/**
		 * \brief Get all ongoing calls associated to the telephony provider.
		 *
		 * \return CallArray
		 * \throw TelephonyError if the telephony provider is not initialized.
		 */
		CallArray getOngoingCalls()
			raises(TelephonyError);
		
		/**
		 * \brief Creates a call to a calling partner.
		 *
		 * Creating a call object the can be used to manage a call
		 * with the passed in calling partner. Creating a call does
		 * not mean that the call is established. To establish a call
		 * use Call.open().
		 *
		 * The passed in calling partner address must be either a valid
		 * phone number for Core telephony providers that follows the
		 * e.164 phone number scheme or should be valid SIP URI for
		 * Data telephony providers.
		 *
		 * \api-feature http://bondi.omtp.org/api/telephony.createcalls
		 *
		 * \param callingPartner The identifier of the calling partner
		 * \return Call call object that can be used to manage the call
		 * \throw SecurityError if creating calls is not allowed
		 * \throw TelephonyError if creating a call was not successfull
		 * \throw TelephonyError if the telephony provider is not initialized.
		 * \throw DeviceAPIError if any of the passed-in parameters is invalid
		 */
		Call createCall(in DOMString callingPartner)
			raises(SecurityError, DeviceAPIError, TelephonyError);
		
		/**
		 * \brief Migrates a call into another call.
		 *
		 * Migrating a call allows to switch an ongoing call from one
		 * telephony provider to another. The returned Call will be in
		 * state CALL_STATE_CONNECTED if migrating a call was
		 * successful. The passed in call will be terminated if migrating
		 * the call was successfull.
		 *
		 * The error callback receives a SecurityError if creating a call
		 * with this telephony provider	is not allowed. It receives a
		 * DeviceAPIError with code Unknown_Error if migrating was not succesfull
		 * or is not possible. It receives a TelephonyError with code
		 * TELEPHONY_PROVIDER_NOT_INITIALIZED if the telephony provider
		 * is not initialized befor calling migrateCall. It receives
		 * a DeviceAPIError with code INVALID_ARGUMENT_ERROR if any input parameter
		 * is invalid.
		 *
		 * \api-feature http://bondi.omtp.org/api/telephony.createcalls
		 *
		 * \param successCallback the callback that receives the migrated call
		 * \param errorCallback the callback that receives any errors
		 * \param call The call that will be migrated to another provider
		 * \return PendingOperation in order to cancel the asny call 
		 */
		PendingOperation migrateCall(in OnIncommingCallEvent successCallback, in ErrorCallback errorCallback, in Call call);
	};
	
	/**
	 * \brief The Call interface to manage a call.
	 *
	 * The call interface represents a telephony call and can
	 * be used to manage a call by establishing, closing,
	 * holding, and resuming connections with the associated
	 * calling partner or calling partners.
	 *
	 */
	interface Call {
		
		/**
		 * \brief State that represents the initial idle state.
		 */
		const short CALL_STATE_IDLE = 0;
		
		/**
		 * \brief State that represents that creating a connection is ongoing.
		 */
		const short CALL_STATE_ESTABLISHING = 1;
		
		/**
		 * \brief State that represents an established call.
		 */
		const short CALL_STATE_CONNECTED = 2;
		
		/**
		 * \brief State that represents a closed call.
		 *
		 * A call can be closed either by calling close on
		 * an ongoing call or it can be closed by the calling
		 * party. A closed call cannot be established again. Use
		 * createCall instead to create a new call.
		 */
		const short CALL_STATE_CLOSED = 3;
		
		/**
		 * \brief State that represents a holded call.
		 *
		 * The call goes into the CALL_STATE_ON_HOLD state
		 * if hold was successfully invoked.
		 *
		 */
		const short CALL_STATE_ON_HOLD = 4;
		
		/**
		 * \brief State that represents an incomming call.
		 *
		 * The call goes into the CALL_STATE_CONNECTED state
		 * if open was successfully invoked on an incomming call.
		 *
		 */
		const short CALL_STATE_RINGING = 5;
		
		/**
		 * \brief The current state of the call.
		 *
		 */
		attribute short currentState;
		
		/**
		 * \brief The calling partners associated to the call.
		 *
		 * The attribute contains all known calling partners
		 * of a call. For example, if joining two calls is
		 * successful the list of partners is increased by
		 * one new partner.
		 *
		 * The calling partner addresses are either a valid
		 * phone number that follows the e.164 phone number
		 * scheme if the associated telephony provider
		 * is a Core telephony provider or it should be valid
		 * SIP URIs if the associated telephony provider is
		 * a Data telephony provider.
		 */
		attribute DOMStringArray partners;
		
		/**
		 * \brief The telephony provider associated to the call.
		 *
		 * A reference to the telephony provider that has
		 * created the call.
		 */
		readonly attribute TelephonyProvider parent;
		
		/**
		 * \brief Establishs a connection.
		 *
		 * Establisgin a connection either through connecting a calling partner
		 * for a created call or through accepting a call for incomming calls.
		 * The CALL_STATE_ESTABLISHING event is published to signal that
		 * establishing a call is ongoing. If the connection was successfully
		 * established the CALL_STATE_CONNECTED is published.
		 *
		 * The errorCallback receives a TelephonyError with code
		 * TELEPHONY_NOT_ALLOWED_ERROR if opening the call is not allowed which
		 * is the case if the call is not in state CALL_STATE_IDLE. It receives a
		 * DeviceAPIError with code UNKNOWN_ERROR if the call could not be opened
		 * for any reason.
		 *
		 * \param successCallback the callback invoked after successful method execution
		 * \param errorCallback the callback invoked in any error cases
		 * \return PendingOperation in order to cancel the async call.
		 */
		PendingOperation open(in SuccessCallback successCallback, in ErrorCallback errorCallback);
		
		/**
		 * \brief Rejects an incomming call.
		 *
		 * A call that was recieved through an OnIncommingCallEvent event
		 * can be rejected in order to drop the incomming call and send
		 * an on-hook signal. A rejected call moves into the
		 * CALL_STATE_CLOSED state.
		 *
		 * The errorCallback receives a TelephonyError with code
		 * TELEPHONY_NOT_ALLOWED_ERROR if rejecting the call is not allowed which
		 * is the case if the call is not in state CALL_STATE_RINGING.
		 *
		 * \param successCallback the callback invoked after successful method execution
		 * \param errorCallback the callback invoked in any error cases
		 * \return PendingOperation in order to cancel the async call.
		 */
		 PendingOperation reject(SuccessCallback successCallback, ErrorCallback errorCallback);
		
		/**
		 * \brief Closes a call.
		 *
		 * Closes a call and disconnects from all calling partners.
		 * The call moves into the CALL_STATE_CLOSED state.
		 *
		 * The errorCallback receives a TelephonyError with code
		 * TELEPHONY_NOT_ALLOWED_ERROR if closing the call is not allowed which
		 * is the case if the call is not in state CALL_STATE_ON_HOLD or
		 * CALL_STATE_CONNECTED.
		 *
		 * \param successCallback the callback invoked after successful method execution
		 * \param errorCallback the callback invoked in any error cases
		 * \return PendingOperation in order to cancel the async call.
		 */
		 PendingOperation close(in SuccessCallback successCallback, in ErrorCallback errorCallback);
				
		/**
		 * \brief Holds an ongoing call.
		 *
		 * A call can be set on hold to create another seperated
		 * call or to accept another incomming call without closing
		 * an ongoing call. Thus, it is possible to switch between
		 * multiple calls.
		 *
		 * If an ongoing call can be holded the call moves to 
		 * the CALL_STATE_ON_HOLD state and publishes an event
		 * accordingly.
		 *
		 * The errorCallback receives a TelephonyError with code
		 * TELEPHONY_NOT_ALLOWED_ERROR if holding the call is not allowed which
		 * is the case if the call is not in state CALL_STATE_CONNECTED. It
		 * receives a DeviceAPIError with code UNKNOWN_ERROR for any other errors.
		 *
		 * \param successCallback the callback invoked after successful method execution
		 * \param errorCallback the callback invoked in any error cases
		 * \return PendingOperation in order to cancel the async call.
		 */
		 PendingOperation hold(in SuccessCallback successCallback, in ErrorCallback errorCallback);
		
		/**
		 * \brief Resumes an ongoing call that was previously set to hold
		 *		  the connection.
		 *
		 * If the call state is CALL_STATE_ON_HOLD it can be resumed. If
		 * resuming is successfull the call goes back into the
		 * CALL_STATE_CONNECTED state. 
		 *
		 * The errorCallback receives a TelephonyError with code
		 * TELEPHONY_NOT_ALLOWED_ERROR if resuming the call is not allowed which
		 * is the case if the call is not in state CALL_STATE_ON_HOLD. It
		 * receives a DeviceAPIError with code UNKNOWN_ERROR for any other errors.
		 *
		 * \param successCallback the callback invoked after successful method execution
		 * \param errorCallback the callback invoked in any error cases
		 * \return PendingOperation in order to cancel the async call.
		 */
		 PendingOperation resume(in SuccessCallback successCallback, in ErrorCallback errorCallback);
		
		/**
		 * \brief Adding a new participant to an ongoing call.
		 *
		 * Joins two calls into one to create a connection with more
		 * than two calling partners. If joining was successfull
		 * the joined participant will be added to the list of partners.
		 * The passed in call goes into the CALL_STATE_CLOSED event.
		 *
		 * The errorCallback receives a TelephonyError with code
		 * TELEPHONY_NOT_ALLOWED_ERROR if joining a call is not allowed which
		 * is the case if this call is not in state CALL_STATE_CONNECTED or
		 * CALL_STATE_ON_HOLD. It receives a DeviceAPIError with code
		 * UNKNOWN_ERROR for any other errors.
		 *
		 * \param call
		 * \param successCallback the callback invoked after successful method execution
		 * \param errorCallback the callback invoked in any error cases
		 * \return PendingOperation in order to cancel the async call.
		 */
		 PendingOperation join(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Call call);
	};
	
	
	  /**
	   * \brief Specifies what is instantiated at feature request
	   * \def-instantiated
	   * \api-feature http://bondi.omtp.org/api/telephony.call
	   */
	 	interface TelephonyManagerObject {
			readonly attribute TelephonyManager telephony; 
		};
		Bondi implements TelephonyManagerObject;
		
		
		/**
		 * \brief Call Log Manager API.
		 *
		 * The LogManager interface offers methods to retrieve information from the call registry.
		 */
		interface LogManager {

			/**
			 * \brief Folder of missed calls.
			 */
			const unsigned short MISSED_CALLS_FOLDER = 0;

			/**
			 * \brief Folder with received calls.
			 */
			const unsigned short RECEIVED_CALLS_FOLDER = 1;

			/**
			 * \brief Folder with initiated calls.
			 */
			const unsigned short INITIATED_CALLS_FOLDER = 2;

			/**
			 * \brief Get the list of selected call log entries
			 *
			 * Gets an array of LogEntry objects for call log entries s stored
			 * within the selected folders and matching the selected
			 * filter.
			 *
	         * The filtering is implemented according to the design patterns (chapter 2.4). If no filter is 
	         * passed all the calls will be returned.
			 *
			 * In a search using strings, the search conductes is case sensitive. If the string is found anywhere inside the key object value,
			 * the entire object will be returned.
			 *
			 * This is an asynchronous method.
			 *
			 * Errors that can be returned in the ErrorCallback:
			 * <ul>
			 * <li>SecurityError PERMISSION_DENIED_ERROR when
			 *        access is denied by the security policy.</li>
			 * <li>DeviceAPIError INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function
			 *	If parameters are not valid
			 *	If folder isn't one of the following: MISSED_CALLS_FOLDER, RECEIVED_CALLS_FOLDER or INITIATED_CALLS_FOLDER
			 *	If some of the filter parameters are not supported  </li>
			 * </ul>
			 *
			 * \api-feature http://bondi.omtp.org/api/1.1/telephony.log.get
			 *
			 * \code
			 *	// Define the success callback.
			 * 	function successCallback(response)
			 * 	{
			 * 		// Get first call in the list of results
			 * 		var myCall = response[0];
			 * 	}
			 *
			 *	// Define the error callback.
			 * 	function errorCallback(response)
			 * 	{
			 * 		alert( "The following error code is: " +  response.code);
			 * 	}
			 *
			 *	// Get the call log for the specified filter.
			 * 	var callsArray = [];
			 * 	callsArray.push(bondi.telephonyLog.MISSED_CALLS_FOLDER);
			 * 	callsArray.push(bondi.telephonyLog.RECEIVED_CALLS_FOLDER);
			 * 	bondi.telephonyLog.findLogEntries(successCallback,errorCallback,callsArray, {phoneNumber:"+34666666666"});
			 * \endcode
			 *
			 * \param successCallback function called when the invocation
			 *        ends successfully, the response object is used to retrieve the array
			 *        of Strings containing call IDs.
			 * \param errorCallback function called when an error occurs,
			 *        the input parameter is an Error object with
			 *        a code giving information about the type of error that occurred.
			 * \param callFolder Array of Ints stating in which message
			 *        folders the web app should look for calls. It can't be null.
			 *        Array values must be 0 MISSED_CALLS_FOLDER),1(RECEIVED_CALLS_FOLDER) or
			 *        2(INITIATED_CALLS_FOLDER).
			 * \param filter Specifies the conditions to be met by the calls
			 *
			 * \return PendingOperation in order to cancel the async call.
			 */

			PendingOperation findLogEntries(in LogManagerSuccessCallback successCallback,
					in ErrorCallback errorCallback,
					in ShortArray callFolder,
					[Optional] in LogFilter filter);

			/**
			 * \brief Get the number of calls in a call folder
			 *
			 * Gets the number of calls contained in the folders passed
			 * as input argument.
			 *
			 * \code
			 * 	var foldersArray = [];
			 * 	foldersArray.push(bondi.telephonyLog.MISSED_CALLS_FOLDER);
			 *  var number = bondi.telephonyLog.getNumberOfCalls(foldersArray);
			 *  alert("There are " + number + " missed calls");
			 * \endcode
			 *
			 * \param callFolders Array of ints describing in which call folders
			 *        the calls should be counted. The Possible values of the array
			 *        elements are 0 (MISSED_CALLS_FOLDER), 1 (RECEIVED_CALLS_FOLDER)
			 *        or 2 (INITIATED_CALLS_FOLDER).
			 *
			 * \return The number of calls matching the criteria
			 * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if parameters are not valid
			 */
			unsigned long getNumberOfCalls(in ShortArray callFolders)
				raises(DeviceAPIError);


			/**
			 * \brief Deletes all the calls from a call folder
			 *
			 * Errors that can be returned in the ErrorCallback:
			 * <ul>
			 * <li>SecurityError PERMISSION_DENIED_ERROR when
			 *        access is denied by the security policy.</li>
			 * <li>DeviceAPIError INVALID_ARGUMENT_ERROR if an invalid parameter
			 *        is provided to this function, 
			 *	e.g.if folder isn't one of the following: MISSED_CALLS_FOLDER, RECEIVED_CALLS_FOLDER or INITIATED_CALLS_FOLDER.</li>
			 * </ul>
			 *
			 * \api-feature http://bondi.omtp.org/api/1.1/telephony.log.delete
			 *
			 * \code
			 *	// Define the success callback.
			 * 	function successCallback(response)
			 * 	{
			 * 		alert("Call log is now empty");
			 * 	}
			 *
			 *	// Define the error callback.
			 * 	function errorCallback(response)
			 * 	{
			 * 		alert( "The following error code occured: " +  response.code);
			 * 	}
			 *
			 *	// Get the call for the specified callid
			 * 	bondi.telephonyLog.deleteLogEntry(successCallback,errorCallback, callid, bondi.telephonyLog.MISSED_CALLS_FOLDER);
			 * \endcode
			 *
			 * \param successCallback function called when the invocation
			 *        completes successfully.
			 * \param errorCallback function called when an error occurs,
			 *        the callback provides an input parameter that is an Error object
			 *        that gives information about the type of error that occurred.
			 * \param callID Call identifier
			 * \param folder Call folder from which the messages should be
			 *        removed. The possible values are 0 (MISSED_CALLS_FOLDER),
			 *        1 (RECEIVED_CALLS_FOLDER) or 2 (INITIATED_CALLS_FOLDER).
			 *
			 * \return PendingOperation in order to allow cancelling the async call.
			 */
			PendingOperation deleteLogEntry(in SuccessCallback successCallback,
					in ErrorCallback errorCallback,
					in DOMString callID, in unsigned short folder);

			/**
			 * \brief Deletes all the calls from a call folder
			 *
			 * Errors that may be returned in the ErrorCallback:
			 * <ul>
			 * <li>SecurityError PERMISSION_DENIED_ERROR when
			 *        access is denied by the security policy.</li>
			 * <li>DeviceAPIError INVALID_ARGUMENT_ERROR if a malformed
			 *        argument has been supplied or a required argument has been omitted.</li>
			 * </ul>
			 *
			 * \api-feature http://bondi.omtp.org/api/1.1/telephony.log.delete
			 *
			 * \code
			 *      // Define the success callback.
			 *      function successCallback(response)
			 *      {
			 *              alert("Call log is now empty");
			 *      }
			 *
			 *      // Define the error callback.
			 *      function errorCallback(response)
			 *      {
			 *              alert( "The following error code occured: " +  response.code);
			 *      }
			 *
			 *      // Get the call log for the specified filter.
			 *		var callsArray = [];
			 *		callsArray.push(bondi.telephonyLog.MISSED_CALLS_FOLDER);
			 *		callsArray.push(bondi.telephonyLog.RECEIVED_CALLS_FOLDER);
			 * 		bondi.telephonyLog.clearLog(successCallback,errorCallback, callsArray);
			 * \endcode
			 *
			 * \param successCallback function called when the invocation completes successfully.
			 * \param errorCallback function called when an error occurs,
			 *        the callback provides an input parameter that is an Error object
			 *        that gives information about the type of error that occurred.
			 * \param callFolder Call folder from which the entries should be
			 *        removed. The possible values are 0 (MISSED_CALLS_FOLDER), 
			 *		  1 (RECEIVED_CALLS_FOLDER) or 2 (INITIATED_CALLS_FOLDER).
			 * \return PendingOperation in order to allow cancelling the async call.
			 */
	        PendingOperation clearLog(in SuccessCallback successCallback,
										in ErrorCallback errorCallback,
										in unsigned short callFolder);
		};
					
		/**
		 * \brief Encapsulation of a call log entry on the device.
		 *
		 * \code
		 *	// Define the success callback.
		 * 	function successCallback(response) {
		 * 		var calls = response;
		 * 		// Get first phone number in the list of results
		 * 		alert(call[0].phoneNumber);
		 * 	}
		 *
		 *	// Define the error callback.
		 * 	function errorCallback(response) {
		 * 		alert( "The following error code is: " +  response.code);
		 * 	}
		 *
		 *	// Get the missed calls log.
		 * 	bondi.telephonyLog.findLogEntries(successCallback, errorCallback,
		 * 		[ bondi.telephonyLog.MISSED_CALLS_FOLDER ],
		 * 		{ phoneNumber:"+34666666666"});
		 * \endcode
		 */
		[NoInterfaceObject] interface LogEntry {
			/**
			 * \brief Phone number 
			 * \n  String that contains the phone number that called or that was called (depending on the folder property).
			 *
			 * This attribute is read-only.
			 *
			 * \code
			 *	// Define the success callback.
			 * 	function successCallback(response) {
			 * 		var calls = response;
			 * 		// Get the phonenumber of the first call in the list of results
			 * 		alert(call[0].phoneNumber);
			 * 	}
			 *
			 *	// Define the error callback.
			 * 	function errorCallback(response) {
			 * 		alert( "The following error code is: " +  response.code);
			 * 	}
			 *
			 *	// Get the missed calls log.
			 * 	bondi.telephonyLog.findLogEntries(successCallback, errorCallback,
			 * 		[ bondi.telephonyLog.MISSED_CALLS_FOLDER ],
			 * 		{ phoneNumber:"+34666666666"});
			 * \endcode
			 */
			readonly attribute DOMString phoneNumber;

			/**
			 * \brief Date when the call started
			 * \n  Object containing date and time when the call took place.
			 *
			 * This attribute is read-only.
			 *
			 * \code
			 *	// Define a success callback.
			 * 	function successCallback(response) {
			 * 		alert(response[0].startTime);
			 * 	}
			 *
			 *	// Define an error callback.
			 * 	function errorCallback(response) {
			 * 		alert( "The following error code is: " +  response.code);
			 * 	}
			 *
			 *	// Get the missed calls log.
			 * 	bondi.telephonyLog.findLogEntries(successCallback, errorCallback,
			 * 		[ bondi.telephonyLog.MISSED_CALLS_FOLDER ],
			 * 		{ phoneNumber:"+34666666666"});
			 * \endcode
			 */
			readonly attribute Date startTime;

			/**
			 * \brief Duration of the call
			 * \n Integer which contains the duration of the call in seconds.
			 *
			 * This attribute is read-only.
			 *
			 * \code
			 *	// Define a success callback.
			 * 	function successCallback(response) {
			 * 		alert("The call lasted for " + response[0].duration + " seconds.");
			 * 	}
			 *
			 *	// Define an error callback.
			 * 	function errorCallback(response) {
			 * 		alert( "The following error code is: " +  response.code);
			 * 	}
			 *
			 *	// Get the missed calls log.
			 * 	bondi.telephonyLog.findLogEntries(successCallback, errorCallback,
			 * 		[ bondi.telephonyLog.MISSED_CALLS_FOLDER ],
			 * 		{ phoneNumber:"+34666666666"});
			 * \endcode
			 */
			readonly attribute unsigned long duration;

			/**
			 * \brief Call identifier
			 * String containing the unique id of the call within the platform.
			 *
			 * This attribute is read-only.
			 *
			 * \code
			 *	// Define a success callback.
			 * 	function successCallback(response) {
			 * 		alert("This is the id for the first call in the log: " + response[0].id);
			 * 	}
			 *
			 *	// Define an error callback.
			 * 	function errorCallback(response) {
			 * 		alert( "The following error code is: " +  response.code);
			 * 	}
			 *
			 * // Get the missed calls log.
			 * 	bondi.telephonyLog.findLogEntries(successCallback, errorCallback,
			 * 		[ bondi.telephonyLog.MISSED_CALLS_FOLDER ],
			 * 		{ phoneNumber:"+34666666666"});
			 * \endcode
			 */
			readonly attribute DOMString id;

			/**
			 * \brief folder where the call was stored
			 * This property has access to the information about in which folder is
			 * the call stored. MISSED_CALLS_FOLDER=0, RECEIVED_CALLS_FOLDER=1 or
			 * INITIATED_CALLS_FOLDER=2
			 *
			 * This attribute is read-only.
			 *
			 * \code
			 *	// Define a success callback.
			 * 	function successCallback(response) {
			 * 		var calls = response;
			 * 		var call = calls[0];
			 * 		if (call.folder == bondi.telephonyLog.MISSED_CALLS_FOLDER) {
			 *			alert("Missed call!");
					}
			 * 	}
			 *
			 *	// Define an error callback.
			 * 	function errorCallback(response) {
			 * 		alert( "The following error code occurred: " +  response.code);
			 * 	}
			 *
			 * // Get the missed calls log.
			 * 	bondi.telephonyLog.findLogEntries(successCallback, errorCallback,
			 * 		[ bondi.telephonyLog.MISSED_CALLS_FOLDER ],
			 * 		{ phoneNumber:"+34666666666"});
			 * \endcode
			 */
			readonly attribute unsigned short folder;
		};

		/**
		 * \brief Used for perform search operations in the Call Log
		 *
		 * This interface is intended to be used for input parameters
		 * for call searching (findLogEntries).
		 * Interface used for creation of the Filter objects depending on the CallProperties interface
		 * All the attributes are optional and by default are undefined
		 *
		 * \code
		 *	// Define the success callback.
		 * 	function successCallback(response) {
		 * 		var calls = response;
		 * 		// Get first message in the list of results
		 * 		var call = calls[0];
		 * 	}
		 *
		 *	// Define the error callback.
		 * 	function errorCallback(response) {
		 * 		alert( "The following error code is: " +  response.code);
		 * 	}
		 *
		 *	// Get the SMS log for the specified filter.
		 * 	bondi.telephonyLog.findLogEntries(successCallback, errorCallback,
		 * 		[ bondi.telephonyLog.RECEIVED_CALLS_FOLDER ],
		 * 		{ phoneNumber:"+34666666666"});
		 * \endcode
		 */
		[NoInterfaceObject, Callback] interface LogFilter : GenericFilter {
			
		};

		/**
		 * \brief Specifies what is instantiated at feature request
		 * \def-instantiated
		 * \api-feature http://bondi.omtp.org/api/1.1/telephony.log.get
		 * \api-feature http://bondi.omtp.org/api/1.1/telephony.log.delete
		*/
		interface LogManagerObject {
			readonly attribute LogManager telephonyLog;
		};
		Bondi implements LogManagerObject;
	
};