/////////////////////////////////////////////////////////////////////////////////
//
// c) 2011 Panther Panache, LLC.  
// This source code is Confidential and Proprietary information of the company.
//
/////////////////////////////////////////////////////////////////////////////////
package com.panache.client.assets
{
	import com.panache.adUnits.IPanacheAdUnitStatus;
	import com.panache.adUnits.states.IPanacheHostingState;
	
	/**
	 * IPanacheToolkitAssetServices is a secondary interface that is implemented
	 * on the IPanacheAssetServices object sent to creatives from a toolkit ad unit.
	 * This interface is not inteded to replace IPanacheAssetServices since this
	 * is a legacy interface.
	 * This interface is intended to add additional services for use by a 
	 * creative which:
	 * <ul>
	 * <li>is being loaded by a toolkit ad unit.</li>
	 * <li>implements the IPanacheAssetServicesClient interface.
	 * </ul>
	 * Note: This interface will be available in ad units compiled after 8/25/2011.
	 * 
	 * <p>
	 * Before a creative calls any of the methods defined in this interface, it should
	 * first test the IPanacheAssetServices object that it receives to see if it also 
	 * implements this interface.
	 * </p>
	 * 
	 * @example The following demonstrates how to retrieve and use the IPanacheAssetServices
	 * object as well as how to retrieve and use the IPanacheToolkitAssetServices object,
	 * if it is available.
	 * <listing version="3.0">
	 * private var _services:IPanacheAssetServices;
	 * private var _toolkitSerivces:IPanacheToolkitAssetServices;
	 * private var _metrics:Object;
	 * private var _adXml:XML;
	 * 
	 * public function setServices(services:IPanacheAssetServices) : void
	 * {
	 * 		_services = services;
	 * 		_toolkitServices = (services as IPanacheToolkitAssetServices);
	 * 
	 * 		// get the metrics object from the asset services object
	 * 		if (_services != null)
	 * 		{
	 * 			_metrics = _services.getPanacheMetrics();	
	 * 		}
	 * 
	 *		// get the ad xml from the toolkit asset services object
	 * 		if (_toolkitServices != null)
	 * 		{
	 * 			_adXml = _toolkitServices.getAdXml();
	 * 		} 			
	 * }
	 * </listing> 
	 */ 
	public interface IPanacheToolkitAssetServices
	{
		/**
		 * Retrieves ad xml from the hosting ad unit so that it can be
		 * processed by the creative.
		 * 
		 * @param nodeName is an optional String argument specifying 
		 * a specific node whose contents is being requested by the
		 * creative.
		 * If the argument is specified and that node is present in
		 * the ad xml, then this funtion will return the contents of 
		 * that node to the creative.
		 * If the argument is specified and that node is NOT present,
		 * then this function will return <code>null</code> to the creative.
		 * If this argument is NOT specified, then this function will send
		 * the entire ad xml to the creative.
		 * 
		 * @param id is an optional String argument for use in conjunction
		 * with the nodeName argument to further specify the node being
		 * requested by the creative.
		 * If the nodeName and id are specified and that node exists AND
		 * its id matches the requested id, then this function will return
		 * the matching node to the creative.
		 * If the nodeName and id are specified and a matching node is NOT
		 * found, then this function will send <code>null</code> to the
		 * creative.
		 * If these arguments are not specified, then the entire ad xml
		 * is sent to the creative.
		 * 
		 * @return A non-null XML object indicates that ad xml is
		 * available for use by the creative.
		 * A return value of <code>null</code> indicates that either
		 * there is no ad xml present in the ad unit or that, if
		 * the optional arguments were specified, that there is
		 * no matching ad xml data.
		 */ 
		function getAdXml(nodeName:String = null, id:String = null) : XML;
		
		/**
		 * Retrieves the IPanacheAdUnitStatus object of the ad unit.
		 * Use this object to query the ad unit about its current
		 * properties, status and other descriptors.
		 * 
		 * @return A non-null object should represent the status
		 * interface of the ad unit.
		 * It would be an error to receive a <code>null</code> response.
		 */ 
		function getAdUnitStatus() : IPanacheAdUnitStatus;
		
		/**
		 * Retrieves the state which is hosting the asset as an
		 * implementation of IPanacheHostingState.
		 * Use this object to query the state about its current
		 * properties, status, and other descriptors;
		 * 
		 * @return A non-null object represents the IPanacheHostingState
		 * interface of the ad unit state displaying the asset.
		 * It would be an error to receive a <code>null</code> response.
		 */ 
		function getHostingState() : IPanacheHostingState;
		
		/**
		 * Retrieves the current data about the ad video state.
		 * This information would include:
		 * <ul>
		 * <li>current play state
		 * <ul>
		 * <li>playing</li>
		 * <li>paused</li>
		 * <li>completed</li>
		 * <li>not-started</li>
		 * <li>failed</li>
		 * </ul>
		 * </li>
		 * <li>current ad video duration</li>
		 * <li>current ad video playhead time</li>
		 * <li>current volume</li>
		 * <li>current video rendition in use</li>
		 * <li>current playlist index, if applicable</li>
		 * </ul>
		 * 
		 * @param id is an optional String argument identifying a
		 * specific video state, in the case where there may be more
		 * than one video.  In most cases, this parameter should be
		 * omitted.
		 * 
		 * @return A non-null Object indicates that there is a
		 * video state enabled. The Object contains fields
		 * that hold the descriptive data.
		 * A return value of <code>null</code> indicates that there
		 * no video state enabled.
		 */ 
		function getAdVideoData(id:String = null) : Object;	
	}
}