Package sage.api

Class FavoriteAPI

java.lang.Object

sage.api.FavoriteAPI

public class FavoriteAPI
extends java.lang.Object

Favorites are objects which are used for repeated recording in SageTV

Constructor Summary

Constructors

Constructor	Description
FavoriteAPI()

Method Summary

Modifier and Type	Method	Description
sage.Favorite	AddFavorite(java.lang.String Title, boolean FirstRuns, boolean ReRuns, java.lang.String Category, java.lang.String SubCategory, sage.Person Person, java.lang.String RoleForPerson, java.lang.String Rated, java.lang.String Year, java.lang.String ParentalRating, java.lang.String Network, java.lang.String ChannelCallSign, java.lang.String Timeslot, java.lang.String Keyword)	Creates a new Favorite object in SageTV.
void	ConfirmManualRecordOverFavoritePriority(sage.Airing ManualRecordAiring, sage.Airing FavoriteAiring)	Confirms that the user is aware that a manual recording they've selected creates a conflict with this favorite recording.
void	CreateFavoritePriority(sage.Favorite HigherPriorityFavorite, sage.Favorite LowerPriorityFavorite)	Establishes a priority of one Favorite over another.
boolean	DoesFavoriteMatchAiring(sage.Favorite Favorite, sage.Airing Airing)	Returns true if the specified Favorite object matches the specified Airing object.
sage.Airing[]	GetFavoriteAirings(sage.Favorite Favorite)	Returns a list of all of the Airings in the database that match this Favorite.
java.io.File	GetFavoriteAutomaticConversionDestination(sage.Favorite Favorite)	Gets the directory that automatic conversions of this favorite should be saved to.
java.lang.String	GetFavoriteAutomaticConversionFormat(sage.Favorite Favorite)	Gets the name of the format that recordings of this Favorite will automatically be converted to when they have completed recording.
java.lang.String	GetFavoriteCategory(sage.Favorite Favorite)	Returns the category that an Airing must match to be included in this Favorite.
java.lang.String	GetFavoriteChannel(sage.Favorite Favorite)	Returns the channel name (call sign) that an Airing must be on to be included in this Favorite.
java.lang.String	GetFavoriteDescription(sage.Favorite Favorite)	Returns a String that describes this Favorite.
sage.Favorite	GetFavoriteForAiring(sage.Airing Airing)	Gets the Favorite that matches this Airing if one exists.
sage.Favorite	GetFavoriteForID(int FavoriteID)	Gets the Favorite object with the corresponding ID from the database.
int	GetFavoriteID(sage.Favorite Favorite)	Gets a unique ID for this Favorite which can be used with GetFavoriteForID() for retrieving the object later.
java.lang.String	GetFavoriteKeyword(sage.Favorite Favorite)	Returns the keyword string that an Airing must match to be included in this Favorite.
java.lang.String	GetFavoriteNetwork(sage.Favorite Favorite)	Returns the network name that an Airing must be on to be included in this Favorite.
java.lang.String	GetFavoriteParentalRating(sage.Favorite Favorite)	Returns the parental rating that an Airing must match to be included in this Favorite.
java.lang.String	GetFavoritePerson(sage.Favorite Favorite)	Returns the person that an Airing must have to be included in this Favorite.
java.lang.String	GetFavoritePersonRole(sage.Favorite Favorite)	Returns the role that an Airing must have the Favorite Person in to be included in this Favorite.
java.lang.String	GetFavoritePresentationName(sage.Favorite Favorite)	Returns a String that describes this Favorite in a 'clean' way.
java.lang.String	GetFavoritePresentationPrefix(sage.Favorite Favorite)	Returns a String that describes this type of Favorite this is, such as Show, Keyword, Person, etc.
java.util.Properties	GetFavoriteProperties(sage.Favorite Favorite)	Returns a java.util.Properties object that has all of the user-set properties for this Favorite in it.
java.lang.String	GetFavoriteProperty(sage.Favorite Favorite, java.lang.String PropertyName)	Returns a property value for a specified Favorite.
java.lang.String	GetFavoriteQuality(sage.Favorite Favorite)	Gets the name of the recording quality that should be used when recording this Favorite.
java.lang.String	GetFavoriteRated(sage.Favorite Favorite)	Returns the rating that an Airing must match to be included in this Favorite.
sage.Favorite[]	GetFavorites()	Gets all of the Favorite objects from the database
sage.Favorite[]	GetFavoritesForAiring(sage.Airing Airing)	Gets the list of all Favorites that match this Airing
java.lang.String	GetFavoriteSubCategory(sage.Favorite Favorite)	Returns the subcategory that an Airing must match to be included in this Favorite.
java.lang.String	GetFavoriteTimeslot(sage.Favorite Favorite)	Returns the timeslot that an Airing must be in to be included in this Favorite.
java.lang.String	GetFavoriteTitle(sage.Favorite Favorite)	Returns the title that an Airing must match to be included in this Favorite.
java.lang.String	GetFavoriteYear(sage.Favorite Favorite)	Returns the year that an Airing must match to be included in this Favorite.
int	GetKeepAtMost(sage.Favorite Favorite)	Returns the maximum number of recordings that match this Favorite that should be kept on disk.
long	GetStartPadding(sage.Favorite Favorite)	Returns the amount of time any recording for this Favorite should start before the actual Airing begins.
long	GetStopPadding(sage.Favorite Favorite)	Returns the amount of time any recording for this Favorite should stop after the actual Airing ends.
boolean	IsAutoDelete(sage.Favorite Favorite)	Returns true if SageTV is allowed to automatically delete recordings of this Favorite when it needs more disk space.
boolean	IsDeleteAfterAutomaticConversion(sage.Favorite Favorite)	If an automatic conversion quality is set for this Favorite; then this will return true if the original file will be deleted after that conversion is performed
boolean	IsFavoriteEnabled(sage.Favorite Favorite)	Returns true if SageTV considers this favorite when performing scheduling.
boolean	IsFavoriteObject(java.lang.Object Favorite)	Returns true if the argument is a Favorite object, false otherwise
boolean	IsFirstRuns(sage.Favorite Favorite)	Returns true if this Favorite is configured to record first runs (it may or may not record reruns)
boolean	IsFirstRunsAndReRuns(sage.Favorite Favorite)	Returns true if this Favorite is configured to record both first runs and reruns.
boolean	IsFirstRunsOnly(sage.Favorite Favorite)	Returns true if this Favorite is configured to record first runs but not reruns.
boolean	IsReRuns(sage.Favorite Favorite)	Returns true if this Favorite is configured to record reruns (it may or may not record first runs)
boolean	IsReRunsOnly(sage.Favorite Favorite)	Returns true if this Favorite is configured to record reruns but not first runs.
void	RemoveFavorite(sage.Favorite Favorite)	Removes a Favorite object from the database.
void	SetDeleteAfterAutomaticConversion(sage.Favorite Favorite, boolean DeleteAfterAutomaticConversion)	Sets whether or not SageTV should delete the original file after doing an automatic conversion for this Favorite
void	SetDontAutodelete(sage.Favorite Favorite, boolean DontAutoDelete)	Sets whether or not SageTV is allowed to automatically delete recordings of this Favorite when it needs more disk space.
void	SetFavoriteAutomaticConversionDestination(sage.Favorite Favorite, java.io.File Folder)	Sets the directory that automatic conversions of this favorite should be saved to.
void	SetFavoriteAutomaticConversionFormat(sage.Favorite Favorite, java.lang.String Format)	Sets the name of the format to transcode this Favorite to after a recording has been completed.
boolean	SetFavoriteCategories(sage.Favorite Favorite, java.lang.String Category, java.lang.String SubCategory)	Sets the category and optionally the subcategory that an Airing must match to be included in this Favorite.
boolean	SetFavoriteChannel(sage.Favorite Favorite, java.lang.Object Channel)	Sets the channel name (call sign) that an Airing must be on to be included in this Favorite.
void	SetFavoriteEnabled(sage.Favorite Favorite, boolean Enabled)	Sets whether or not SageTV will use this favorite when scheduling recordings
boolean	SetFavoriteKeyword(sage.Favorite Favorite, java.lang.String Keyword)	Sets the keyword string that an Airing must match to be included in this Favorite.
boolean	SetFavoriteNetwork(sage.Favorite Favorite, java.lang.String Network)	Sets the network name that an Airing must be on to be included in this Favorite.
boolean	SetFavoriteParentalRating(sage.Favorite Favorite, java.lang.String ParentalRating)	Sets the parental rating that an Airing must match to be included in this Favorite.
boolean	SetFavoritePerson(sage.Favorite Favorite, sage.Person Person, java.lang.String Role)	Sets a person (and optionally the role the person must appear in) that must be in an Airing for it to be included in this Favorite
void	SetFavoriteProperty(sage.Favorite Favorite, java.lang.String PropertyName, java.lang.String PropertyValue)	Sets a property for this Favorite.
void	SetFavoriteQuality(sage.Favorite Favorite, java.lang.String Quality)	Sets the name of the recording quality that should be used when recording this Favorite.
boolean	SetFavoriteRated(sage.Favorite Favorite, java.lang.String Rated)	Sets the rating that an Airing must match to be included in this Favorite.
boolean	SetFavoriteTimeslot(sage.Favorite Favorite, java.lang.String Timeslot)	Sets the timeslot that an Airing must be in to be included in this Favorite.
boolean	SetFavoriteTitle(sage.Favorite Favorite, java.lang.String Title)	Sets the title that an Airing must match to be included in this Favorite.
boolean	SetFavoriteYear(sage.Favorite Favorite, java.lang.String Year)	Sets the year that an Airing must match to be included in this Favorite.
void	SetKeepAtMost(sage.Favorite Favorite, int NumberToKeep)	Sets the maximum number of recordings that match this Favorite that should be kept on disk.
boolean	SetRunStatus(sage.Favorite Favorite, boolean FirstRuns, boolean ReRuns)	Sets whether first runs, reruns or both types of airings should be recorded for this Favorite.
void	SetStartPadding(sage.Favorite Favorite, long StartPadding)	Sets the amount of time any recording for this Favorite should start before the actual Airing begins.
void	SetStopPadding(sage.Favorite Favorite, long StopPadding)	Sets the amount of time any recording for this Favorite should stop after the actual Airing ends.
sage.Favorite	UpdateFavorite(sage.Favorite Favorite, java.lang.String Title, boolean FirstRuns, boolean ReRuns, java.lang.String Category, java.lang.String SubCategory, sage.Person Person, java.lang.String RoleForPerson, java.lang.String Rated, java.lang.String Year, java.lang.String ParentalRating, java.lang.String Network, java.lang.String ChannelCallSign, java.lang.String Timeslot, java.lang.String Keyword)	Updates all of the fields of a Favorite that can be used to match.

Methods inherited from class java.lang.Object

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

Constructor Detail

FavoriteAPI

public FavoriteAPI()

Method Detail

IsFirstRunsAndReRuns

public boolean IsFirstRunsAndReRuns(sage.Favorite Favorite)

Returns true if this Favorite is configured to record both first runs and reruns.

Parameters:

Favorite - the Favorite object

Returns:

true if this Favorite is configured to record both first runs AND reruns, false otherwise

IsFirstRunsOnly

public boolean IsFirstRunsOnly(sage.Favorite Favorite)

Returns true if this Favorite is configured to record first runs but not reruns.

Parameters:

Favorite - the Favorite object

Returns:

true if this Favorite is configured to record first runs only, false otherwise

IsReRunsOnly

public boolean IsReRunsOnly(sage.Favorite Favorite)

Returns true if this Favorite is configured to record reruns but not first runs.

Parameters:

Favorite - the Favorite object

Returns:

true if this Favorite is configured to record reruns only, false otherwise

IsFirstRuns

public boolean IsFirstRuns(sage.Favorite Favorite)

Returns true if this Favorite is configured to record first runs (it may or may not record reruns)

Parameters:

Favorite - the Favorite object

Returns:

true if this Favorite is configured to record first runs, false otherwise

IsReRuns

public boolean IsReRuns(sage.Favorite Favorite)

Returns true if this Favorite is configured to record reruns (it may or may not record first runs)

Parameters:

Favorite - the Favorite object

Returns:

true if this Favorite is configured to record reruns, false otherwise

IsAutoDelete

public boolean IsAutoDelete(sage.Favorite Favorite)

Returns true if SageTV is allowed to automatically delete recordings of this Favorite when it needs more disk space. If this is false, then SageTV will never automatically delete files recorded for this Favorite; the user will have to delete the files themself.

Parameters:

Favorite - the Favorite object

Returns:

true if this Favorite is configured for auto delete, false otherwise

IsDeleteAfterAutomaticConversion

public boolean IsDeleteAfterAutomaticConversion(sage.Favorite Favorite)

If an automatic conversion quality is set for this Favorite; then this will return true if the original file will be deleted after that conversion is performed

Parameters:

Favorite - the Favorite object

Returns:

true if this Favorite is configured to delete the original file after automatic conversion

Since:

7.0

IsFavoriteEnabled

public boolean IsFavoriteEnabled(sage.Favorite Favorite)

Returns true if SageTV considers this favorite when performing scheduling.

Parameters:

Favorite - the Favorite object

Returns:

true if this Favorite is enabled, false otherwise

Since:

9.0

GetKeepAtMost

public int GetKeepAtMost(sage.Favorite Favorite)

Returns the maximum number of recordings that match this Favorite that should be kept on disk. If AutoDelete is set to true then SageTV will continue to record new airings of this Favorite as they air, and delete the oldest recording on disk if it hits the keep at most limit. If AutoDelete is false then SageTV will stop recording this Favorite once it has this many recordings on disk

Parameters:

Favorite - the Favorite object

Returns:

the maximum number of recordings SageTV should keep on disk of this Favorite, 0 if it is unlimited

GetFavoriteDescription

public java.lang.String GetFavoriteDescription(sage.Favorite Favorite)

Returns a String that describes this Favorite.

Parameters:

Favorite - the Favorite object

Returns:

a descriptive string for this Favorite

GetFavoritePresentationName

public java.lang.String GetFavoritePresentationName(sage.Favorite Favorite)

Returns a String that describes this Favorite in a 'clean' way. Should be used in conjunction with GetFavoritePresentationPrefix to create a complete string for presenting a Favorite named uniquely.

Parameters:

Favorite - the Favorite object

Returns:

a descriptive string for this Favorite

Since:

8.0

GetFavoritePresentationPrefix

public java.lang.String GetFavoritePresentationPrefix(sage.Favorite Favorite)

Returns a String that describes this type of Favorite this is, such as Show, Keyword, Person, etc.

Parameters:

Favorite - the Favorite object

Returns:

a descriptive string for the type of Favorite

Since:

8.0

GetFavoriteTitle

public java.lang.String GetFavoriteTitle(sage.Favorite Favorite)

Returns the title that an Airing must match to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Returns:

the title that an Airing must match to be included in this Favorite, returns the empty string if the title isn't a field that needs to match

GetFavoriteCategory

public java.lang.String GetFavoriteCategory(sage.Favorite Favorite)

Returns the category that an Airing must match to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Returns:

the category that an Airing must match to be included in this Favorite, returns the empty string if category isn't a field that needs to match

GetFavoriteSubCategory

public java.lang.String GetFavoriteSubCategory(sage.Favorite Favorite)

Returns the subcategory that an Airing must match to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Returns:

the subcategory that an Airing must match to be included in this Favorite, returns the empty string if subcategory isn't a field that needs to match

GetFavoritePerson

public java.lang.String GetFavoritePerson(sage.Favorite Favorite)

Returns the person that an Airing must have to be included in this Favorite. The person may also be restricted by their role in the content.

Parameters:

Favorite - the Favorite object

Returns:

the person that an Airing must have to be included in this Favorite, returns the empty string if person isn't a field that needs to match

GetFavoriteRated

public java.lang.String GetFavoriteRated(sage.Favorite Favorite)

Returns the rating that an Airing must match to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Returns:

the rating that an Airing must match to be included in this Favorite, returns the empty string if rating isn't a field that needs to match

GetFavoritePersonRole

public java.lang.String GetFavoritePersonRole(sage.Favorite Favorite)

Returns the role that an Airing must have the Favorite Person in to be included in this Favorite. This only applies if a person is set for this Favorite.

Parameters:

Favorite - the Favorite object

Returns:

the role that the favorite person for an Airing must have to be included in this Favorite, returns the empty string if role doesn't matter

GetFavoriteYear

public java.lang.String GetFavoriteYear(sage.Favorite Favorite)

Returns the year that an Airing must match to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Returns:

the year that an Airing must match to be included in this Favorite, returns the empty string if year isn't a field that needs to match

GetFavoriteParentalRating

public java.lang.String GetFavoriteParentalRating(sage.Favorite Favorite)

Returns the parental rating that an Airing must match to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Returns:

the parental rating that an Airing must match to be included in this Favorite, returns the empty string if parental rating isn't a field that needs to match

GetFavoriteChannel

public java.lang.String GetFavoriteChannel(sage.Favorite Favorite)

Returns the channel name (call sign) that an Airing must be on to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Returns:

the channel name that an Airing must be on to be included in this Favorite, returns the empty string if channel doesn't matter; for mult-channel favorites this will be a semicolon or comma-delimited list of channel names

GetFavoriteKeyword

public java.lang.String GetFavoriteKeyword(sage.Favorite Favorite)

Returns the keyword string that an Airing must match to be included in this Favorite. This is case insensitive. Double quotes can be used to require word to be in a certain order. Otherwise; each individual word is searched for in the Airing's details and must match a whole word for the match to succeed. The * character can be used to match 0 or more characters. The ? character can be used to match a single character. Regex is the matching language used for this so any other regex parsing characters besides * and ? can be used. All of the fields of the object are searched as part of this.

Parameters:

Favorite - the Favorite object

Returns:

the keyword that an Airing must match to be included in this Favorite, returns the empty string if keyword doesn't matter

GetFavoriteNetwork

public java.lang.String GetFavoriteNetwork(sage.Favorite Favorite)

Returns the network name that an Airing must be on to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Returns:

the network name that an Airing must be on to be included in this Favorite, returns the empty string if network doesn't matter

GetFavoriteTimeslot

public java.lang.String GetFavoriteTimeslot(sage.Favorite Favorite)

Returns the timeslot that an Airing must be in to be included in this Favorite. It just needs to overlap the timeslot.

Parameters:

Favorite - the Favorite object

Returns:

the timeslot that an Airing must be in to be included in this Favorite, returns the empty string if timeslot doesn't matter

GetStartPadding

public long GetStartPadding(sage.Favorite Favorite)

Returns the amount of time any recording for this Favorite should start before the actual Airing begins.

Parameters:

Favorite - the Favorite object

Returns:

the amount of time any recording for this Favorite should start before the actual Airing begins, in milliseconds

GetStopPadding

public long GetStopPadding(sage.Favorite Favorite)

Returns the amount of time any recording for this Favorite should stop after the actual Airing ends.

Parameters:

Favorite - the Favorite object

Returns:

the amount of time any recording for this Favorite should stop after the actual Airing ends, in milliseconds

GetFavoriteQuality

public java.lang.String GetFavoriteQuality(sage.Favorite Favorite)

Gets the name of the recording quality that should be used when recording this Favorite.

Parameters:

Favorite - the Favorite object

Returns:

the name of the recording quality that should be used when recording this Favorite, the empty string if the default recording quality should be used

GetFavoriteAutomaticConversionFormat

public java.lang.String GetFavoriteAutomaticConversionFormat(sage.Favorite Favorite)

Gets the name of the format that recordings of this Favorite will automatically be converted to when they have completed recording. It will return an empty string if automatic conversion is disabled for this Favorite

Parameters:

Favorite - the Favorite object

Returns:

the name of the transcode format that should be used when converting this Favorite, the empty string if no automatic conversion should be done

Since:

7.0

GetFavoriteAutomaticConversionDestination

public java.io.File GetFavoriteAutomaticConversionDestination(sage.Favorite Favorite)

Gets the directory that automatic conversions of this favorite should be saved to. Returns the empty string when using the same directory the recording is in.

Parameters:

Favorite - the Favorite object

Returns:

the destination directory for the automatic conversions of this Favorite; or null if its the same as the recording directory

Since:

7.0

SetStartPadding

public void SetStartPadding(sage.Favorite Favorite,
                            long StartPadding)

Sets the amount of time any recording for this Favorite should start before the actual Airing begins.

Parameters:

Favorite - the Favorite object

StartPadding - the amount of time any recording for this Favorite should start before the actual Airing begins, in milliseconds

SetStopPadding

public void SetStopPadding(sage.Favorite Favorite,
                           long StopPadding)

Sets the amount of time any recording for this Favorite should stop after the actual Airing ends.

Parameters:

Favorite - the Favorite object

StopPadding - the amount of time any recording for this Favorite should stop after the actual Airing ends, in milliseconds

SetFavoriteQuality

public void SetFavoriteQuality(sage.Favorite Favorite,
                               java.lang.String Quality)

Sets the name of the recording quality that should be used when recording this Favorite.

Parameters:

Favorite - the Favorite object

Quality - the name of the recording quality that should be used when recording this Favorite, the empty string if the default recording quality should be used

SetFavoriteAutomaticConversionFormat

public void SetFavoriteAutomaticConversionFormat(sage.Favorite Favorite,
                                                 java.lang.String Format)

Sets the name of the format to transcode this Favorite to after a recording has been completed. Format names should come from GetTranscodeFormats(). Use the empty string or null to disable automatic conversion for this Favorite.

Parameters:

Favorite - the Favorite object

Format - the name of the transcode format to use when converting recordings of this Favorite; the empty string or null to disable automatic conversion

Since:

7.0

SetFavoriteAutomaticConversionDestination

public void SetFavoriteAutomaticConversionDestination(sage.Favorite Favorite,
                                                      java.io.File Folder)

Sets the directory that automatic conversions of this favorite should be saved to. Use null to use the same directory the recording is in.

Parameters:

Favorite - the Favorite object

Folder - the destination directory for the automatic conversions of this Favorite; null to use the same directory as the recording directory

Since:

7.0

CreateFavoritePriority

public void CreateFavoritePriority(sage.Favorite HigherPriorityFavorite,
                                   sage.Favorite LowerPriorityFavorite)

Establishes a priority of one Favorite over another. This will take undo any previous prioritization that it directly conflicts with. Favorites with a higher priority will be recorded over ones with a lower priority if there's a case where both cannot be recorded at once.

Parameters:

HigherPriorityFavorite - the Favorite object that you wish to make a higher priority than the other specified Favorite object

LowerPriorityFavorite - the Favorite object that you wish to make a lower priority than the other specified Favorite object

ConfirmManualRecordOverFavoritePriority

public void ConfirmManualRecordOverFavoritePriority(sage.Airing ManualRecordAiring,
                                                    sage.Airing FavoriteAiring)

Confirms that the user is aware that a manual recording they've selected creates a conflict with this favorite recording. This is purely for notifcation purposes.

Parameters:

ManualRecordAiring - the manual record Airing object to confirm the recording priority of

FavoriteAiring - the Airing for the Favorite that won't be recorded due to the manual record

SetDontAutodelete

public void SetDontAutodelete(sage.Favorite Favorite,
                              boolean DontAutoDelete)

Sets whether or not SageTV is allowed to automatically delete recordings of this Favorite when it needs more disk space. If this is true, then SageTV will never automatically delete files recorded for this Favorite; the user will have to delete the files themself.

Parameters:

Favorite - the Favorite object

DontAutoDelete - true if this Favorite is configured to NOT auto delete, false otherwise

SetDeleteAfterAutomaticConversion

public void SetDeleteAfterAutomaticConversion(sage.Favorite Favorite,
                                              boolean DeleteAfterAutomaticConversion)

Sets whether or not SageTV should delete the original file after doing an automatic conversion for this Favorite

Parameters:

Favorite - the Favorite object

DeleteAfterAutomaticConversion - true if this Favorite is configured to delete the source file after automatic conversion

Since:

7.0

SetKeepAtMost

public void SetKeepAtMost(sage.Favorite Favorite,
                          int NumberToKeep)

Sets the maximum number of recordings that match this Favorite that should be kept on disk. If AutoDelete is set to true then SageTV will continue to record new airings of this Favorite as they air, and delete the oldest recording on disk if it hits the keep at most limit. If AutoDelete is false then SageTV will stop recording this Favorite once it has this many recordings on disk

Parameters:

Favorite - the Favorite object

NumberToKeep - the maximum number of recordings SageTV should keep on disk of this Favorite, 0 if it is unlimited

SetRunStatus

public boolean SetRunStatus(sage.Favorite Favorite,
                            boolean FirstRuns,
                            boolean ReRuns)

Sets whether first runs, reruns or both types of airings should be recorded for this Favorite. If both arguments are false, SageTV will record both first runs and reruns.

Parameters:

Favorite - the Favorite object

FirstRuns - true if first runs should be recorded with this favorite, false otherwise

ReRuns - true if reruns should be recorded with this Favorite, false otherwise

Returns:

true if the change was successful, false if the change would alter this Favorite to be identical to an existing Favorite or if the user doesn't have permissions to make this change

SetFavoriteTitle

public boolean SetFavoriteTitle(sage.Favorite Favorite,
                                java.lang.String Title)

Sets the title that an Airing must match to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Title - the title that an Airing must match to be included in this Favorite, use the empty string or null if the title isn't a field that needs to match

Returns:

true if the change was successful, false if the change would alter this Favorite to be identical to an existing Favorite or if the user doesn't have permissions to make this change

SetFavoriteCategories

public boolean SetFavoriteCategories(sage.Favorite Favorite,
                                     java.lang.String Category,
                                     java.lang.String SubCategory)

Sets the category and optionally the subcategory that an Airing must match to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Category - the category that an Airing must match to be included in this Favorite, use the empty string or null if the category isn't a field that needs to match

SubCategory - the category that an Airing must match to be included in this Favorite, use the empty string the subcategory doesn't need to match

Returns:

true if the change was successful, false if the change would alter this Favorite to be identical to an existing Favorite or if the user doesn't have permissions to make this change

SetFavoritePerson

public boolean SetFavoritePerson(sage.Favorite Favorite,
                                 sage.Person Person,
                                 java.lang.String Role)

Sets a person (and optionally the role the person must appear in) that must be in an Airing for it to be included in this Favorite

Parameters:

Favorite - the Favorite object

Person - the name of the person that needs to be included in an Airing for it to match this Favorite, use the empty string or null if person doesn't need to match

Role - the name of the role the corresponding person needs to be in, or the emptry string or null if role doesn't matter

Returns:

true if the change was successful, false if the change would alter this Favorite to be identical to an existing Favorite or if the user doesn't have permissions to make this change

SetFavoriteRated

public boolean SetFavoriteRated(sage.Favorite Favorite,
                                java.lang.String Rated)

Sets the rating that an Airing must match to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Rated - the rating that an Airing must match to be included in this Favorite, use the empty string or null if rating isn't a field that needs to match

Returns:

true if the change was successful, false if the change would alter this Favorite to be identical to an existing Favorite or if the user doesn't have permissions to make this change

SetFavoriteYear

public boolean SetFavoriteYear(sage.Favorite Favorite,
                               java.lang.String Year)

Sets the year that an Airing must match to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Year - the year that an Airing must match to be included in this Favorite, use the empty string or null if year isn't a field that needs to match

Returns:

true if the change was successful, false if the change would alter this Favorite to be identical to an existing Favorite or if the user doesn't have permissions to make this change

SetFavoriteParentalRating

public boolean SetFavoriteParentalRating(sage.Favorite Favorite,
                                         java.lang.String ParentalRating)

Sets the parental rating that an Airing must match to be included in this Favorite.

Parameters:

Favorite - the Favorite object

ParentalRating - the parental rating that an Airing must match to be included in this Favorite, use the empty string or null if parental rating isn't a field that needs to match

Returns:

true if the change was successful, false if the change would alter this Favorite to be identical to an existing Favorite or if the user doesn't have permissions to make this change

SetFavoriteKeyword

public boolean SetFavoriteKeyword(sage.Favorite Favorite,
                                  java.lang.String Keyword)

Sets the keyword string that an Airing must match to be included in this Favorite. This is case insensitive. Double quotes can be used to require word to be in a certain order. Otherwise; each individual word is searched for in the Airing's details and must match a whole word for the match to succeed. The * character can be used to match 0 or more characters. The ? character can be used to match a single character. Regex is the matching language used for this so any other regex parsing characters besides * and ? can be used. All of the fields of the object are searched as part of this.

Parameters:

Favorite - the Favorite object

Keyword - the keyword that an Airing must match to be included in this Favorite, use the empty string or null if keyword doesn't matter

Returns:

true if the change was successful, false if the change would alter this Favorite to be identical to an existing Favorite or if the user doesn't have permissions to make this change

SetFavoriteChannel

public boolean SetFavoriteChannel(sage.Favorite Favorite,
                                  java.lang.Object Channel)

Sets the channel name (call sign) that an Airing must be on to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Channel - the channel name (String) or Channel object (Channel) that an Airing must be on to be included in this Favorite, use null or the empty string if channel doesn't matter; you may also use a semicolon or comma-delimited list of channel names for mult-channel favorites

Returns:

true if the change was successful, false if the change would alter this Favorite to be identical to an existing Favorite or if the user doesn't have permissions to make this change

SetFavoriteNetwork

public boolean SetFavoriteNetwork(sage.Favorite Favorite,
                                  java.lang.String Network)

Sets the network name that an Airing must be on to be included in this Favorite.

Parameters:

Favorite - the Favorite object

Network - the network name that an Airing must be on to be included in this Favorite, use null or the empty string if network doesn't matter

Returns:

true if the change was successful, false if the change would alter this Favorite to be identical to an existing Favorite or if the user doesn't have permissions to make this change

SetFavoriteTimeslot

public boolean SetFavoriteTimeslot(sage.Favorite Favorite,
                                   java.lang.String Timeslot)

Sets the timeslot that an Airing must be in to be included in this Favorite. It just needs to overlap the timeslot.

Parameters:

Favorite - the Favorite object

Timeslot - the timeslot that an Airing must be in to be included in this Favorite, use null or the empty string if timeslot doesn't matter. The timeslot should be in one of three formats: 1) Day Time, 2) Day, 3) Time. Where Day is a day of the week, and Time is an hour of the day such as 3pm or 8:00 (if the user's locale uses am/pm then it'll be like 3pm, otherwise it'll use like 8:00). Multiple timeslots are allowed and should be sent as a semicolon delimited list; an Airing only needs to overlap one of the timeslots to match the Favorite then. Multiple timeslots must also all be of the same type (i.e. all DayTime, all Day or all Time).

Returns:

true if the change was successful, false if the change would alter this Favorite to be identical to an existing Favorite or if the user doesn't have permissions to make this change

SetFavoriteEnabled

public void SetFavoriteEnabled(sage.Favorite Favorite,
                               boolean Enabled)

Sets whether or not SageTV will use this favorite when scheduling recordings

Parameters:

Favorite - the Favorite object

Enabled - true if this Favorite is to be used for scheduling, false otherwise

Since:

9.0

GetFavoriteForAiring

public sage.Favorite GetFavoriteForAiring(sage.Airing Airing)

Gets the Favorite that matches this Airing if one exists.

Parameters:

Airing - the Airing object to get a matching Favorite for

Returns:

a Favorite object that matches this Airing or null if there is no such Favorite

GetFavoritesForAiring

public sage.Favorite[] GetFavoritesForAiring(sage.Airing Airing)

Gets the list of all Favorites that match this Airing

Parameters:

Airing - the Airing object to get the matching Favorites for

Returns:

a Favorite array who's elements all match this Airing

Since:

8.0

DoesFavoriteMatchAiring

public boolean DoesFavoriteMatchAiring(sage.Favorite Favorite,
                                       sage.Airing Airing)

Returns true if the specified Favorite object matches the specified Airing object.

Parameters:

Favorite - the Favorite object to test

Airing - the Airing object to test

Returns:

true if the specified Favorite matches the specified Airing, false otherwise

IsFavoriteObject

public boolean IsFavoriteObject(java.lang.Object Favorite)

Returns true if the argument is a Favorite object, false otherwise

Parameters:

Favorite - an object to test to see if its an instance of Favorite

Returns:

true if the argument is an instance of a Favorite object, false otherwise

UpdateFavorite

public sage.Favorite UpdateFavorite(sage.Favorite Favorite,
                                    java.lang.String Title,
                                    boolean FirstRuns,
                                    boolean ReRuns,
                                    java.lang.String Category,
                                    java.lang.String SubCategory,
                                    sage.Person Person,
                                    java.lang.String RoleForPerson,
                                    java.lang.String Rated,
                                    java.lang.String Year,
                                    java.lang.String ParentalRating,
                                    java.lang.String Network,
                                    java.lang.String ChannelCallSign,
                                    java.lang.String Timeslot,
                                    java.lang.String Keyword)

Updates all of the fields of a Favorite that can be used to match. The rules for the arguments are specified in the individual methods that allow settting of the corresponding parameter.

Parameters:

Favorite - the Favorite object to update

Title - the title that an Airing must match to be included in this Favorite, use the empty string or null if the title isn't a field that needs to match

FirstRuns - true if this Favorite should match First Runs, false otherwise

ReRuns - true if this Favorite should match ReRuns, false otherwise

Category - the category that an Airing must match to be included in this Favorite, use the empty string or null if category isn't a field that needs to match

SubCategory - the subcategory that an Airing must match to be included in this Favorite, use the empty string or null if subcategory isn't a field that needs to match

Person - the name of the person that needs to be included in an Airing for it to match this Favorite, use the empty string or null if person doesn't need to match

RoleForPerson - the name of the role the corresponding person needs to be in, or the emptry string or null if role doesn't matter

Rated - the rating that an Airing must match to be included in this Favorite, use the empty string or null if rating isn't a field that needs to match

Year - the year that an Airing must match to be included in this Favorite, use the empty string or null if year isn't a field that needs to match

ParentalRating - the parental rating that an Airing must match to be included in this Favorite, use the empty string or null if parental rating isn't a field that needs to match

Network - the network name that an Airing must be on to be included in this Favorite, use null or the empty string if network doesn't matter

ChannelCallSign - the channel name that an Airing must be on to be included in this Favorite, use null or the empty string if channel doesn't matter; you may also use a semicolon or comma-delimited list of channel names for mult-channel favorites

Timeslot - the timeslot that an Airing must be in to be included in this Favorite, use null or the empty string if timeslot doesn't matter. The timeslot should be in one of three formats: 1) Day Time, 2) Day, 3) Time. Where Day is a day of the week, and Time is an hour of the day such as 3pm or 8:00 (if the user's locale uses am/pm then it'll be like 3pm, otherwise it'll use like 8:00) Multiple timeslots are allowed and should be sent as a semicolon delimited list; an Airing only needs to overlap one of the timeslots to match the Favorite then. Multiple timeslots must also all be of the same type (i.e. all DayTime, all Day or all Time).

Keyword - the keyword that an Airing must match to be included in this Favorite, use the empty string or null if keyword doesn't matter

Returns:

the updated Favorite object, or if the changes would make this Favorite the same as an existing Favorite, the other existing Favorite is returned, null is returned if there was no valid criteria specified in the arguments

GetFavoriteAirings

public sage.Airing[] GetFavoriteAirings(sage.Favorite Favorite)

Returns a list of all of the Airings in the database that match this Favorite. If this Favorite is disabled, no Airings will be returned. To get a list of Airings that match a disabled Favorite, call GetPotentialFavoriteAirings instead.

Parameters:

Favorite - the Favorite object

Returns:

the list of Airings in the DB that match this Favorite

GetFavoriteID

public int GetFavoriteID(sage.Favorite Favorite)

Gets a unique ID for this Favorite which can be used with GetFavoriteForID() for retrieving the object later.

Parameters:

Favorite - the Favorite object

Returns:

the unique ID for this Favorite

GetFavoriteForID

public sage.Favorite GetFavoriteForID(int FavoriteID)

Gets the Favorite object with the corresponding ID from the database. Use with GetFavoriteID()

Parameters:

FavoriteID - the ID to look up in the DB for a Favorite object

Returns:

the Favorite object with the specified ID if it exists, null otherwise

GetFavorites

public sage.Favorite[] GetFavorites()

Gets all of the Favorite objects from the database

Returns:

all of the Favorite objects in the database

RemoveFavorite

public void RemoveFavorite(sage.Favorite Favorite)

Removes a Favorite object from the database. Airings matching this Favorite will not necesarilly be automatically recorded anymore (intelligent recording may still record them)

Parameters:

Favorite - the Favorite object to remove

AddFavorite

public sage.Favorite AddFavorite(java.lang.String Title,
                                 boolean FirstRuns,
                                 boolean ReRuns,
                                 java.lang.String Category,
                                 java.lang.String SubCategory,
                                 sage.Person Person,
                                 java.lang.String RoleForPerson,
                                 java.lang.String Rated,
                                 java.lang.String Year,
                                 java.lang.String ParentalRating,
                                 java.lang.String Network,
                                 java.lang.String ChannelCallSign,
                                 java.lang.String Timeslot,
                                 java.lang.String Keyword)

Creates a new Favorite object in SageTV. Airings that match this Favorite will be recorded and saved into the SageTV Recordings.

Parameters:

Title - the title that an Airing must match to be included in this Favorite, use the empty string or null if the title isn't a field that needs to match

FirstRuns - true if this Favorite should match First Runs, false otherwise

ReRuns - true if this Favorite should match ReRuns, false otherwise (if both FirstRuns and ReRuns are false, then it will match both)

Category - the category that an Airing must match to be included in this Favorite, use the empty string or null if category isn't a field that needs to match

SubCategory - the subcategory that an Airing must match to be included in this Favorite, use the empty string or null if subcategory isn't a field that needs to match

Person - the name of the person that needs to be included in an Airing for it to match this Favorite, use the empty string or null if person doesn't need to match

RoleForPerson - the name of the role the corresponding person needs to be in, or the emptry string or null if role doesn't matter

Rated - the rating that an Airing must match to be included in this Favorite, use the empty string or null if rating isn't a field that needs to match

Year - the year that an Airing must match to be included in this Favorite, use the empty string or null if year isn't a field that needs to match

ParentalRating - the parental rating that an Airing must match to be included in this Favorite, use the empty string or null if parental rating isn't a field that needs to match

Network - the network name that an Airing must be on to be included in this Favorite, use null or the empty string if network doesn't matter

ChannelCallSign - the channel name that an Airing must be on to be included in this Favorite, use null or the empty string if channel doesn't matter; you may also use a semicolon or comma-delimited list of channel names for multi-channel favorites

Timeslot - the timeslot that an Airing must be in to be included in this Favorite, use null or the empty string if timeslot doesn't matter. The timeslot should be in one of three formats: 1) Day Time, 2) Day, 3) Time. Where Day is a day of the week, and Time is an hour of the day such as 3pm or 8:00 (if the user's locale uses am/pm then it'll be like 3pm, otherwise it'll use like 8:00) Multiple timeslots are allowed and should be sent as a semicolon delimited list; an Airing only needs to overlap one of the timeslots to match the Favorite then. Multiple timeslots must also all be of the same type (i.e. all DayTime, all Day or all Time).

Keyword - the keyword that an Airing must match to be included in this Favorite, use the empty string or null if keyword doesn't matter

Returns:

the newly created Favorite object, null is returned if there was no valid criteria specified in the arguments

GetFavoriteProperty

public java.lang.String GetFavoriteProperty(sage.Favorite Favorite,
                                            java.lang.String PropertyName)

Returns a property value for a specified Favorite. This must have been set using SetFavoriteProperty. Returns the empty string when the property is undefined.

Parameters:

Favorite - the Favorite object

PropertyName - the name of the property

Returns:

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

Since:

7.0

SetFavoriteProperty

public void SetFavoriteProperty(sage.Favorite Favorite,
                                java.lang.String PropertyName,
                                java.lang.String PropertyValue)

Sets a property for this Favorite. 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 Favorite. This only impacts the return values from GetFavoriteProperty and has no other side effects.

Parameters:

Favorite - the Favorite object

PropertyName - the name of the property

PropertyValue - the value of the property

Since:

7.0

GetFavoriteProperties

public java.util.Properties GetFavoriteProperties(sage.Favorite Favorite)

Returns a java.util.Properties object that has all of the user-set properties for this Favorite in it.

Parameters:

Favorite - the Favorite object

Returns:

a java.util.Properties object that has all of the user-set properties for this Favorite in it; this is a copy of the original one so it is safe to modify it

Since:

7.1