/*****************************************************
*
* Copyright 2009 Akamai Technologies, Inc. All Rights Reserved.
*
*****************************************************
* The contents of this file are subject to the Mozilla Public License
* Version 1.1 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS"
* basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
* License for the specific language governing rights and limitations
* under the License.
*
*
* The Initial Developer of the Original Code is Akamai Technologies, Inc.
* Portions created by Akamai Technologies, Inc. are Copyright (C) 2009 Akamai
* Technologies, Inc. All Rights Reserved.
*
* Contributor(s): Adobe Systems Incorporated.
*
*****************************************************/
package org.osmf.traits
{
import flash.errors.IllegalOperationError;
import org.osmf.events.DynamicStreamEvent;
import org.osmf.utils.OSMFStrings;
/**
* Dispatched when a stream switch is requested, completed, or failed.
*
* @eventType org.osmf.events.DynamicStreamEvent.SWITCHING_CHANGE
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
[Event(name="switchingChange",type="org.osmf.events.DynamicStreamEvent")]
/**
* Dispatched when the number of dynamic streams has changed.
*
* @eventType org.osmf.events.DynamicStreamEvent.NUM_DYNAMIC_STREAMS_CHANGE
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
[Event(name="numDynamicStreamsChange",type="org.osmf.events.DynamicStreamEvent")]
/**
* Dispatched when the autoSwitch property changed.
*
* @eventType org.osmf.events.DynamicStreamEvent.AUTO_SWITCH_CHANGE
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
[Event(name="autoSwitchChange",type="org.osmf.events.DynamicStreamEvent")]
/**
* DynamicStreamTrait defines the trait interface for media supporting dynamic stream
* switching. It can also be used as the base class for a more specific DynamicStreamTrait
* subclass.
*
* <p>Use the <code>MediaElement.hasTrait(MediaTraitType.DYNAMIC_STREAM)</code> method to query
* whether a media element has a trait of this type.
* If <code>hasTrait(MediaTraitType.DYNAMIC_STREAM)</code> returns <code>true</code>,
* use the <code>MediaElement.getTrait(MediaTraitType.DYNAMIC_STREAM)</code> method
* to get an object of this type.</p>
*
* @see org.osmf.media.MediaElement
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public class DynamicStreamTrait extends MediaTraitBase
{
/**
* Constructor.
*
* @param autoSwitch The initial autoSwitch state for the trait. The default is true.
* @param currentIndex The initial stream index for the trait. The default is zero.
* @param numDynamicStreams The total number of dynamic streams.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function DynamicStreamTrait(autoSwitch:Boolean=true, currentIndex:int=0, numDynamicStreams:int=1)
{
super(MediaTraitType.DYNAMIC_STREAM);
_autoSwitch = autoSwitch;
_currentIndex = currentIndex;
_numDynamicStreams = numDynamicStreams;
_maxAllowedIndex = numDynamicStreams - 1;
_switching = false;
}
/**
* Defines whether or not the trait should be in manual
* or auto-switch mode. If in manual mode the <code>switchTo</code>
* method can be used to manually switch to a specific stream.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function get autoSwitch():Boolean
{
return _autoSwitch;
}
public final function set autoSwitch(value:Boolean):void
{
if (autoSwitch != value)
{
autoSwitchChangeStart(value);
_autoSwitch = value;
autoSwitchChangeEnd();
}
}
/**
* The total number of dynamic streams.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function get numDynamicStreams():int
{
return _numDynamicStreams;
}
/**
* The index of the current dynamic stream. Uses a zero-based index.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function get currentIndex():int
{
return _currentIndex;
}
/**
* The maximum allowed index. This can be set at run-time to
* provide a ceiling for the switching profile, for example,
* to keep from switching up to a higher quality stream when
* the current video is too small to handle a higher quality stream.
*
* The default is the highest stream index.
*
* @throws RangeError If the specified index is less than zero or
* greater than the total number of dynamic streams.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function get maxAllowedIndex():int
{
return _maxAllowedIndex;
}
public final function set maxAllowedIndex(value:int):void
{
if (value < 0 || value > _numDynamicStreams - 1)
{
throw new RangeError(OSMFStrings.getString(OSMFStrings.STREAMSWITCH_INVALID_INDEX));
}
if (maxAllowedIndex != value)
{
maxAllowedIndexChangeStart(value);
_maxAllowedIndex = value;
maxAllowedIndexChangeEnd();
}
}
/**
* Returns the associated bitrate, in kilobits per second, for the specified index.
*
* @throws RangeError If the specified index is less than zero or
* greater than the highest index available.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function getBitrateForIndex(index:int):Number
{
if (index > _numDynamicStreams - 1 || index < 0)
{
throw new RangeError(OSMFStrings.getString(OSMFStrings.STREAMSWITCH_INVALID_INDEX));
}
return 0;
}
/**
* Indicates whether or not a switch is currently in progress.
* This property will return <code>true</code> while a switch has been
* requested and the switch has not yet been acknowledged and no switch failure
* has occurred. Once the switch request has been acknowledged or a
* failure occurs, the property will return <code>false</code>.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function get switching():Boolean
{
return _switching;
}
/**
* Switch to a specific index. To switch up, use the <code>currentIndex</code>
* property, such as:<p>
* <code>
* obj.switchTo(obj.currentIndex + 1);
* </code>
* </p>
* @throws RangeError If the specified index is less than zero or
* greater than <code>maxAllowedIndex</code>.
* Note: If the media is paused, switching will not take place until after play resumes.
* @throws IllegalOperationError If the stream is not in manual switch mode.
*
* @see maxAllowedIndex
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function switchTo(index:int):void
{
if (autoSwitch)
{
throw new IllegalOperationError(OSMFStrings.getString(OSMFStrings.STREAMSWITCH_STREAM_NOT_IN_MANUAL_MODE));
}
else if (index != currentIndex)
{
if (index < 0 || index > maxAllowedIndex)
{
throw new RangeError(OSMFStrings.getString(OSMFStrings.STREAMSWITCH_INVALID_INDEX));
}
// This method sets the switching state to true. The processing
// and completion of the switch are up to the implementing media.
setSwitching(true, index);
}
}
// Internals
//
/**
* Invoking this setter will result in the trait's numDynamicStreams
* property changing.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
protected final function setNumDynamicStreams(value:int):void
{
if (value != _numDynamicStreams)
{
_numDynamicStreams = value;
// Only adjust our maxAllowedIndex property if the old value
// is now out of range.
if (maxAllowedIndex >= _numDynamicStreams)
{
maxAllowedIndex = Math.max(0, _numDynamicStreams - 1);
}
dispatchEvent(new DynamicStreamEvent(DynamicStreamEvent.NUM_DYNAMIC_STREAMS_CHANGE));
}
}
/**
* Invoking this setter will result in the trait's currentIndex
* property changing.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
protected final function setCurrentIndex(value:int):void
{
_currentIndex = value;
}
/**
* Must be called by the implementing media on completing a switch.
*
* Calls the <code>switchingChangeStart()</code> and <code>switchingChangeEnd()</code>
* methods.
* @param newSwitching New <code>switching</code> value for the trait.
* @param index The index to which the switch shall (or did) occur.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
protected final function setSwitching(newSwitching:Boolean, index:int):void
{
if (newSwitching != _switching)
{
switchingChangeStart(newSwitching, index);
_switching = newSwitching;
// Update the index when a switch finishes.
if (newSwitching == false)
{
setCurrentIndex(index);
}
switchingChangeEnd(index);
}
}
/**
* Called immediately before the <code>autoSwitch</code> property is changed.
* <p>Subclasses can override this method to communicate the change to the media.</p>
* @param value New value for the <code>autoSwitch</code> property.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
protected function autoSwitchChangeStart(value:Boolean):void
{
}
/**
* Called just after the <code>autoSwitch</code> property has changed.
* Dispatches the change event.
*
* <p>Subclasses that override should call this method to
* dispatch the change event.</p>
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
protected function autoSwitchChangeEnd():void
{
dispatchEvent(new DynamicStreamEvent(DynamicStreamEvent.AUTO_SWITCH_CHANGE, false, false, false, _autoSwitch));
}
/**
* Called immediately before the <code>switching</code> property is changed.
* <p>Subclasses can override this method to communicate the change to the media.</p>
* @param newSwitching New value for the <code>switching</code> property.
* @param index The index of the stream to switch to.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
protected function switchingChangeStart(newSwitching:Boolean, index:int):void
{
}
/**
* Called just after the <code>switching</code> property has changed.
* Dispatches the change event.
*
* <p>Subclasses that override should call this method to
* dispatch the change event.</p>
*
* @param index The index of the switched-to stream.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
protected function switchingChangeEnd(index:int):void
{
dispatchEvent
( new DynamicStreamEvent
( DynamicStreamEvent.SWITCHING_CHANGE
, false
, false
, switching
)
);
}
/**
* Called immediately before the <code>maxAllowedIndex</code> property is changed.
* <p>Subclasses can override this method to communicate the change to the media.</p>
* @param newIndex New value for the <code>maxAllowedIndex</code> property.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
protected function maxAllowedIndexChangeStart(newIndex:int):void
{
}
/**
* Called just after the <code>maxAllowedIndex</code> property has changed.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
protected function maxAllowedIndexChangeEnd():void
{
}
private var _autoSwitch:Boolean;
private var _currentIndex:int = 0;
private var _maxAllowedIndex:int = 0;
private var _numDynamicStreams:int;
private var _switching:Boolean;
}
}
