sage.api
Class AiringAPI

java.lang.Object
  sage.api.AiringAPI

public class AiringAPI
extends java.lang.Object

Airing is the 'meta' object used to access content.

An Airing can represent a specific time and Channel that a television Show is broadcast on. Uniquely identified by its time-Channel overlap because only one thing can be broadcast on a Channel at any given time. Airing's also represent the metadata that identify individual files.

SageTV will automatically convert the following types to Airing if used for a parameter that requires the Airing type:

MediaFile - the Airing that represents the content is used

java.io.File - the corresponding MediaFile (if it exists) is resolved and then its Airing is used

Method Summary

sage.Airing	AddAiring(java.lang.String ShowExternalID, int StationID, long StartTime, long Duration) Adds a new Airing object to the database.
sage.Airing	AddAiringDetailed(java.lang.String ShowExternalID, int StationID, long StartTime, long Duration, int PartNumber, int TotalParts, java.lang.String ParentalRating, boolean HDTV, boolean Stereo, boolean ClosedCaptioning, boolean SAP, boolean Subtitled, java.lang.String PremierFinale) Adds a new Airing object to the database.
void	CancelRecord(sage.Airing Airing) Cancels a recording that was previously set with a call to Record() or SetRecordingTimes()
void	ClearDontLike(sage.Airing Airing) Called to cancel the indication that the content in this Airing is "Not Liked" by the user
void	ClearWatched(sage.Airing Airing) Clears the watched information for this Airing completely.
java.lang.String	GetAiringChannelName(sage.Airing Airing) Gets the name of the Channel that this Airing is on
java.lang.String	GetAiringChannelNumber(sage.Airing Airing) Gets the channel number that this Airing is on
long	GetAiringDuration(sage.Airing Airing) Gets the duration of this Airing in milliseconds
long	GetAiringEndTime(sage.Airing Airing) Gets the end time of this Airing.
sage.Airing	GetAiringForID(int AiringID) Returns the Airing object that corresponds to the passed in ID.
int	GetAiringID(sage.Airing Airing) Returns the unique ID used to identify this Airing.
sage.Airing	GetAiringOnAfter(sage.Airing Airing) Returns the Airing on the same Channel that is on immediately after the passed in Airing
sage.Airing	GetAiringOnBefore(sage.Airing Airing) Returns the Airing on the same Channel that is on immediately before the passed in Airing
java.lang.String[]	GetAiringRatings(sage.Airing Airing) Gets the list of the field values which correspond to parental ratings control for this Airing
long	GetAiringStartTime(sage.Airing Airing) Gets the start time of this Airing.
java.lang.String	GetAiringTitle(sage.Airing Airing) Gets the title of this Airing.
sage.Channel	GetChannel(sage.Airing Airing) Gets the Channel that this Airing is on
java.lang.String	GetExtraAiringDetails(sage.Airing Airing) Gets miscellaneous information about this Airing.
long	GetLatestWatchedTime(sage.Airing Airing) Gets the time that viewing should resume from for this Airing if it is selected to view
java.lang.String	GetManualRecordProperty(sage.Airing Airing, java.lang.String PropertyName) Returns a property value for a specified ManualRecord.
sage.MediaFile	GetMediaFileForAiring(sage.Airing Airing) Gets the MediaFile object which corresponds to this Airing object
java.lang.String	GetParentalRating(sage.Airing Airing) Gets the parental rating information associated with this Airing.
long	GetRealWatchedEndTime(sage.Airing Airing) Gets the time the user finished watching this Airing, in real time.
long	GetRealWatchedStartTime(sage.Airing Airing) Gets the time the user started watching this Airing, in real time.
java.lang.String	GetRecordingName(sage.Airing Airing) Gets the name for this recording that was set via SetRecordingName(Airing, String)
java.lang.String	GetRecordingQuality(sage.Airing Airing) Returns the recording quality that this Airing has been specifically set to record at.
long	GetScheduleDuration(sage.Airing Airing) Get the duration for an airing accounting for any adjustments made due to Manual Recording stop/start time adjustments or adjustments due to favorite padding.
long	GetScheduleEndTime(sage.Airing Airing) Get the end time for an airing accounting for any adjustments made due to Manual Recording stop/start time adjustments or adjustments due to favorite padding.
java.lang.String	GetScheduleRecordingRecurrence(sage.Airing Airing) If this Airing is a time-based recording this will get a description of the recurrence frequency for its recording recurrence
long	GetScheduleStartTime(sage.Airing Airing) Get the start time for an airing accounting for any adjustments made due to Manual Recording stop/start time adjustments or adjustments due to favorite padding.
sage.Show	GetShow(sage.Airing Airing) Gets the Show object for this Airing which describes it in further detail (Show contains the title, actors, category, description, etc.)
int	GetTrackNumber(sage.Airing Airing) Returns the track number for the Airing if it's from a Music Album.
long	GetWatchedDuration(sage.Airing Airing) Gets the duration of time of this Airing that has been watched already.
long	GetWatchedEndTime(sage.Airing Airing) Gets the time the user finished watching this Airing.
long	GetWatchedStartTime(sage.Airing Airing) Gets the time the user started watching this Airing.
boolean	IsAiringHDTV(sage.Airing Airing) Returns true if this Airing is in HDTV
boolean	IsAiringObject(sage.Airing Airing) Returns true if the argument is an Airing object.
boolean	IsDontLike(sage.Airing Airing) Returns true if this Airing has been set as content the user "Doesn't Like"
boolean	IsFavorite(sage.Airing Airing) Returns true if this Airing matches one of the Favorites the user has setup
boolean	IsManualRecord(sage.Airing Airing) Returns true if this Airing has been selected by the user to manually record Record()
boolean	IsNotManualOrFavorite(sage.Airing Airing) Returns true if this Airing has NOT been selected by the user to manually record Record() and is also NOT a Favorite (i.e.
boolean	IsWatched(sage.Airing Airing) Returns true if this Airing's content has been completely watched already.
boolean	IsWatchedCompletely(sage.Airing Airing) Returns true if this Airing has been completely watched already.
java.lang.String	PrintAiringLong(sage.Airing Airing) Returns a lengthy string which is suitable for displaying information about this Airing.
java.lang.String	PrintAiringMedium(sage.Airing Airing) Returns a string which is suitable for displaying information about this Airing.
java.lang.String	PrintAiringShort(sage.Airing Airing) Returns a brief string which is suitable for displaying information about this Airing.
java.lang.Object	Record(sage.Airing Airing) Specifies that this Airing should be recorded.
void	SetDontLike(sage.Airing Airing) Called to indicate that the content in this Airing is "Not Liked" by the user
void	SetManualRecordProperty(sage.Airing Airing, java.lang.String PropertyName, java.lang.String PropertyValue) Sets a property for a specified ManualRecord.
void	SetRecordingName(sage.Airing Airing, java.lang.String Name) Sets the name for this recording.
void	SetRecordingQuality(sage.Airing Airing, java.lang.String Quality) Sets the recording quality for this Airing if it has been selected by the user as a manual record
java.lang.Object	SetRecordingTimes(sage.Airing Airing, long StartTime, long StopTime) Modifies or creates a time-based recording that is associated with this Airing.
void	SetWatched(sage.Airing Airing) Sets the watched flag for this Airing to true as if the user watched the show from start to finish
void	SetWatchedTimes(sage.Airing Airing, long WatchedEndTime, long RealStartTime) Updates the Watched information for this airing.

Methods inherited from class java.lang.Object

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

Method Detail

SetRecordingName

public void SetRecordingName(sage.Airing Airing,
                             java.lang.String Name)

Sets the name for this recording. For Timed Recordings this will effect the title & associated attributes. For ManualRecordings this will not have any side effects at all.

Parameters:

Airing - the ManualRecord to set the name for

Name - the name to set

GetRecordingName

public java.lang.String GetRecordingName(sage.Airing Airing)

Gets the name for this recording that was set via SetRecordingName(Airing, String)

Parameters:

Airing - the ManualRecord to get the name for

Returns:

the name of the ManualRecord or the empty string if the argument was not a manual record

GetChannel

public sage.Channel GetChannel(sage.Airing Airing)

Gets the Channel that this Airing is on

Parameters:

Airing - the Airing object

Returns:

the Channel that this Airing is on

GetAiringChannelName

public java.lang.String GetAiringChannelName(sage.Airing Airing)

Gets the name of the Channel that this Airing is on

Parameters:

Airing - the Airing object

Returns:

the name of the Channel that this Airing is on

GetAiringChannelNumber

public java.lang.String GetAiringChannelNumber(sage.Airing Airing)

Gets the channel number that this Airing is on

Parameters:

Airing - the Airing object

Returns:

the channel number that this Airing is on

GetAiringDuration

public long GetAiringDuration(sage.Airing Airing)

Gets the duration of this Airing in milliseconds

Parameters:

Airing - the Airing object

Returns:

the duration of this Airing in milliseconds

GetAiringStartTime

public long GetAiringStartTime(sage.Airing Airing)

Gets the start time of this Airing. The time is in Java time units, which are milliseconds since Jan 1, 1970 GMT

Parameters:

Airing - the Airing object

Returns:

the start time of this Airing

GetAiringEndTime

public long GetAiringEndTime(sage.Airing Airing)

Gets the end time of this Airing. The time is in Java time units, which are milliseconds since Jan 1, 1970 GMT

Parameters:

Airing - the Airing object

Returns:

the end time of this Airing

GetShow

public sage.Show GetShow(sage.Airing Airing)

Gets the Show object for this Airing which describes it in further detail (Show contains the title, actors, category, description, etc.)

Parameters:

Airing - the Airing object

Returns:

the Show object for this Airing

GetAiringRatings

public java.lang.String[] GetAiringRatings(sage.Airing Airing)

Gets the list of the field values which correspond to parental ratings control for this Airing

Parameters:

Airing - the Airing object

Returns:

the list of the field values which correspond to parental ratings control for this Airing

GetScheduleStartTime

public long GetScheduleStartTime(sage.Airing Airing)

Get the start time for an airing accounting for any adjustments made due to Manual Recording stop/start time adjustments or adjustments due to favorite padding.

Parameters:

Airing - the Airing object

Returns:

the scheduling end time of the Airing

GetScheduleEndTime

public long GetScheduleEndTime(sage.Airing Airing)

Get the end time for an airing accounting for any adjustments made due to Manual Recording stop/start time adjustments or adjustments due to favorite padding.

Parameters:

Airing - the Airing object

Returns:

the scheduling end time of the Airing

GetScheduleDuration

public long GetScheduleDuration(sage.Airing Airing)

Get the duration for an airing accounting for any adjustments made due to Manual Recording stop/start time adjustments or adjustments due to favorite padding.

Parameters:

Airing - the Airing object

Returns:

the scheduling duration of the Airing

GetScheduleRecordingRecurrence

public java.lang.String GetScheduleRecordingRecurrence(sage.Airing Airing)

If this Airing is a time-based recording this will get a description of the recurrence frequency for its recording recurrence

Parameters:

Airing - the Airing object

Returns:

a description of the recurrence frequency for this Airing's recording recurrence, or the empty string if this is not recurring time-based recording

PrintAiringLong

public java.lang.String PrintAiringLong(sage.Airing Airing)

Returns a lengthy string which is suitable for displaying information about this Airing. This contains nearly all the details of the Airing & its Show

Parameters:

Airing - the Airing object

Returns:

a lengthy string which is suitable for displaying information about this Airing

PrintAiringMedium

public java.lang.String PrintAiringMedium(sage.Airing Airing)

Returns a string which is suitable for displaying information about this Airing. This contains the Airing's channel & a short time string as well as the title & episode name or a short description

Parameters:

Airing - the Airing object

Returns:

a string which is suitable for displaying information about this Airing

PrintAiringShort

public java.lang.String PrintAiringShort(sage.Airing Airing)

Returns a brief string which is suitable for displaying information about this Airing. This contains the Airing's channel & a short time string as well as the title

Parameters:

Airing - the Airing object

Returns:

a brief string which is suitable for displaying information about this Airing

GetAiringTitle

public java.lang.String GetAiringTitle(sage.Airing Airing)

Gets the title of this Airing. This will be the same as the title of the Airing's Show

Parameters:

Airing - the Airing object

Returns:

the title of this Airing

IsWatched

public boolean IsWatched(sage.Airing Airing)

Returns true if this Airing's content has been completely watched already. This may also return true if this Airing itself was not watched; but an Airing with the same content (as determined by SageTV's AI) was watched

Parameters:

Airing - the Airing object

Returns:

true if this Airing's content has beeen watched completely before

GetWatchedDuration

public long GetWatchedDuration(sage.Airing Airing)

Gets the duration of time of this Airing that has been watched already. This time is relative to the Airing itself; not real time.

Parameters:

Airing - the Airing object

Returns:

the duration of time of this Airing that has been watched already in milliseconds

GetWatchedStartTime

public long GetWatchedStartTime(sage.Airing Airing)

Gets the time the user started watching this Airing. This time is relative to the Airing itself; not real time. If this is the first time watching this Airing; then this will return the time the Airing started recording. If this Airing has been watched previously; then the minimum value for this will be the Airing start time.

Parameters:

Airing - the Airing object

Returns:

the time the user started watching this Airing

GetWatchedEndTime

public long GetWatchedEndTime(sage.Airing Airing)

Gets the time the user finished watching this Airing. This time is relative to the Airing itself; not real time. If this Airing is currently being watched, this will be the maximum of any prior watch end time and the current playback time in the Airing.

Parameters:

Airing - the Airing object

Returns:

the time the user finished watching this Airing

GetRealWatchedStartTime

public long GetRealWatchedStartTime(sage.Airing Airing)

Gets the time the user started watching this Airing, in real time.

Parameters:

Airing - the Airing object

Returns:

the time the user started watching this Airing in real time

Since:

6.4

GetRealWatchedEndTime

public long GetRealWatchedEndTime(sage.Airing Airing)

Gets the time the user finished watching this Airing, in real time.

Parameters:

Airing - the Airing object

Returns:

the time the user finished watching this Airing

Since:

6.4

SetWatched

public void SetWatched(sage.Airing Airing)

Sets the watched flag for this Airing to true as if the user watched the show from start to finish

Parameters:

Airing - the Airing object

SetWatchedTimes

public void SetWatchedTimes(sage.Airing Airing,
                            long WatchedEndTime,
                            long RealStartTime)

Updates the Watched information for this airing. The AiringEndTime should be an airing-relative time which indicates the time the user has watched the show up until. The new watched end time will be the maximum of this value and the current watched end time. The RealStartTime is the time (in real time) the user started watching this program at. Internally SageTV will set the start time of the watched data to be the minimum of the recording start time and the airing start time; and the 'real' end time to be the current time.

Parameters:

Airing - the Airing object, there must be a corresponding MediaFile for this Airing

WatchedEndTime - an airing-relative time which indicates the time the user has watched the show up until

RealStartTime - the time (in real time) the user started watching this program at

Since:

7.0

ClearWatched

public void ClearWatched(sage.Airing Airing)

Clears the watched information for this Airing completely.

Parameters:

Airing - the Airing object

GetLatestWatchedTime

public long GetLatestWatchedTime(sage.Airing Airing)

Gets the time that viewing should resume from for this Airing if it is selected to view

Parameters:

Airing - the Airing object

IsWatchedCompletely

public boolean IsWatchedCompletely(sage.Airing Airing)

Returns true if this Airing has been completely watched already. This is different then IsWatched()

Parameters:

Airing - the Airing object

Returns:

true if this Airing has beeen watched completely

IsDontLike

public boolean IsDontLike(sage.Airing Airing)

Returns true if this Airing has been set as content the user "Doesn't Like"

Parameters:

Airing - the Airing object

Returns:

true if this Airing has been set as content the user "Doesn't Like"

SetDontLike

public void SetDontLike(sage.Airing Airing)

Called to indicate that the content in this Airing is "Not Liked" by the user

Parameters:

Airing - the Airing object

ClearDontLike

public void ClearDontLike(sage.Airing Airing)

Called to cancel the indication that the content in this Airing is "Not Liked" by the user

Parameters:

Airing - the Airing object

IsManualRecord

public boolean IsManualRecord(sage.Airing Airing)

Returns true if this Airing has been selected by the user to manually record Record()

Parameters:

Airing - the Airing object

Returns:

true if this Airing has been selected by the user to manually record Record()

IsNotManualOrFavorite

public boolean IsNotManualOrFavorite(sage.Airing Airing)

Returns true if this Airing has NOT been selected by the user to manually record Record() and is also NOT a Favorite (i.e. IsFavorite and IsManualRecord both return false)

Parameters:

Airing - the Airing object

Returns:

true if this Airing is not a ManualRecord or a Favorite

Since:

6.2

IsAiringHDTV

public boolean IsAiringHDTV(sage.Airing Airing)

Returns true if this Airing is in HDTV

Parameters:

Airing - the Airing object

Returns:

true if this Airing is in HDTV, false otherwise

GetTrackNumber

public int GetTrackNumber(sage.Airing Airing)

Returns the track number for the Airing if it's from a Music Album. With music; each song (file) corresponds to an airing.

Parameters:

Airing - the Airing object

Returns:

the track number for the Airing if it's from a Music Album, 0 otherwise

GetRecordingQuality

public java.lang.String GetRecordingQuality(sage.Airing Airing)

Returns the recording quality that this Airing has been specifically set to record at. This is only valid for user selected manual recordings Record()

Parameters:

Airing - the Airing object

Returns:

the recording quality name that this Airing has been specifically set to record at; if no quality has been set it returns the empty string

SetRecordingQuality

public void SetRecordingQuality(sage.Airing Airing,
                                java.lang.String Quality)

Sets the recording quality for this Airing if it has been selected by the user as a manual record

Parameters:

Airing - the Airing object

Quality - the name of the recording quality

IsFavorite

public boolean IsFavorite(sage.Airing Airing)

Returns true if this Airing matches one of the Favorites the user has setup

Parameters:

Airing - the Airing object

Returns:

true if this Airing matches one of the Favorites the user has setup

SetRecordingTimes

public java.lang.Object SetRecordingTimes(sage.Airing Airing,
                                          long StartTime,
                                          long StopTime)

Modifies or creates a time-based recording that is associated with this Airing. This is also a type of Manual Record.

Parameters:

Airing - the Airing object

StartTime - the time the recording of this Airing should start

StopTime - the time the recording of this Airing should stop

Returns:

true if the call succeeds, otherwise a localized error message is returned

Record

public java.lang.Object Record(sage.Airing Airing)

Specifies that this Airing should be recorded. This is a Manul Recording.

Parameters:

Airing - the Airing object

Returns:

true if the call succeeds, otherwise a localized error message is returned

CancelRecord

public void CancelRecord(sage.Airing Airing)

Cancels a recording that was previously set with a call to Record() or SetRecordingTimes()

Parameters:

Airing - the Airing object

IsAiringObject

public boolean IsAiringObject(sage.Airing Airing)

Returns true if the argument is an Airing object. Automatic type conversion is NOT done in this call.

Parameters:

Airing - the object to test

Returns:

true if the argument is an Airing object

GetParentalRating

public java.lang.String GetParentalRating(sage.Airing Airing)

Gets the parental rating information associated with this Airing. This is information such as TVY, TVPG, TVMA, etc.

Parameters:

Airing - the Airing object

Returns:

the parental rating information associated with this Airing

GetExtraAiringDetails

public java.lang.String GetExtraAiringDetails(sage.Airing Airing)

Gets miscellaneous information about this Airing. This includes thing such as "Part 1 of 2", "CC", "HDTV", "Series Premiere", etc.

Parameters:

Airing - the Airing object

Returns:

miscellaneous information about this Airing

GetAiringID

public int GetAiringID(sage.Airing Airing)

Returns the unique ID used to identify this Airing. Can get used later on a call to GetAiringForID()

Parameters:

Airing - the Airing object

Returns:

the unique ID used to identify this Airing

GetAiringForID

public sage.Airing GetAiringForID(int AiringID)

Returns the Airing object that corresponds to the passed in ID. The ID should have been obtained from a call to GetAiringID()

Parameters:

AiringID - the Airing id

Returns:

the Airing object that corresponds to the passed in ID

AddAiring

public sage.Airing AddAiring(java.lang.String ShowExternalID,
                             int StationID,
                             long StartTime,
                             long Duration)

Adds a new Airing object to the database. This call should be used with caution.

Parameters:

ShowExternalID - a GUID which uniquely identifies the Show that correlates with this Airing, this Show should already have been added

StationID - the GUID which uniquely identifies a "Station" (sort of like a Channel)

StartTime - the time at which the new Airing starts

Duration - the duration of the new Airing in milliseconds

Returns:

the newly added Airing

AddAiringDetailed

public sage.Airing AddAiringDetailed(java.lang.String ShowExternalID,
                                     int StationID,
                                     long StartTime,
                                     long Duration,
                                     int PartNumber,
                                     int TotalParts,
                                     java.lang.String ParentalRating,
                                     boolean HDTV,
                                     boolean Stereo,
                                     boolean ClosedCaptioning,
                                     boolean SAP,
                                     boolean Subtitled,
                                     java.lang.String PremierFinale)

Adds a new Airing object to the database. This call should be used with caution. (it has more details you can specify than the standard AddAiring API call)

Parameters:

ShowExternalID - a GUID which uniquely identifies the Show that correlates with this Airing, this Show should already have been added

StationID - the GUID which uniquely identifies a "Station" (sort of like a Channel)

StartTime - the time at which the new Airing starts

Duration - the duration of the new Airing in milliseconds

PartNumber - for music files, the track number; for TV shows if it is a multipart show this is the part number, otherwise this should be 0

TotalParts - for multipart TV shows, this is the total number of parts otherwise this should be zero; for music files it should be zero

ParentalRating - the parental rating for the show, should be a localized value from "TVY", "TVY7", "TVG", "TVPG", "TV14", "TVM" or the empty string

HDTV - true if it's an HDTV airing, false otherwise

Stereo - true if it's a stereo recording, false otherwise

ClosedCaptioning - true if the airing has closed captioning, false otherwise

SAP - true if the Airing has a Secondary Audio Program (SAP), false otherwise

Subtitled - true if the Airing is subtitled, false otherwise

PremierFinale - should be the empty string or a localized value from the list "Premier", "Channel Premier", "Season Premier", "Series Premier", "Season Finale", "Series Finale"

Returns:

the newly added Airing

Since:

5.0

GetMediaFileForAiring

public sage.MediaFile GetMediaFileForAiring(sage.Airing Airing)

Gets the MediaFile object which corresponds to this Airing object

Parameters:

Airing - the Airing object

Returns:

the MediaFile object which corresponds to this Airing object, or null if it has no associated MediaFile

GetAiringOnAfter

public sage.Airing GetAiringOnAfter(sage.Airing Airing)

Returns the Airing on the same Channel that is on immediately after the passed in Airing

Parameters:

Airing - the Airing object

Returns:

the Airing on the same Channel that is on immediately after the passed in Airing

GetAiringOnBefore

public sage.Airing GetAiringOnBefore(sage.Airing Airing)

Returns the Airing on the same Channel that is on immediately before the passed in Airing

Parameters:

Airing - the Airing object

Returns:

the Airing on the same Channel that is on immediately before the passed in Airing

GetManualRecordProperty

public java.lang.String GetManualRecordProperty(sage.Airing Airing,
                                                java.lang.String PropertyName)

Returns a property value for a specified ManualRecord. This must have been set using SetManualRecordProperty and the specified Airing must be a ManualRecord. Returns the empty string when the property is undefined.

Parameters:

Airing - the Airing object which is a ManualRecord

PropertyName - the name of the property

Returns:

the property value for the specified ManualRecord, or the empty string if it is not defined

Since:

7.0

SetManualRecordProperty

public void SetManualRecordProperty(sage.Airing Airing,
                                    java.lang.String PropertyName,
                                    java.lang.String PropertyValue)

Sets a property for a specified ManualRecord. This can be any name/value combination (but the name cannot be null). If the value is null; then the specified property will be removed from this ManualRecord. This only impacts the return values from GetManualRecordProperty and has no other side effects.

Parameters:

Airing - the Airing object which is a ManualRecord

PropertyName - the name of the property

PropertyValue - the value of the property

Since:

7.0