SageTV Platform
V9.0

sage.api
Class FavoriteAPI

java.lang.Object
  extended by sage.api.FavoriteAPI

public class FavoriteAPI
extends java.lang.Object

Favorites are objects which are used for repeated recording in SageTV


Constructor Summary
FavoriteAPI()
           
 
Method Summary
 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.Object 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.Object 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.

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

SageTV Platform
V9.0

SageTV is a trademark or registered trademark of Google, Inc. in the US and other countries.
Copyright 2000-2015 The SageTV Authors. All Rights Reserved.