Package sage.api

Class ChannelAPI

java.lang.Object

sage.api.ChannelAPI

public class ChannelAPI
extends java.lang.Object

A Channel represents a logical station on a broadcast, cable or satellite lineup.

Channel numbers always refer to logical channel numbers EXCEPT when they are explicitly stated to refer to physical channel numbers.

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

Airing - every Airing has an associated Channel, that Channel is used

MediaFile - due to the 1:1 mapping between MediaFiles and Airings, the MediaFile is resolved to an Airing and then to a Channel

Constructor Summary

Constructors

Constructor	Description
ChannelAPI()

Method Summary

Modifier and Type	Method	Description
sage.Channel	AddChannel(java.lang.String CallSign, java.lang.String Name, java.lang.String Network, int StationID)	Adds a new Channel to the database.
void	ClearChannelMappingOnLineup(sage.Channel Channel, java.lang.String Lineup)	Clears any associated channel mappings that were created for this Channel on the specified Lineup
void	ClearPhysicalChannelMappingsOnLineup(sage.Channel Channel, java.lang.String Lineup)	Clears any associated physical channel mappings that were created for this Channel on the specified Lineup
sage.Channel[]	GetAllChannels()	Returns all of the Channels that are defined in the system
java.lang.String	GetChannelDescription(sage.Channel Channel)	Gets the descriptive name for this Channel.
sage.Channel	GetChannelForStationID(int StationID)	Returns the Channel object that has the corresponding station ID.
sage.MetaImage	GetChannelLogo(sage.Channel Channel)	Gets the logo image for the specified Channel if one exists
sage.MetaImage	GetChannelLogo(sage.Channel Channel, java.lang.String Type, int Index, boolean Fallback)	Returns a Channel logo for the requested Channel if one exists.
int	GetChannelLogoCount(sage.Channel Channel)	Returns a count of logos for this channel.
java.lang.String	GetChannelLogoURL(sage.Channel Channel)	Gets the URL of the logo image for the specified Channel if one exists
java.lang.String	GetChannelLogoURL(sage.Channel Channel, java.lang.String Type, int Index, boolean Fallback)	Returns a Channel logo URL for the requested Channel if one exists.
java.lang.String	GetChannelName(sage.Channel Channel)	Gets the name for this Channel.
java.lang.String	GetChannelNetwork(sage.Channel Channel)	Gets the name of the associated network for this Channel.
java.lang.String	GetChannelNumber(sage.Channel Channel)	Gets the channel number to tune to for this Channel.
java.lang.String	GetChannelNumberForLineup(sage.Channel Channel, java.lang.String Lineup)	Gets the channel number to tune to for this Channel on the specified lineup.
java.lang.String[]	GetChannelNumbersForLineup(sage.Channel Channel, java.lang.String Lineup)	Gets the channel numbers which can be used to tune this Channel on the specified lineup.
java.lang.String	GetPhysicalChannelNumberForLineup(sage.Channel Channel, java.lang.String Lineup)	Gets the physical channel number to tune to for this Channel on the specified lineup.
int	GetStationID(sage.Channel Channel)	Returns an ID which can be used with GetChannelForStationID() for doing keyed lookups of Channel objects
boolean	IsChannelObject(sage.Channel Channel)	Returns true if the argument is a Channel object.
boolean	IsChannelRemappedOnLineup(sage.Channel Channel, java.lang.String Lineup)	Returns true if the user has remapped this Channel to a different number than it's default on the specified Lineup
boolean	IsChannelViewable(sage.Channel Channel)	Returns true if there is a configured lineup for which this channel is viewable.
boolean	IsChannelViewableOnLineup(sage.Channel Channel, java.lang.String Lineup)	Returns true if this Channel is viewable on the specified Lineup
boolean	IsChannelViewableOnNumberOnLineup(sage.Channel Channel, java.lang.String ChannelNumber, java.lang.String Lineup)	Returns true if this Channel is viewable on the specified Lineup on the specified channel number
boolean	IsPhysicalChannelRemappedOnLineup(sage.Channel Channel, java.lang.String Lineup)	Returns true if the user has remapped this physical Channel to a different physical number than it's default on the specified Lineup
void	SetChannelMappingForLineup(sage.Channel Channel, java.lang.String Lineup, java.lang.String NewNumber)	Maps a channel on a lineup to a new channel number.
void	SetChannelMappingsForLineup(sage.Channel Channel, java.lang.String Lineup, java.lang.String[] NewNumbers)	Maps a channel on a lineup to a new channel number(s).
void	SetChannelViewabilityForChannelNumberOnLineup(sage.Channel Channel, java.lang.String ChannelNumber, java.lang.String Lineup, boolean Viewable)	Sets whether or not the specified Channel is viewable on the specified number on the specified Lineup
void	SetChannelViewabilityForChannelOnLineup(sage.Channel Channel, java.lang.String Lineup, boolean Viewable)	Sets whether or not the specified Channel is viewable on the specified Lineup.
void	SetPhysicalChannelMappingForLineup(sage.Channel Channel, java.lang.String Lineup, java.lang.String NewNumber)	Maps a Channel on a lineup to a new physical channel number.

Methods inherited from class java.lang.Object

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

Constructor Detail

ChannelAPI

public ChannelAPI()

Method Detail

GetChannelDescription

public java.lang.String GetChannelDescription(sage.Channel Channel)

Gets the descriptive name for this Channel. This is the longer text string.

Parameters:

Channel - the Channel Object

Returns:

the longer descriptive name for the specified Channel

GetChannelName

public java.lang.String GetChannelName(sage.Channel Channel)

Gets the name for this Channel. This is the Channel's call sign.

Parameters:

Channel - the Channel Object

Returns:

the name (call sign) for the specified Channel

GetChannelNetwork

public java.lang.String GetChannelNetwork(sage.Channel Channel)

Gets the name of the associated network for this Channel. This is a way of grouping kinds of Channels together.

Parameters:

Channel - the Channel Object

Returns:

the network name for the specified Channel

GetChannelNumber

public java.lang.String GetChannelNumber(sage.Channel Channel)

Gets the channel number to tune to for this Channel. SageTV will return the first channel number it finds for this Channel since there may be multiple ones.

Parameters:

Channel - the Channel Object

Returns:

a channel number associated with this Channel

GetChannelNumberForLineup

public java.lang.String GetChannelNumberForLineup(sage.Channel Channel,
                                                  java.lang.String Lineup)

Gets the channel number to tune to for this Channel on the specified lineup. SageTV will return the first channel number it finds for this Channel on the lineup since there may be multiple ones.

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

Returns:

the channel number for the specified Channel on the specified Lineup

GetPhysicalChannelNumberForLineup

public java.lang.String GetPhysicalChannelNumberForLineup(sage.Channel Channel,
                                                          java.lang.String Lineup)

Gets the physical channel number to tune to for this Channel on the specified lineup.

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

Returns:

the physical channel number for the specified Channel on the specified Lineup

Since:

5.1

IsChannelViewable

public boolean IsChannelViewable(sage.Channel Channel)

Returns true if there is a configured lineup for which this channel is viewable.

Parameters:

Channel - the Channel object

Returns:

true if there is a configured lineup for which this channel is viewable.

IsChannelViewableOnLineup

public boolean IsChannelViewableOnLineup(sage.Channel Channel,
                                         java.lang.String Lineup)

Returns true if this Channel is viewable on the specified Lineup

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

Returns:

true if this Channel is viewable on the specified Lineup

IsChannelViewableOnNumberOnLineup

public boolean IsChannelViewableOnNumberOnLineup(sage.Channel Channel,
                                                 java.lang.String ChannelNumber,
                                                 java.lang.String Lineup)

Returns true if this Channel is viewable on the specified Lineup on the specified channel number

Parameters:

Channel - the Channel object

ChannelNumber - the channel number to check

Lineup - the name of the Lineup

Returns:

true if this Channel is viewable on the specified Lineup on the specified channel number

GetChannelNumbersForLineup

public java.lang.String[] GetChannelNumbersForLineup(sage.Channel Channel,
                                                     java.lang.String Lineup)

Gets the channel numbers which can be used to tune this Channel on the specified lineup.

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

Returns:

the channel numbers for the specified Channel on the specified Lineup

ClearChannelMappingOnLineup

public void ClearChannelMappingOnLineup(sage.Channel Channel,
                                        java.lang.String Lineup)

Clears any associated channel mappings that were created for this Channel on the specified Lineup

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

IsChannelRemappedOnLineup

public boolean IsChannelRemappedOnLineup(sage.Channel Channel,
                                         java.lang.String Lineup)

Returns true if the user has remapped this Channel to a different number than it's default on the specified Lineup

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

Returns:

true if the user has remapped this Channel to a different number than it's default on the specified Lineup

SetChannelMappingForLineup

public void SetChannelMappingForLineup(sage.Channel Channel,
                                       java.lang.String Lineup,
                                       java.lang.String NewNumber)

Maps a channel on a lineup to a new channel number.

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

NewNumber - the new channel number to use for this Channel

SetChannelMappingsForLineup

public void SetChannelMappingsForLineup(sage.Channel Channel,
                                        java.lang.String Lineup,
                                        java.lang.String[] NewNumbers)

Maps a channel on a lineup to a new channel number(s).

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

NewNumbers - the new channel numbers to use for this Channel

Since:

6.4.3

ClearPhysicalChannelMappingsOnLineup

public void ClearPhysicalChannelMappingsOnLineup(sage.Channel Channel,
                                                 java.lang.String Lineup)

Clears any associated physical channel mappings that were created for this Channel on the specified Lineup

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

Since:

5.1

IsPhysicalChannelRemappedOnLineup

public boolean IsPhysicalChannelRemappedOnLineup(sage.Channel Channel,
                                                 java.lang.String Lineup)

Returns true if the user has remapped this physical Channel to a different physical number than it's default on the specified Lineup

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

Returns:

true if the user has remapped this physical Channel to a different number than it's default on the specified Lineup

Since:

5.1

SetPhysicalChannelMappingForLineup

public void SetPhysicalChannelMappingForLineup(sage.Channel Channel,
                                               java.lang.String Lineup,
                                               java.lang.String NewNumber)

Maps a Channel on a lineup to a new physical channel number.

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

NewNumber - the new phyical channel number to use for this Channel

Since:

5.1

GetStationID

public int GetStationID(sage.Channel Channel)

Returns an ID which can be used with GetChannelForStationID() for doing keyed lookups of Channel objects

Parameters:

Channel - the Channel object

Returns:

the station ID for the specified Channel

GetChannelLogo

public sage.MetaImage GetChannelLogo(sage.Channel Channel)

Gets the logo image for the specified Channel if one exists

Parameters:

Channel - the Channel object

Returns:

the logo image for the Channel

GetChannelLogo

public sage.MetaImage GetChannelLogo(sage.Channel Channel,
                                     java.lang.String Type,
                                     int Index,
                                     boolean Fallback)

Returns a Channel logo for the requested Channel if one exists. This can provide more detailed requests then the single argument GetChannelLogo call.

Parameters:

Channel - the Channel object

Type - the type of image, can be one of "Small", "Med" or "Large" (all logos have all sizes available, w/ the exception of user-supplied logos)

Index - the 0-based index of the image to retrieve when multiple images exist for a given Type (there are only ever 0, 1 or 2 logos for a channel)

Fallback - should be true if an alternate image is allowed (this enables checking user-supplied logos first, as well as falling back to the primary logo if a secondary one is requested but does not exist)

Returns:

a MetaImage corresponding to the requested image, or null if no image matching the requested parameters is found or an invalid Type is specified

Since:

7.1

IsChannelObject

public boolean IsChannelObject(sage.Channel Channel)

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

Parameters:

Channel - the object to test

Returns:

true if the argument is a Channel object

SetChannelViewabilityForChannelNumberOnLineup

public void SetChannelViewabilityForChannelNumberOnLineup(sage.Channel Channel,
                                                          java.lang.String ChannelNumber,
                                                          java.lang.String Lineup,
                                                          boolean Viewable)

Sets whether or not the specified Channel is viewable on the specified number on the specified Lineup

Parameters:

Channel - the Channel object

ChannelNumber - the channel number to set the viewability state for

Lineup - the name of the Lineup

Viewable - true if is viewable, false if it is not

SetChannelViewabilityForChannelOnLineup

public void SetChannelViewabilityForChannelOnLineup(sage.Channel Channel,
                                                    java.lang.String Lineup,
                                                    boolean Viewable)

Sets whether or not the specified Channel is viewable on the specified Lineup. This affects all channel numbers it appears on.

Parameters:

Channel - the Channel object

Lineup - the name of the Lineup

Viewable - true if is viewable, false if it is not

GetChannelForStationID

public sage.Channel GetChannelForStationID(int StationID)

Returns the Channel object that has the corresponding station ID. The station ID is retrieved using GetStationID()

Parameters:

StationID - the station ID to look up

Returns:

the Channel with the specified station ID

AddChannel

public sage.Channel AddChannel(java.lang.String CallSign,
                               java.lang.String Name,
                               java.lang.String Network,
                               int StationID)

Adds a new Channel to the database. The CallSign should not match that of any other channel; but this rule is not enforced. The StationID is what is used as the unique key to identify a station. Be sure that if you're creating new station IDs they do not conflict with existing ones. The safest way to pick a station ID (if you need to at random) is to make it less than 10000 and ensure that no channel already exists with that station ID.

Parameters:

CallSign - the 'Name' to assign to the new Channel

Name - the 'Description' to assign to the new Channel

Network - the 'Network' that the Channel is part of (can be "")

StationID - the unique ID to give to this Channel

Returns:

the newly created Channel object, if the station ID is already in use it will return the existing Channel object, but updated with the passed in values

GetAllChannels

public sage.Channel[] GetAllChannels()

Returns all of the Channels that are defined in the system

Returns:

all of the Channel objects that are defined in the system

GetChannelLogoCount

public int GetChannelLogoCount(sage.Channel Channel)

Returns a count of logos for this channel. This will either be 0, 1 or 2. This does NOT include user-supplied channel logos. Since all channel logos have all types, this does not require a type argument.

Parameters:

Channel - the Channel object

Returns:

the number of logos for the specified Channel (does NOT include user-supplied logos)

Since:

7.1

GetChannelLogoURL

public java.lang.String GetChannelLogoURL(sage.Channel Channel)

Gets the URL of the logo image for the specified Channel if one exists

Parameters:

Channel - the Channel object

Returns:

the URL of the logo image for the Channel

Since:

8.0

GetChannelLogoURL

public java.lang.String GetChannelLogoURL(sage.Channel Channel,
                                          java.lang.String Type,
                                          int Index,
                                          boolean Fallback)

Returns a Channel logo URL for the requested Channel if one exists. This can provide more detailed requests then the single argument GetChannelLogoURL call.

Parameters:

Channel - the Channel object

Type - the type of image, can be one of "Small", "Med" or "Large" (all logos have all sizes available, w/ the exception of user-supplied logos)

Index - the 0-based index of the image to retrieve when multiple images exist for a given Type (there are only ever 0, 1 or 2 logos for a channel)

Fallback - should be true if an alternate image is allowed (this enables checking user-supplied logos first, as well as falling back to the primary logo if a secondary one is requested but does not exist)

Returns:

a URL corresponding to the requested image, or null if no image matching the requested parameters is found or an invalid Type is specified

Since:

8.0