sage.api
Class MediaNodeAPI

java.lang.Object
  sage.api.MediaNodeAPI

public class MediaNodeAPI
extends java.lang.Object

Virtual content directory abstraction.

Method Summary

void	AppendNodeFilter(sage.vfs.MediaNode MediaNode, java.lang.String Technique, boolean MatchPasses) Adds a filtering technique to used by the specified MediaNode hierarchy.
sage.vfs.MediaNode	CreateMediaNode(java.lang.String PrimaryLabel, java.lang.String SecondaryLabel, java.lang.Object Thumbnail, java.lang.Object Icon, java.lang.Object DataObject) Creates a static MediaNode that has no parents and no children.
java.util.Collection	GetAllNodeDescendants(sage.vfs.MediaNode MediaNode) Returns the data set that represents all the children under the specified MediaNode if that data set has already been realized.
int	GetChildrenCheckedCount(sage.vfs.MediaNode MediaNode, boolean State) Returns the number of children of the specified MediaNode that are in the specified checked state.
java.util.Vector	GetChildrenCheckedNodes(sage.vfs.MediaNode MediaNode, boolean State) Returns the children of the specified MediaNode that are in the specified checked state.
sage.vfs.MediaNode	GetMediaSource(java.lang.String Name) Retrieves a MediaNode which is the root of the specified 'Media Source'.
sage.vfs.MediaNode	GetMediaView(java.lang.String Name, java.lang.Object Data) Similar to the GetMediaSource API call; but the second argument allows specifying the actual data set to be used for the view.
sage.vfs.MediaNode	GetNodeChildAt(sage.vfs.MediaNode MediaNode, int Index) Returns the child of the specified MediaNode at the given index
sage.vfs.MediaNode[]	GetNodeChildren(sage.vfs.MediaNode MediaNode) Returns an array of the children of the specified MediaNode
java.lang.Object	GetNodeDataObject(sage.vfs.MediaNode MediaNode) Returns the Object that is wrapped by the specified MediaNode
java.lang.String	GetNodeDataType(sage.vfs.MediaNode MediaNode) Returns the type of the Object that is wrapped by the specified MediaNode
java.lang.String	GetNodeFilterTechnique(sage.vfs.MediaNode MediaNode, int FilterIndex) Returns the name of the current filtering technique used by the specified MediaNode hierarchy.
(package private) java.lang.String	GetNodeFullPath(sage.vfs.MediaNode MediaNode) Returns a string which represents the hierarchical path to this MediaNode.
java.lang.Object	GetNodeIcon(sage.vfs.MediaNode MediaNode) Returns the icon image associated with the specified MediaNode.
int	GetNodeNumChildren(sage.vfs.MediaNode MediaNode) Returns the number of children of the specified MediaNode
(package private) int	GetNodeNumFilters(sage.vfs.MediaNode MediaNode) Gets the number of filters that are currently set for the specified MediaNode.
sage.vfs.MediaNode	GetNodeParent(sage.vfs.MediaNode MediaNode) Returns the MediaNode parent of the specified MediaNode
java.lang.String	GetNodePrimaryLabel(sage.vfs.MediaNode MediaNode) Returns a string representation of the primary data associated with the specified MediaNode suitable for display in the UI.
java.lang.String	GetNodeProperty(sage.vfs.MediaNode MediaNode, java.lang.String PropertyName) Returns a specific property associated with this MediaNode.
java.lang.String	GetNodeSecondaryLabel(sage.vfs.MediaNode MediaNode) Returns a string representation of the secondary data associated with the specified MediaNode suitable for display in the UI.
java.lang.String	GetNodeSortTechnique(sage.vfs.MediaNode MediaNode) Returns the name of the current sorting technique used by the specified MediaNode hierarchy.
java.lang.Object	GetNodeThumbnail(sage.vfs.MediaNode MediaNode) Returns the thumbnail image associated with the specified MediaNode.
(package private) java.lang.String	GetNodeTypePath(sage.vfs.MediaNode MediaNode) Returns a string which represents the hierarchical path to this MediaNode with type information only.
sage.vfs.MediaNode	GetRelativeMediaSource(java.lang.String Name, java.lang.Object RelativeRoot) Creates a MediaNode view with a relative root for a specified media source.
boolean	IsMediaNodeObject(java.lang.Object Object) Returns true if the specified object is a MediaNode object.
boolean	IsNodeFilterMatching(sage.vfs.MediaNode MediaNode, int FilterIndex) Returns the match state of the current filtering technique used by the specified MediaNode hierarchy.
boolean	IsNodeFolder(sage.vfs.MediaNode MediaNode) Returns true if the specified MediaNode has children
boolean	IsNodeHierarchyRealized(sage.vfs.MediaNode MediaNode) Returns true if the entire set of data objects that back this MediaNode hierarchy has already been realized.
boolean	IsNodePlayable(sage.vfs.MediaNode MediaNode) Returns true if the Object that this MediaNode wraps is suitable for passing to the Watch API call.
boolean	IsNodeSortAscending(sage.vfs.MediaNode MediaNode) Returns true if the current sorting technique used by the specified MediaNode hierarchy is in ascending order, false otherwise
boolean	IsNodeVirtual(sage.vfs.MediaNode MediaNode) Returns true if the specified MediaNode doesn't wrap an actual data object; but just an abstraction of a hierarchy
void	RefreshNode(sage.vfs.MediaNode MediaNode) Refreshes the hierarchy associated with the specified MediaNode.
void	SetAllChildrenChecked(sage.vfs.MediaNode MediaNode, boolean State) Sets a flag on all the children of this MediaNode to indicate they are in the checked state.
void	SetNodeChecked(sage.vfs.MediaNode MediaNode, boolean State) Sets a flag on this MediaNode to indicate it is in the checked state.
void	SetNodeFilter(sage.vfs.MediaNode MediaNode, java.lang.String Technique, boolean MatchPasses) Sets the filtering techniques used by the specified MediaNode hierarchy.
void	SetNodeSort(sage.vfs.MediaNode MediaNode, java.lang.String Technique, boolean Ascending) Sets the sorting technique used by the specified MediaNode hierarchy.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

GetMediaSource

public sage.vfs.MediaNode GetMediaSource(java.lang.String Name)

Retrieves a MediaNode which is the root of the specified 'Media Source'. All names are case insensitive. Valid names are: Filesystem - provides a view of the native filesystem VideoNavigator - provides various views of the imported videos MusicNavigator - provides various views of the imported music MusicVideosNavigator - provides various views of the imported videos with the 'music videos' category MoviesNavigator - provides various views of all content with the 'Movie' category or that are DVDs or BluRays TVNavigator - provides various views of recorded TV content
You can also use names that are "ContentByGrouping" or just "Content". Valid values for "Content" are: Clips - all video files with a duration under 10 mins (controlled by the property max_duration_to_be_a_clip) Music or ImportedMusic - all imported music files Videos or ImportedVideso - all imported video files Picture or Photos or ImportedPictures or ImportedPhotos - all imported picture files DVDs or ImportedDVDs - all imported DVDs BluRays or ImportedBluRays - all imported BluRays Movies - all videos or TV recordings with the 'Movie' category or that are DVDs or BluRays MusicVideos - all imported videos with the 'Music Video' category TV - all recorded TV content MediaFiles - all files in SageTV Compilations - all music files that are by 'Various Artist' MusicPlaylists - all music playlists VideoPlaylists - all video playlists
Valid values for "Grouping" are: Folder - grouped according to their relative import path Category or Genre - grouped by category, for music files they are then subgrouped by Artist and then Album Year - grouped by year, for music files they are subgrouped by Album Director - grouped by Director Actor - grouped by actors/actress Studio - grouped by the studio that produced the content if known Title - grouped by title Series - grouped by television series if known (SeriesInfo object) Album - grouped by album Artist - grouped by artist and then subgrouped by album Channel - grouped by channel

Parameters:

Name - the name of the media source

Returns:

a MediaNode which contains the hierarchy for the specified media source

Since:

7.0

GetMediaView

public sage.vfs.MediaNode GetMediaView(java.lang.String Name,
                                       java.lang.Object Data)

Similar to the GetMediaSource API call; but the second argument allows specifying the actual data set to be used for the view. The name describes the type of content or grouping just like in GetMediaSource. Can be used for presenting a subset of another view or for creating a MediaNode view of a fixed list of data such as a list of MediaFiles or Actors.

Parameters:

Name - the view name to use

Data - the dataset that defines the content in the view, can be a Collection, Object[] or a single object

Returns:

a MediaNode that represents the specified Data using the specified view Name

Since:

7.0

GetRelativeMediaSource

public sage.vfs.MediaNode GetRelativeMediaSource(java.lang.String Name,
                                                 java.lang.Object RelativeRoot)

Creates a MediaNode view with a relative root for a specified media source. This is currently only useable with the 'Filesystem' media source

Parameters:

Name - should be Filesystem; anything else will behave like the GetMediaSource API call

RelativeRoot - the subdirectory which should be the root of this view

Returns:

a MediaNode that represents the relative view of the specified media source

Since:

7.0

IsNodeFolder

public boolean IsNodeFolder(sage.vfs.MediaNode MediaNode)

Returns true if the specified MediaNode has children

Parameters:

MediaNode - the specified MediaNode

Returns:

true if the specified MediaNode has children, false otherwise

Since:

7.0

GetNodeChildren

public sage.vfs.MediaNode[] GetNodeChildren(sage.vfs.MediaNode MediaNode)

Returns an array of the children of the specified MediaNode

Parameters:

MediaNode - the specified MediaNode

Returns:

an array of the children of the specified MediaNode

Since:

7.0

GetNodeNumChildren

public int GetNodeNumChildren(sage.vfs.MediaNode MediaNode)

Returns the number of children of the specified MediaNode

Parameters:

MediaNode - the specified MediaNode

Returns:

the number of children of the specified MediaNode

Since:

7.0

GetNodeChildAt

public sage.vfs.MediaNode GetNodeChildAt(sage.vfs.MediaNode MediaNode,
                                         int Index)

Returns the child of the specified MediaNode at the given index

Parameters:

MediaNode - the specified MediaNode

Index - the index of the child to return (0-based)

Returns:

the child of the specified MediaNode at the given index

Since:

7.0

SetNodeSort

public void SetNodeSort(sage.vfs.MediaNode MediaNode,
                        java.lang.String Technique,
                        boolean Ascending)

Sets the sorting technique used by the specified MediaNode hierarchy. This effects all levels of the hierarchy. MediaNodes that are folders are always listed first when sorting. Some of the sorting techniques can also ignore 'the' as a prefix; this is controlled by the property "ui/ignore_the_when_sorting" which defaults to true. Valid sorting technique names are: Date, Size, Name (can ignore the), Filename, Track, Duration, Title (can ignore the), Artist (can ignore the), Album (can ignore the), Category, Year, Rating, Count, EpisodeName, EpisodeID, Rated, Runtime, Studio (can ignore the), Fullpath, OriginalAirDate, ChannelName, Intelligent

Parameters:

MediaNode - the specified MediaNode

Technique - the name of the sorting technique to use, case insensitive

Ascending - true if the sorting should occur in ascending order, false otherwise

Since:

7.0

GetNodeSortTechnique

public java.lang.String GetNodeSortTechnique(sage.vfs.MediaNode MediaNode)

Returns the name of the current sorting technique used by the specified MediaNode hierarchy.

Parameters:

MediaNode - the specified MediaNode

Returns:

the name of the current sorting technique used by the specified MediaNode hierarchy.

Since:

7.0

IsNodeSortAscending

public boolean IsNodeSortAscending(sage.vfs.MediaNode MediaNode)

Returns true if the current sorting technique used by the specified MediaNode hierarchy is in ascending order, false otherwise

Parameters:

MediaNode - the specified MediaNode

Returns:

true if the current sorting technique used by the specified MediaNode hierarchy is in ascending order, false otherwise

Since:

7.0

SetNodeFilter

public void SetNodeFilter(sage.vfs.MediaNode MediaNode,
                          java.lang.String Technique,
                          boolean MatchPasses)

Sets the filtering techniques used by the specified MediaNode hierarchy. This effects all levels of the hierarchy. Filters can either be inclusive or exclusive. This method will clear all other filters and set this as the only filter. Valid filtering technique names are: Directories, Pictures, Videos, Music, DVD, BluRay, TV, Watched, Archived, DontLike, Favorite, HDTV, ManualRecord, FirstRun, CompleteRecording

Parameters:

MediaNode - the specified MediaNode

Technique - the name of the filtering technique to use, case insensitive

MatchPasses - true if the items matching the filter should be retained, false if matching items should be removed

Since:

7.0

GetNodeNumFilters

int GetNodeNumFilters(sage.vfs.MediaNode MediaNode)

Gets the number of filters that are currently set for the specified MediaNode.

Parameters:

MediaNode - the specified MediaNode

Returns:

the number of filters that are currently set for the specified MediaNode.

Since:

7.0

GetNodeFilterTechnique

public java.lang.String GetNodeFilterTechnique(sage.vfs.MediaNode MediaNode,
                                               int FilterIndex)

Returns the name of the current filtering technique used by the specified MediaNode hierarchy. Since multiple filters can be set; an index must be specified to determine which one to get the technique of

Parameters:

MediaNode - the specified MediaNode

FilterIndex - the 0-based index of the filtering technique to retrieve

Returns:

the name of the current filtering technique used by the specified MediaNode hierarchy at the specified index, null if the index is out of bounds

Since:

7.0

IsNodeFilterMatching

public boolean IsNodeFilterMatching(sage.vfs.MediaNode MediaNode,
                                    int FilterIndex)

Returns the match state of the current filtering technique used by the specified MediaNode hierarchy. Since multiple filters can be set; an index must be specified to determine which one to get the matching state of

Parameters:

MediaNode - the specified MediaNode

FilterIndex - the 0-based index of the filtering match state to retrieve

Returns:

true if the current filtering technique used by the specified MediaNode hierarchy at the specified index is MatchPasses, false otherwise or if the index is out of bounds

Since:

7.0

AppendNodeFilter

public void AppendNodeFilter(sage.vfs.MediaNode MediaNode,
                             java.lang.String Technique,
                             boolean MatchPasses)

Adds a filtering technique to used by the specified MediaNode hierarchy. This effects all levels of the hierarchy. Filters can either be inclusive or exclusive. This method will not clear other filters that have been set. Valid filtering technique names are: Directories, Pictures, Videos, Music, DVD, BluRay, TV, Watched, Archived, DontLike, Favorite, HDTV, ManualRecord, FirstRun, CompleteRecording

Parameters:

MediaNode - the specified MediaNode

Technique - the name of the filtering technique to use, case insensitive

MatchPasses - true if the items matching the filter should be retained, false if matching items should be removed

Since:

7.0

IsNodeHierarchyRealized

public boolean IsNodeHierarchyRealized(sage.vfs.MediaNode MediaNode)

Returns true if the entire set of data objects that back this MediaNode hierarchy has already been realized. This will be true for fixed sets of data; but false for abstractions like the filesystem. When this is true the API call GetAllNodeDescendants will return a valid result.

Parameters:

MediaNode - the specified MediaNode

Returns:

true if the entire set of data objects that back this MediaNode hierarchy has already been realized, false otherwise

Since:

7.0

GetAllNodeDescendants

public java.util.Collection GetAllNodeDescendants(sage.vfs.MediaNode MediaNode)

Returns the data set that represents all the children under the specified MediaNode if that data set has already been realized.

Parameters:

MediaNode - the specified MediaNode

Returns:

a Collection which holds all of the resulting descendants of the specified Media Node; this Collection should NOT be modified

Since:

7.0

GetNodeIcon

public java.lang.Object GetNodeIcon(sage.vfs.MediaNode MediaNode)

Returns the icon image associated with the specified MediaNode. This is currently the same as GetNodeThumbnail.

Parameters:

MediaNode - the specified MediaNode

Returns:

an Object which represents the icon for this MediaNode; this may be a MetaImage or a resource path that can be used to load an image

Since:

7.0

GetNodeThumbnail

public java.lang.Object GetNodeThumbnail(sage.vfs.MediaNode MediaNode)

Returns the thumbnail image associated with the specified MediaNode.

Parameters:

MediaNode - the specified MediaNode

Returns:

an Object which represents the thumbnail for this MediaNode; this may be a MetaImage or a resource path that can be used to load an image

Since:

7.0

GetNodePrimaryLabel

public java.lang.String GetNodePrimaryLabel(sage.vfs.MediaNode MediaNode)

Returns a string representation of the primary data associated with the specified MediaNode suitable for display in the UI.

Parameters:

MediaNode - the specified MediaNode

Returns:

a string representation of the primary data associated with the specified MediaNode suitable for display in the UI

Since:

7.0

GetNodeSecondaryLabel

public java.lang.String GetNodeSecondaryLabel(sage.vfs.MediaNode MediaNode)

Returns a string representation of the secondary data associated with the specified MediaNode suitable for display in the UI. This will usually relate to whatever the current sorting technique is.

Parameters:

MediaNode - the specified MediaNode

Returns:

a string representation of the secondary data associated with the specified MediaNode suitable for display in the UI

Since:

7.0

IsNodePlayable

public boolean IsNodePlayable(sage.vfs.MediaNode MediaNode)

Returns true if the Object that this MediaNode wraps is suitable for passing to the Watch API call.

Parameters:

MediaNode - the specified MediaNode

Returns:

true if the Object that this MediaNode wraps is suitable for passing to the Watch API call

Since:

7.0

IsNodeVirtual

public boolean IsNodeVirtual(sage.vfs.MediaNode MediaNode)

Returns true if the specified MediaNode doesn't wrap an actual data object; but just an abstraction of a hierarchy

Parameters:

MediaNode - the specified MediaNode

Returns:

true if the specified MediaNode doesn't wrap an actual data object; but just an abstraction of a hierarchy

Since:

7.0

GetNodeDataObject

public java.lang.Object GetNodeDataObject(sage.vfs.MediaNode MediaNode)

Returns the Object that is wrapped by the specified MediaNode

Parameters:

MediaNode - the specified MediaNode

Returns:

the Object that is wrapped by the specified MediaNode

Since:

7.0

GetNodeDataType

public java.lang.String GetNodeDataType(sage.vfs.MediaNode MediaNode)

Returns the type of the Object that is wrapped by the specified MediaNode

Parameters:

MediaNode - the specified MediaNode

Returns:

the type of the Object that is wrapped by the specified MediaNode

Since:

7.0

GetNodeProperty

public java.lang.String GetNodeProperty(sage.vfs.MediaNode MediaNode,
                                        java.lang.String PropertyName)

Returns a specific property associated with this MediaNode. This varies depending upon the data type of the MediaNode. For MediaFile based nodes this will end up calling GetMediaFileMetadata.

Parameters:

MediaNode - the specified MediaNode

PropertyName - the name of the property

Returns:

the value of the specified property for the specified MediaNode

Since:

7.0

GetNodeParent

public sage.vfs.MediaNode GetNodeParent(sage.vfs.MediaNode MediaNode)

Returns the MediaNode parent of the specified MediaNode

Parameters:

MediaNode - the specified MediaNode

Returns:

the MediaNode parent of the specified MediaNode or null if it doesn't have a parent

Since:

7.0

RefreshNode

public void RefreshNode(sage.vfs.MediaNode MediaNode)

Refreshes the hierarchy associated with the specified MediaNode.

Parameters:

MediaNode - the specified MediaNode

Since:

7.0

SetNodeChecked

public void SetNodeChecked(sage.vfs.MediaNode MediaNode,
                           boolean State)

Sets a flag on this MediaNode to indicate it is in the checked state. Useful for tracking multi-selection of child MediaNodes.

Parameters:

MediaNode - the specified MediaNode

State - true if the MediaNode should be marked as being in the checked state, false otherwise

Since:

7.0

SetAllChildrenChecked

public void SetAllChildrenChecked(sage.vfs.MediaNode MediaNode,
                                  boolean State)

Sets a flag on all the children of this MediaNode to indicate they are in the checked state. Useful for tracking multi-selection of child MediaNodes.

Parameters:

MediaNode - the specified MediaNode

State - true if all the children of the MediaNode should be marked as being in the checked state, false if they should be marked as unchecked

Since:

7.0

GetChildrenCheckedCount

public int GetChildrenCheckedCount(sage.vfs.MediaNode MediaNode,
                                   boolean State)

Returns the number of children of the specified MediaNode that are in the specified checked state.

Parameters:

MediaNode - the specified MediaNode

State - true if the returned count should be for checked children, false if it should be for unchecked children

Returns:

the number of children of the specified MediaNode that are in the specified checked state

Since:

7.0

GetChildrenCheckedNodes

public java.util.Vector GetChildrenCheckedNodes(sage.vfs.MediaNode MediaNode,
                                                boolean State)

Returns the children of the specified MediaNode that are in the specified checked state.

Parameters:

MediaNode - the specified MediaNode

State - true if the returned list should be for checked children, false if it should be for unchecked children

Returns:

an array of children of the specified MediaNode that are in the specified checked state

Since:

7.0

CreateMediaNode

public sage.vfs.MediaNode CreateMediaNode(java.lang.String PrimaryLabel,
                                          java.lang.String SecondaryLabel,
                                          java.lang.Object Thumbnail,
                                          java.lang.Object Icon,
                                          java.lang.Object DataObject)

Creates a static MediaNode that has no parents and no children. Can be used to add arbitrary items to MediaNode lists for display in the UI. The data type for the node will be Virtual.

Parameters:

PrimaryLabel - the value to set as the primary label for the MediaNode

SecondaryLabel - the value to set as the secondary label for the MediaNode

Thumbnail - the Object to use as the thumbnail for the MediaNode

Icon - the Object to use as the icon for the MediaNode

DataObject - the Object that should be the data object for the MediaNode

Returns:

a new MediaNode object that has the specified attributes

Since:

7.0

GetNodeFullPath

java.lang.String GetNodeFullPath(sage.vfs.MediaNode MediaNode)

Returns a string which represents the hierarchical path to this MediaNode. This is created by appending the primary labels of all the parents up to the root of the hierarchy. The forward slash is used as a separator.

Parameters:

MediaNode - the specified MediaNode

Returns:

a string which represents the hierarchical path to this MediaNode

Since:

7.0

GetNodeTypePath

java.lang.String GetNodeTypePath(sage.vfs.MediaNode MediaNode)

Returns a string which represents the hierarchical path to this MediaNode with type information only. This is created by appending the data types of all the parents up to the root of the hierarchy. The forward slash is used as a separator. For Virtual nodes, it will use F if it represents a folder in the import hierarchy; otherwise it'll use the primary label unless that is null, in which case it'll use V.

Parameters:

MediaNode - the specified MediaNode

Returns:

a string which represents the hierarchical type path to this MediaNode

Since:

7.0

IsMediaNodeObject

public boolean IsMediaNodeObject(java.lang.Object Object)

Returns true if the specified object is a MediaNode object. No automatic type conversion will be performed on the argument.

Parameters:

Object - the object to test to see if it is a MediaNode object

Returns:

true if the argument is a MediaNode object, false otherwise

Since:

7.1