/*************************************************************************
*
*  Copyright 2008 FlashMobileBlog
*  All Rights Reserved.
*
**************************************************************************/


/**
* This is the base class for data provider classes that retrieve their data from the
* Device using DataRequests.
* <p>
* The <code>DeviceDataProvider</code> class is to be used with components, both UI components and other
* ActionScript classes.
* It responds to data requests and dispatches events to notify of data changes.
* This base class allows for only reading of device data. You can extend this class to provide
* extra functionality to interact with items on the device.
* </p>
*
* @category Class
* @langversion 2.0
* @playerversion Lite 2.1
*/
class mobile.device.DeviceDataProvider
{
	//--------------------------------------------------------------------------
	//
	//  Constructor
	//
	//--------------------------------------------------------------------------

	/**
	 * Class Constructor.
	 *
	 * @category Constructor
	 * @langversion 2.0
	 * @playerversion Lite 2.1
	 *
	 */
	function DeviceDataProvider()
	{
		super();
	}

	//--------------------------------------------------------------------------
	//
	//  Variables
	//
	//--------------------------------------------------------------------------

	/**
	 * @private
	 *
	 * The length of the virtual item list
	 */
	private var _length:Number;

	/**
	 * Gets the length of the virtual item list.
	 * <p>
	 * This is only valid after the <code>DeviceDataProvider.OPEN</code> event is received.
	 * </p>
	 *
	 * @category Property
	 * @langversion 2.0
	 * @playerversion Lite 2.1
	 */
	public function get length():Number
    	{
        	return _length;
    	}

	/**
	 * @private
	 *
	 * The DataRequest that corresponds to a virtual list session in native code
	 */
	private var list:DataRequest;


	/**
	 * @private
	 *
	 * A fake object to allow DeviceDataProvider functions to run in the context
	 * of a data request to improve memory and CPU efficiency
	 */
	private var owner:Object;


	/**
	 * Handles the list open notification through <code>onLoad</code> calls from the open list data request.
	 * <p>
	 * This method is run in the context of the <code>DeviceDataProvider</code> class.
	 * </p>
	 *
	 * @category Method
	 * @langversion 2.0
	 * @playerversion Lite 2.1
	 */
	public function doHandleOpenList():Void
	{
		owner.listOpenHandler();
	}

	/**
	 * Handles the list cancelation notification through <code>onLoad</code> calls from the open list data request.
	 * <p>
	 * This method is run in the context of the open list data request not the <code>DeviceDataProvider</code> class.
	 * </p>
	 *
	 * @category Method
	 * @langversion 2.0
	 * @playerversion Lite 2.1
	 */
	public function listOpenHandler():Void
	{
		this.dispatchEvent(new DataProviderEvent("open", length()));
	}

	/**
	 *
	 *
 	 * Switches the <code>DeviceDataProvider</code> object list data request to the parameter given.
	 * <p>
	 * If the <code>DeviceDataProvider</code> was previously initialized, then all outstanding
	 * requests will be cancelled and deleted.
     	 * When the list has completed its first stage of opening and initialization, this event is dispatched.
     	 * The list's Id is available once the open event has been received.
 	 * </p>
	 * @param list A constructed DataRequest to claim a native list.
	 * 				The request should not triggered with the request function.
	 * 				The request's <code>onData()</code> and <code>onLoad()</code> will be overwritten.
	 *
	 * @see DataRequest
	 *
	 * @category Method
	 * @langversion 2.0
	 * @playerversion Lite 2.1
	 */
	public function open(filter:Object, sortOrder:Number, returnFields:Object):Void
	{
		if (list!=null)
		{
			close();
		}

		list = new DataRequest("plugin", "openList", filter, sortOrder, returnFields);
		list.owner = this;
		list.onLoad = doHandleOpenList;
		list.request();
	}


	/**
	 *
	 *
 	 * Closes the DataProvider's open list data request.
	 * <p>
	 * This method cancels all outstanding data requests on the list and
 	 * allows them to be garbage collected. It is safe to call this function
	 * even if the data provider is already closed.
	 * Once the list is canceled, the <code>DeviceDataProvider.CLOSE</code> event is dispatched.
	 * </p>
	 * @see DataRequest
	 *
	 * @category Method
	 * @langversion 2.0
	 * @playerversion Lite 2.1
	 */
	public function close():Void
	{
		list.cancel();
		delete list;
		delete _length;
	}
}