Package sage.api

Provides the details of the SageTV Studio API commands.

See:
Description

Class Summary

AiringAPI	Airing is the 'meta' object used to access content.
AlbumAPI	Represents an Album of music.
CaptureDeviceAPI	Represents a capture card or network encoder which is used to record TV.
CaptureDeviceInputAPI	Represents an specific input on a CaptureDevice such as the TV Tuner, Composite or S-Video inputs
ChannelAPI	A Channel represents a logical station on a broadcast, cable or satellite lineup.
Configuration	Configuration and properties for the whole system
Database	Contains methods for manipulating database objects in SageTV as well as doing general database queries NOTE: All of the 'Search' methods will be limited to 1000 results.
FavoriteAPI	Favorites are objects which are used for repeated recording in SageTV
Global	System methods used for dealing with Sage specifics
LocatorAPI
MediaFileAPI	A MediaFile represents a physical file or a group of files that represent the same content.
MediaNodeAPI	Virtual content directory abstraction.
MediaPlayerAPI	Calls for playing back media in SageTV and for controlling that playback
PlaylistAPI	Calls for creating, editing, removing and querying playlists in the system
PluginAPI	API calls to be used for downloading, enabling and disabling of SageTV Plugins from the central repository.
SeriesInfoAPI
ShowAPI	Show represents detailed information about content.
SystemMessageAPI
TranscodeAPI
TVEditorialAPI
Utility	Contains miscellaneous methods useful for a variety of purposes
WidgetAPI	Widget reflection API

Package sage.api Description

Provides the details of the SageTV Studio API commands.

Package Specification

The API calls here are documented using Javadoc from Sun Microsystems. It's IMPORTANT to realize that this documentation does NOT corresponds to actual Java Objects are Java API calls that can be made. The API calls outlined in this documentation can be utilized in 2 ways described below.

Using the API in SageTV Studio Expressions

In the SageTV Studio, expressions are used for various different purposes. They can be Actions, Conditionals, Attribute values, dynamic properties for example. These expressions may have 'functions' in them. A function is defined as a word with parenthesis after it such as foo(), or a word with parenthesis that contain a comma delimited list of arguments such as foo(x, y). If you remember back to the days of Algebra, you may find this concept familiar. When SageTV needs to determine what a function actually does, it has 2 techniques it uses to look it up. First it checks the SageTV API, which is documented here. A valid expression for this could be:

GetMediaFileTitle(GetCurrentMediaFile())

That expression will return the title of the currently playing media file. The SageTV API uses Java objects for all arguments and return values. Primitive types are boxed/unboxed automatically by SageTV using the primitive object types (i.e. Integer, Long, etc.). Arrays are also used on occassion as well as components of the java.util package. If the function cannot be found in the SageTV API, then SageTV will replace any '_' characters in the function name with '.' characters (to convert to java package separators) and then attempt to dynamically load the corresponding Java class and check for a corresponding method with matching argument types. For example:

java_io_File_length(GetFileForSegment(GetCurrentMediaFile(), 0))

Using the API directly from Java code

The SageTV API calls can also be invoked from Java code directly. To do this, you can use the following static method in the sage.SageTV class:

public static Object api(String methodName, Object[] methodArgs) throws java.lang.reflect.InvocationTargetException;

The methodName parameter should be the name of the SageTV API call and the method Args should be an array of the arguments to pass to the API call. It is safe to use null for methodArgs if the call has no arguments. If an exception is thrown during execution of the SageTV API call then the exception will be wrapped in an InvocationTargetException and thrown.

NOTE:As of SageTV 4.1, multiple user interfaces may be run inside one process when SageTV is using media extenders. This means that some API calls have a user interface context associated with them. When invoking SageTV API calls directly from Java, there is now an option to specify the targeted user interface for the API call. By default, all method calls made using the api call that need a user interface context will use the local user interface context. This corresponds to the SageTV application running on the PC. A new static method call has also been added which allows specifying the targeted user interface context:

public static Object apiUI(String uiContextName, String methodName, Object[] methodArgs) throws java.lang.reflect.InvocationTargetException;

The uiContextName parameter is the name of the user interface context to use. The current list of user interface context names can be obtained by calling GetUIContextNames() in the Global API.

To compile code that uses this, just put the Sage.jar file in the classpath of your Java compiler.

A very thorough example of using the SageTV API from Java can be seen in the Webserver plugin developed by Nielm. The code for that project is publicly available on Sourceforge.net in the 'sageplugins' project.

Below is a simple code chunk which can be compiled and then added to the load_at_startup_runnable_classes property in SageTV. It gets a list of all of the files in the DB, and then gets a list of all the segment files for each file. Then it prints out the file path and then file size on each line in a file named "filelist.txt" in the current working directory.

public class SageTVAPITest implements Runnable
{
        public void run()
        {
                // Get all of the MediaFiles in the system and print their file paths to a file along with their file sizes
                try
                {
                        java.io.PrintWriter writer = new java.io.PrintWriter(new java.io.FileWriter("filelist.txt"));
                        Object[] mediaFiles = (Object[])sage.SageTV.api("GetMediaFiles", null);
                        for (int i = 0; i < mediaFiles.length; i++)
                        {
                                Object currFile = mediaFiles[i];
                                int numSubFiles = ((Integer)sage.SageTV.api("GetNumberOfSegments", new Object[] { currFile })).intValue();
                                for (int j = 0; j < numSubFiles; j++)
                                {
                                        java.io.File theFile = (java.io.File) sage.SageTV.api("GetFileForSegment", new Object[] { currFile, new Integer(j) });
                                        writer.println(theFile.toString() + " " + theFile.length());
                                }
                        }
                        writer.close();
                }
                catch (java.io.IOException e1)
                {
                        System.out.println("I/O Error:" + e1);
                }
                catch (java.lang.reflect.InvocationTargetException e)
                {
                        System.out.println("ERROR invoking SageTV API calls of: " + e.toString());
                }
        }
}