SageTV Platform
V9.0

sage.api
Class ChannelAPI

java.lang.Object
  extended by 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
ChannelAPI()
           
 
Method Summary
 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

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.