SageTV Platform
V9.0

sage.api
Class Utility

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

public class Utility
extends java.lang.Object

Contains miscellaneous methods useful for a variety of purposes


Constructor Summary
Utility()
           
 
Method Summary
 boolean AddElement(java.util.Collection Data, java.lang.Object Value)
          Add the element with the specified value to this data.
 boolean AddToGrouping(java.util.Map Grouping, java.lang.Object Key, java.lang.Object Value)
          Adds the specified value into the grouping using the specified key.
 boolean Animate(java.lang.String WidgetName, java.lang.String LayerName, java.lang.String AnimationName, long Duration)
          Starts an animation for the specified Widget in the specified Layer.
 boolean AnimateDelayed(java.lang.String WidgetName, java.lang.String LayerName, java.lang.String AnimationName, long Duration, long StartDelay, boolean Interruptable)
          This is the same as the Animate API call; but it allows specifiying a delay that should occur before the animation actually starts.
 boolean AnimateTransition(java.lang.String SourceWidgetName, java.lang.String TargetWidgetName, java.lang.String LayerName, java.lang.String AnimationName, long Duration, long StartDelay, boolean Interruptable)
          Performs an Animation between two different Widgets.
 boolean AnimateVariable(java.lang.String WidgetName, java.lang.String LayerName, java.lang.String VarName, java.lang.Object VarValue, java.lang.String AnimationName, long Duration, long StartDelay, boolean Interruptable)
          For more details on Animations see here: Animate() In addition to what's specified in the Animate API call; this also offers restricting of an Animation by a variable name and value.
 boolean AreCoreAnimationsEnabled()
          Returns whether or not animation support is enabled (either layered or Effect based animations; depending upon the STV configuration)
 boolean AreCoreAnimationsSupported()
          Returns whether or not animation support is possible in the current UI environment.
 java.lang.String CalculateMD5Sum(java.io.File FilePath)
          Calculates the MD5 Sum of a given file
 void ClearMenuCache()
          Clears the cache that links Widgets to the in memory-menu representations for this UI.
 java.lang.String ConvertNteChars(java.lang.String NteString)
          converts a string of NTE key characters (and normal characters) into their default character representation - given by the first character in the NTE chatacter list
The NTE key characters are the Unicode characters u2460-u2468 and u24EA (Unicode Circled Digits), representing the numeric Text Keys 1-9 and 0.
The characters represented by the keys are defined by the client properties "ui/numeric_text_input_<ui/translation_language_code>_<key>_lower.
 java.lang.Object[] CreateArray(java.lang.Object Value)
          Creates a java.lang.Object array and initializes each element to the passed in argument.
 java.io.File CreateFilePath(java.lang.String Directory, java.lang.String File)
          Creates a new file object for the specified directory and file name or relative path
 boolean CreateNewDirectory(java.io.File DirectoryPath)
          Creates a new directory and any parent directories for the specified directory path.
 boolean CreateNewLocalDirectory(java.io.File DirectoryPath)
          Creates a new local directory and any parent directories for the specified directory path.
 java.lang.Long[] CreateTimeSpan(long StartTime, long EndTime)
          Returns a length 2 Long object array which can be used for specifying a time span in a table.
 java.lang.String DateFormat(java.lang.String Format, java.lang.Object Date)
          Returns a formatted date string for the specified Date.
 boolean DeleteFilePath(java.io.File FilePath)
          Deletes the file/directory at the corresponding file path (directories must be empty first)
 boolean DeleteLocalFilePath(java.io.File FilePath)
          Deletes the file/directory at the corresponding local file path (directories must be empty first)
 boolean DidImageLoadFail(java.lang.Object Image)
          Checks whether the passed in MetaImage (from an API call that returns MetaImage), MediaFile, File, URL or Album failed to load successfully.
 java.io.File[] DirectoryListing(java.io.File DirectoryPath)
          Returns a list of the files in the specified directory
 java.io.File[] DirectoryListing(java.io.File DirectoryPath, java.lang.String MediaMask)
          Returns a list of the files in the specified directory.
 void DumpServerThreadStates()
          Dumps all the java stack information on the SageTV server process to the server's debug output stream
 java.lang.String DurFormat(java.lang.String Format, long Duration)
          Returns a formatted duration String for a period of time in milliseconds.
 java.lang.Process ExecuteProcess(java.lang.String CommandString, java.lang.Object Arguments, java.io.File WorkingDirectory, boolean ConsoleApp)
          Executes a new process on the system
 java.lang.String ExecuteProcessReturnOutput(java.lang.String CommandString, java.lang.Object Arguments, java.io.File WorkingDirectory, boolean ReturnStdout, boolean ReturnStderr)
          Executes a new process on the system and returns as a String the output of the process
 java.lang.Object FindComparativeElement(java.lang.Object Data, java.lang.Comparable Criteria, java.lang.String Method)
          Searches a sorted list of data to find the index that the specified criteria exists at; or if it doesn't exist in the data it will use the index that would be the appropriate insertion point for the criteria in the data in order to maintain sort order.
 int FindElementIndex(java.lang.Object Data, java.lang.Object Element)
          Returns the index in the data that the specified element is found at.
 java.lang.String GetAbsoluteFilePath(java.io.File FilePath)
          Returns the full path name from the specified file path..
 long GetDiskFreeSpace(java.lang.String DrivePath)
          Returns the amount of disk free space in bytes at the specified path
 long GetDiskTotalSpace(java.lang.String DrivePath)
          Returns the amount of total disk space in bytes at the specified path
 java.lang.String GetDNSAddress()
          Returns the DNS address for the currently configured network adapter.
 java.lang.Object GetElement(java.lang.Object Data, int Index)
          Returns the element at the specified index in this data; works for arrays and java.util.List implementations (i.e.
 java.lang.String GetFileAsString(java.io.File FilePath)
          Opens the file at the specified path and reads the entire contents of it and returns it as a String.
 java.lang.String GetFileExtensionFromPath(java.lang.String FilePath)
          Returns the file name extension from the specified file path (not including the '.')
 java.lang.String GetFileNameFromPath(java.io.File FilePath)
          Returns the file name from the specified file path; this just returns the filename without any path information.
 long GetFilePathSize(java.io.File FilePath)
          Returns the size in bytes of the specified file path
 java.io.File[] GetFileSystemRoots()
          Returns the root directories of the file systems (on Linux this'll just be / and on Windows it'll be the drive letters)
 java.lang.String GetFileSystemType(java.lang.String DrivePath)
          Gets the name of the filesystem type at the specified path
 java.lang.String GetGatewayAddress()
          Returns the gateway address for the currently configured network adapter.
 java.awt.image.BufferedImage GetImageAsBufferedImage(java.lang.Object Resource)
          Returns a java.awt.image.BufferedImage object.
 java.lang.String GetLocalFileAsString(java.io.File FilePath)
          Opens the file at the specified path and reads the entire contents of it and returns it as a String.
 long GetLocalFilePathSize(java.io.File FilePath)
          Returns the size in bytes of the specified local file path
 java.io.File[] GetLocalFileSystemRoots()
          Returns the root directories of the local file systems (on Linux this'll just be / and on Windows it'll be the drive letters)
 java.lang.String GetLocalIPAddress()
          Returns the IP address of the machine
 long GetLocalPathLastModifiedTime(java.io.File FilePath)
          Returns the last modified time of the specified local file path
 float GetMetaImageAspectRatio(sage.MetaImage MetaImage)
          Returns the aspect ratio of an image as a floating point number of width/height, zero if the image was a failed load or has not been loaded yet
 byte[] GetMetaImageBytes(sage.MetaImage MetaImage)
          Returns a byte array which is the contents of the MetaImage source's data (i.e.
 java.io.File GetMetaImageSourceFile(sage.MetaImage MetaImage)
          Returns the file path that a MetaImage was loaded from.
 long GetPathLastModifiedTime(java.io.File FilePath)
          Returns the last modified time of the specified file path
 java.io.File GetPathParentDirectory(java.io.File FilePath)
          Returns the parent directory for the specified file path
 java.awt.image.BufferedImage GetScaledImageAsBufferedImage(java.lang.Object Resource, int Width, int Height)
          Returns a java.awt.image.BufferedImage object.
 java.lang.Object GetSubgroup(java.util.Map Grouping, java.lang.Object Key)
          Gets the value for the specified key out of a map.
 java.lang.String GetSubnetMask()
          Returns the subnet mask for the currently configured network adapter.
 long GetTimeSinceLastInput()
          Returns the amount of time in milliseconds since the last user input occurred for this UI (used for doing things while the user is idle)
 boolean GetUIRefreshLock()
          Acquires the lock for this user interface system to prevent other updates from occuring.
 int GetWindowsRegistryDWORDValue(java.lang.String Root, java.lang.String Key, java.lang.String Name)
          Returns a DWORD value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)
 java.lang.String[] GetWindowsRegistryNames(java.lang.String Root, java.lang.String Key)
          Returns a list of the Windows registry names which exist under the specified root & key (Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)
 int GetWindowsRegistryStringValue(java.lang.String Root, java.lang.String Key, java.lang.String Name)
          Returns a string value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)
 java.lang.String GetWorkingDirectory()
          Returns the current working directory for the application (if this is a client; it'll be the working directory of the server)
 java.lang.String GuessMajorFileType(java.lang.String Filename)
          Guesses what media type the specified filename corresponds to.
 boolean HasLocalFilesystem()
          Returns true if this client has a local file system that can be accessed.
 java.lang.Object If(boolean Condition, java.lang.Object True, java.lang.Object False)
          Returns the second argument if the first argument is true, otherwise the third argument is returned.
 boolean IsDirectoryPath(java.lang.String FilePath)
          Returns true if the specified path denotes a directory that exists
 boolean IsEmpty(java.lang.Object Data)
          Returns true if the argument is null, zero, an empty string or a failed image load
 boolean IsFilePath(java.lang.String FilePath)
          Returns true if the specified file path denotes a file that exists and is not a directory
 boolean IsFilePathHidden(java.lang.String FilePath)
          Returns true if the specified file path is marked as a hidden file
 boolean IsImageLoaded(java.lang.Object Image)
          Checks whether the passed in MetaImage (from an API call that returns MetaImage), MediaFile, File, URL or Album is loaded into system memory or into the VRAM cache of the corresponding UI making the call.
 boolean IsImportableFileType(java.lang.String Filename)
          Returns true if the specified file path has a file extension which would be imported by SageTV into its library.
 boolean IsLocalDirectoryPath(java.lang.String FilePath)
          Returns true if the specified local path denotes a directory that exists
 boolean IsLocalFilePath(java.lang.String FilePath)
          Returns true if the specified local file path denotes a file that exists and is not a directory
 boolean IsLocalFilePathHidden(java.lang.String FilePath)
          Returns true if the specified local file path is marked as a hidden file
 boolean IsLocalRestartNeeded()
          Returns true if the local instance of SageTV needs to be restarted due to a plugin install/uninstall
 boolean IsMetaImage(java.lang.Object MetaImage)
          Returns true if the argument is a MetaImage object.
 boolean IsServerRestartNeeded()
          Returns true if the server instance of SageTV needs to be restarted due to a plugin install/uninstall
 void Keystroke(java.lang.String Character, boolean System)
          Executes the specified keystroke in either the SageTV event system or by emulation in the operating system
 sage.MetaImage LoadImage(java.lang.Object Resource)
          Returns a MetaImage object that refers to a specified image resource.
 sage.MetaImage LoadImageFile(java.io.File FilePath)
          Returns a MetaImage object that refers to the specified image file.
 java.io.File[] LocalDirectoryListing(java.io.File DirectoryPath)
          Returns a list of the files in the specified directory on the local filesystem
 java.lang.String LocalizeString(java.lang.String EnglishText)
          Returns a localized version of the specified string.
 java.lang.String LookupIPForLocatorID(java.lang.String LocatorID)
          Connects to the SageTV Locator server and submits the specified Locator ID for a IP lookup.
 java.lang.Number Max(java.lang.Number Value1, java.lang.Number Value2)
          Returns the maximum of the two arguments; the type of the returned argument will be the same as the highest precision argument
 java.lang.Number Min(java.lang.Number Value1, java.lang.Number Value2)
          Returns the minimum of the two arguments; the type of the returned argument will be the same as the highest precision argument
 java.lang.String NumberFormat(java.lang.String Format, float Number)
          Returns a formatted numeric string for the specified number.
 void PlaySound(java.lang.String SoundFile)
          Plays the specified sound file (used for sound effects, don't use for music playback)
 java.lang.String PrintCurrentTime()
          Returns a string that represents the current time.
 java.lang.String PrintDate(long Date)
          Returns a formatted date string using the java.text.DateFormat.MEDIUM formatting technique
 java.lang.String PrintDateFull(long Date)
          Returns a formatted date string using the java.text.DateFormat.FULL formatting technique
 java.lang.String PrintDateLong(long Date)
          Returns a formatted date string using SageTV's default detailed date formatting
 java.lang.String PrintDateShort(long Date)
          Returns a formatted date string using the java.text.DateFormat.SHORT formatting technique
 java.lang.String PrintDuration(long Duration)
          Returns a formatted duration string according to SageTV's verbose duration formating, minutes is the most detailed resolution of this format
 java.lang.String PrintDurationShort(long Duration)
          Returns a formatted duration string according to SageTV's concise duration formating, minutes is the most detailed resolution of this format
 java.lang.String PrintDurationWithSeconds(long Duration)
          Returns a formatted duration string according to SageTV's default duration formating, seconds is the most detailed resolution of this format
 java.lang.String PrintTime(long Time)
          Returns a formatted time string using the java.text.DateFormat.MEDIUM formatting technique
 java.lang.String PrintTimeFull(long Time)
          Returns a formatted time string using the java.text.DateFormat.FULL formatting technique
 java.lang.String PrintTimeLong(long Time)
          Returns a formatted time string using the java.text.DateFormat.LONG formatting technique
 java.lang.String PrintTimeShort(long Time)
          Returns a formatted time string using the java.text.DateFormat.SHORT formatting technique
 java.lang.String QueryServerMacAddress(java.lang.String Hostname)
          Gets the MAC address of the SageTV server at the specified hostname.
 int ReformatDeviceAtPathAsEXT3(java.lang.String DrivePath)
          Determines the device that is mounted at the specified path, and then repartitions it to have a single EXT3 partition and then formats that partition.
 void ReleaseUIRefreshLock()
          Releases the lock for this user interface system to allow other updates to occur.
 void ReloadNameserverCache()
          Reloads the name server cache.
 java.lang.Object RemoveElement(java.lang.Object Data, java.lang.Object Value)
          Removes the element at with the specified value from this data.
 java.lang.Object RemoveElementAtIndex(java.util.List Data, int Index)
          Removes the element at the specified index in this data; works java.util.List implementations (i.e.
 boolean RemoveWindowsRegistryValue(java.lang.String Root, java.lang.String Key, java.lang.String Name)
          Removes a value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)
 boolean RenameFilePath(java.io.File OriginalFilePath, java.io.File NewFilePath)
          Renames a file/directory
 boolean Restart()
          Restarts the local instance of SageTV.
 java.lang.Object Round(java.lang.Object Number)
          Rounds a floating point number to an integral value.
 boolean SaveImageToFile(sage.MetaImage MetaImage, java.io.File File, int Width, int Height)
          Saves a MetaImage object to a file using the specified image size.
 java.awt.image.BufferedImage ScaleBufferedImage(java.awt.image.BufferedImage JavaBufferedImage, int Width, int Height, boolean Alpha)
          Scales a java.awt.image.BufferedImage object using optimized techniques
 java.util.Map ScanWirelessAPs()
          Scans for wireless access points and returns the results as a map.
 boolean SendNetworkCommand(java.lang.String Hostname, int Port, java.lang.Object Command)
          Opens a TCP/IP socket connection to the specified hostname on the specified port and then sends the specified command.
 boolean ServerRestart()
          Restarts the server instance of SageTV.
 void SetCoreAnimationsEnabled(boolean Enabled)
          Sets whether or not animation support is enabled (either layered or Effect based animations; depending upon the STV configuration)
 java.lang.Object SetElement(java.lang.Object Data, int Index, java.lang.Object Value)
          Sets the element at the specified index in this data; works for arrays and java.util.List implementations (i.e.
 void SetScrollPosition(float RelativeX, float RelativeY)
          Scrolls the closest pageable UI parent component (or sibling of a parent) to the specified position.
 boolean SetWindowsRegistryDWORDValue(java.lang.String Root, java.lang.String Key, java.lang.String Name, int Value)
          Sets a DWORD value in the Windows registry for the specified root, key and name(Windows only) The name will be created if it doesn't already exist.
 boolean SetWindowsRegistryStringValue(java.lang.String Root, java.lang.String Key, java.lang.String Name, java.lang.String Value)
          Sets a string value in the Windows registry for the specified root, key and name(Windows only) The name will be created if it doesn't already exist.
 int Size(java.lang.Object Data)
          Returns the size of the specified data.
 boolean StringEndsWith(java.lang.String FullString, java.lang.String MatchString)
          Returns true if the first string ends with the second, uses java.lang.String.endsWith
 int StringIndexOf(java.lang.String FullString, java.lang.String MatchString)
          Returns the index of the second string within the first string, -1 if it is not found.
 java.lang.String StringIndexOfNTE(java.lang.String FullString, java.lang.String MatchStringNTE)
          Returns the index of MatchStringNTE string within FullString, -1 if it is not found.
Search is case-insentive
The MatchStringNTE may contain the Unicode characters u2460-u2468 and u24EA (Unicode Circled Digits) representing numeric Text Keys 1-9 and 0.
 int StringLastIndexOf(java.lang.String FullString, java.lang.String MatchString)
          Returns the last index of the second string within the first string, -1 if it is not found.
 boolean StringStartsWith(java.lang.String FullString, java.lang.String MatchString)
          Returns true if the first string starts with the second, uses java.lang.String.startsWith
 java.lang.Boolean StringStartsWithNTE(java.lang.String FullString, java.lang.String MatchStringNTE)
          Returns true if the Full String starts with characters matching MatchStringNTE
Search is case-insentive
The MatchStringNTE may contain the Unicode characters u2460-u2468 and u24EA (Unicode Circled Digits) representing numeric Text Keys 1-9 and 0.
 java.lang.String Substring(java.lang.String String, int StartIndex, int EndIndex)
          Returns the substring from a specified string.
 java.lang.String SubstringBegin(java.lang.String String, int EndOffset)
          Returns the substring from a specified string.
 int TestPlaceshifterConnectivity(java.lang.String LocatorID)
          Connects to the SageTV Locator server and submits the specified Locator ID for a 'ping'.
 long Time()
          Returns the current time; see java.lang.System.currentTimeMillis() for the explanation of the units.
 void UnloadImage(java.lang.String ResPath)
          Unloads the specified image resource from memory.
 void Wait(long Time)
          Causes the currently executing thread to sleep for the specified amount of time in milliseconds.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Utility

public Utility()
Method Detail

GetSubgroup

public java.lang.Object GetSubgroup(java.util.Map Grouping,
                                    java.lang.Object Key)
Gets the value for the specified key out of a map. Useful for analyzing data from a GroupByMethod () call.

Parameters:
Grouping - the map to get the value from
Key - the key to use for retrieving the value
Returns:
the value for the specified key in the specified map

Keystroke

public void Keystroke(java.lang.String Character,
                      boolean System)
Executes the specified keystroke in either the SageTV event system or by emulation in the operating system

Parameters:
Character - the keystroke to perform, can contain Ctrl, Shift, Alt and combinations thereof with the specified key name
System - if true then an operating system keystroke should be emulated, if false then keep the keystroke within SageTV

Size

public int Size(java.lang.Object Data)
Returns the size of the specified data.

Parameters:
Data - the object to get the data size of
Returns:
for a Collection or Map, the size of it; for an array, the length; for a string, the length, otherwise 0 is returned

IsEmpty

public boolean IsEmpty(java.lang.Object Data)
Returns true if the argument is null, zero, an empty string or a failed image load

Parameters:
Data - the object to test
Returns:
true if the argument is null, zero, an empty string or a failed image load
Since:
7.0

DateFormat

public java.lang.String DateFormat(java.lang.String Format,
                                   java.lang.Object Date)
Returns a formatted date string for the specified Date.

Parameters:
Format - null if SageTV's default date format should be used, otherwise use a formatting string as specified in java.text.SimpleDateFormat
Date - either a java.util.Date object or a long which corresponds to the date
Returns:
the date formatted string

NumberFormat

public java.lang.String NumberFormat(java.lang.String Format,
                                     float Number)
Returns a formatted numeric string for the specified number.

Parameters:
Format - a formatting string as specified in java.text.DecimalFormat
Number - the floating point number to format
Returns:
the formatted numeric string

DurFormat

public java.lang.String DurFormat(java.lang.String Format,
                                  long Duration)
Returns a formatted duration String for a period of time in milliseconds. The formatting string uses the % character for escapement (%% is not supported, you cannot display the % symbol in a duration string). The 'd', 'h', 'm' and 's' characters can be used to indicate days, hours, minutes and seconds respectively. Any format character may be prefixed by the 'r' character to indicate it is a required field.

For example, the format string %rh:%m for 20 minutes would return 0:20 and for the string $h:%m it would return 20 If there's characters before a field value then that value will be zero padded, i.e. 65 minutes for %h:%m would be 1:05

Parameters:
Format - the duration format string, or null to use SageTV's default duration formatting
Duration - the duration to print out in milliseconds
Returns:
the formatted duration string

CreateTimeSpan

public java.lang.Long[] CreateTimeSpan(long StartTime,
                                       long EndTime)
Returns a length 2 Long object array which can be used for specifying a time span in a table. The first element will be the StartTime and the second will be the EndTime

Parameters:
StartTime - the long value which specifies the start value of the time span
EndTime - the long value which specifies the end value of the time span
Returns:
an array which represents this time span

GetElement

public java.lang.Object GetElement(java.lang.Object Data,
                                   int Index)
Returns the element at the specified index in this data; works for arrays and java.util.List implementations (i.e. Vector, etc.)

Parameters:
Data - the java.util.List or array object to get the element from
Index - the 0-based index of the element to retrieve
Returns:
the element at the specified index or null if there is no such element

SetElement

public java.lang.Object SetElement(java.lang.Object Data,
                                   int Index,
                                   java.lang.Object Value)
Sets the element at the specified index in this data; works for arrays and java.util.List implementations (i.e. Vector, etc.)

Parameters:
Data - the java.util.List or array object to set the element for
Index - the 0-based index of the element to set
Value - the value to set
Returns:
the Value parameters is returned

RemoveElementAtIndex

public java.lang.Object RemoveElementAtIndex(java.util.List Data,
                                             int Index)
Removes the element at the specified index in this data; works java.util.List implementations (i.e. Vector, etc.)

Parameters:
Data - the java.util.List object to remove the element from
Index - the 0-based index of the element to remove
Returns:
the element at the specified index or null if there is no such element

RemoveElement

public java.lang.Object RemoveElement(java.lang.Object Data,
                                      java.lang.Object Value)
Removes the element at with the specified value from this data. Works for java.util.Collection or java.util.Map implementations. If the value appears multiple times in the data (for Collections) only the first occurrence is removed.

Parameters:
Data - the java.util.Collection or java.util.Map object to remove the element from; for maps it removes based on key
Value - the value to remove from the data
Returns:
for java.util.Collections true if the element exists and was removed, false otherwise; for java.util.Maps it returns the value that the specified key corresponded to

AddElement

public boolean AddElement(java.util.Collection Data,
                          java.lang.Object Value)
Add the element with the specified value to this data. Works for java.util.Collection implementations.

Parameters:
Data - the java.util.Collection object to add the element to
Value - the value to add to the data
Returns:
for java.util.Collections true if the data changed as a result of the call (i.e. the add succeded and was not redundant), false otherwise
Since:
7.0

FindElementIndex

public int FindElementIndex(java.lang.Object Data,
                            java.lang.Object Element)
Returns the index in the data that the specified element is found at. If there are multiple occurrences of this element only the first index is returned. This works for arrays and java.util.List implementations.

Parameters:
Data - the java.util.List or array to look in
Element - the value to search the data for
Returns:
the 0-based index of the specified element in the data, or -1 if it does not exist

FindComparativeElement

public java.lang.Object FindComparativeElement(java.lang.Object Data,
                                               java.lang.Comparable Criteria,
                                               java.lang.String Method)
Searches a sorted list of data to find the index that the specified criteria exists at; or if it doesn't exist in the data it will use the index that would be the appropriate insertion point for the criteria in the data in order to maintain sort order. The element at that index is what is returned

Parameters:
Data - the data to sort, this must be a java.util.Collection, a java.util.Map, or an array
Criteria - the object to compare the elements to; this must implement java.lang.Comparable
Method - the method name to execute on each element to get the value to compare; use null to compare the elements themselves
Returns:
the element at the comparative insertion point

Substring

public java.lang.String Substring(java.lang.String String,
                                  int StartIndex,
                                  int EndIndex)
Returns the substring from a specified string. Same as java.lang.String.substring(int startIndex, int endIndex)

Parameters:
String - the string to get the substring of
StartIndex - the 0-based index that the substring starts at
EndIndex - the 0-based index that the substring ends at or -1 if the substring goes to the end of the string
Returns:
the substring from the specified string

SubstringBegin

public java.lang.String SubstringBegin(java.lang.String String,
                                       int EndOffset)
Returns the substring from a specified string. The substring will start at the beginning of the string and end EndIndex characters before the end of the string. Same as Substring(String, 0, Size(String) - EndOffset).

Parameters:
String - the string to get the substring of
EndOffset - the number of characters from the end of the string to terminate the substring (0 implies return the entire string)
Returns:
the substring from the specified string
Since:
7.0

Round

public java.lang.Object Round(java.lang.Object Number)
Rounds a floating point number to an integral value. For Doubles a Long is returned, for Floats an Integer is returned

Parameters:
Number - the number to round
Returns:
the rounded value

Time

public long Time()
Returns the current time; see java.lang.System.currentTimeMillis() for the explanation of the units.

Returns:
the current time

PrintCurrentTime

public java.lang.String PrintCurrentTime()
Returns a string that represents the current time.

Returns:
a string that represents the current time.

PrintDate

public java.lang.String PrintDate(long Date)
Returns a formatted date string using the java.text.DateFormat.MEDIUM formatting technique

Parameters:
Date - the date value to format
Returns:
a formatted date string

PrintDateLong

public java.lang.String PrintDateLong(long Date)
Returns a formatted date string using SageTV's default detailed date formatting

Parameters:
Date - the date value to format
Returns:
a formatted date string

PrintDateShort

public java.lang.String PrintDateShort(long Date)
Returns a formatted date string using the java.text.DateFormat.SHORT formatting technique

Parameters:
Date - the date value to format
Returns:
a formatted date string

PrintDateFull

public java.lang.String PrintDateFull(long Date)
Returns a formatted date string using the java.text.DateFormat.FULL formatting technique

Parameters:
Date - the date value to format
Returns:
a formatted date string

PrintTime

public java.lang.String PrintTime(long Time)
Returns a formatted time string using the java.text.DateFormat.MEDIUM formatting technique

Parameters:
Time - the time value to format
Returns:
a formatted time string

PrintTimeLong

public java.lang.String PrintTimeLong(long Time)
Returns a formatted time string using the java.text.DateFormat.LONG formatting technique

Parameters:
Time - the time value to format
Returns:
a formatted time string

PrintTimeShort

public java.lang.String PrintTimeShort(long Time)
Returns a formatted time string using the java.text.DateFormat.SHORT formatting technique

Parameters:
Time - the time value to format
Returns:
a formatted time string

PrintTimeFull

public java.lang.String PrintTimeFull(long Time)
Returns a formatted time string using the java.text.DateFormat.FULL formatting technique

Parameters:
Time - the time value to format
Returns:
a formatted time string

PrintDuration

public java.lang.String PrintDuration(long Duration)
Returns a formatted duration string according to SageTV's verbose duration formating, minutes is the most detailed resolution of this format

Parameters:
Duration - the duration in milliseconds to print
Returns:
the formatted duration string

PrintDurationWithSeconds

public java.lang.String PrintDurationWithSeconds(long Duration)
Returns a formatted duration string according to SageTV's default duration formating, seconds is the most detailed resolution of this format

Parameters:
Duration - the duration in milliseconds to print
Returns:
the formatted duration string

PrintDurationShort

public java.lang.String PrintDurationShort(long Duration)
Returns a formatted duration string according to SageTV's concise duration formating, minutes is the most detailed resolution of this format

Parameters:
Duration - the duration in milliseconds to print
Returns:
the formatted duration string

GetDiskFreeSpace

public long GetDiskFreeSpace(java.lang.String DrivePath)
Returns the amount of disk free space in bytes at the specified path

Parameters:
DrivePath - the path string of a disk to get the free space of
Returns:
the free space on the specified disk in bytes

GetDiskTotalSpace

public long GetDiskTotalSpace(java.lang.String DrivePath)
Returns the amount of total disk space in bytes at the specified path

Parameters:
DrivePath - the path string of a disk to get the total space of
Returns:
the total space on the specified disk in bytes

GetFileSystemType

public java.lang.String GetFileSystemType(java.lang.String DrivePath)
Gets the name of the filesystem type at the specified path

Parameters:
DrivePath - the path string of a disk to get the filesystem type for
Returns:
the name of the filesystem type at the specified path

GetWindowsRegistryNames

public java.lang.String[] GetWindowsRegistryNames(java.lang.String Root,
                                                  java.lang.String Key)
Returns a list of the Windows registry names which exist under the specified root & key (Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:
Root - the registry hive to look in
Key - the key path in the registry hive
Returns:
the names stored in the registry under the specified key

GetWindowsRegistryDWORDValue

public int GetWindowsRegistryDWORDValue(java.lang.String Root,
                                        java.lang.String Key,
                                        java.lang.String Name)
Returns a DWORD value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:
Root - the registry hive to look in
Key - the key path in the registry hive
Name - the name of the registry value to retrieve
Returns:
the value of the specified registry setting as a DWORD

GetWindowsRegistryStringValue

public int GetWindowsRegistryStringValue(java.lang.String Root,
                                         java.lang.String Key,
                                         java.lang.String Name)
Returns a string value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:
Root - the registry hive to look in
Key - the key path in the registry hive
Name - the name of the registry value to retrieve
Returns:
the value of the specified registry setting as a string

RemoveWindowsRegistryValue

public boolean RemoveWindowsRegistryValue(java.lang.String Root,
                                          java.lang.String Key,
                                          java.lang.String Name)
Removes a value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:
Root - the registry hive to look in
Key - the key path in the registry hive
Name - the name of the registry value to remove
Returns:
true if the specified setting was removed, false otherwise

SetWindowsRegistryDWORDValue

public boolean SetWindowsRegistryDWORDValue(java.lang.String Root,
                                            java.lang.String Key,
                                            java.lang.String Name,
                                            int Value)
Sets a DWORD value in the Windows registry for the specified root, key and name(Windows only) The name will be created if it doesn't already exist. Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:
Root - the registry hive to use
Key - the key path in the registry hive
Name - the name of the registry value to set
Value - the value of the specified registry setting as a DWORD
Returns:
true if the operation was successful, false otherwise

SetWindowsRegistryStringValue

public boolean SetWindowsRegistryStringValue(java.lang.String Root,
                                             java.lang.String Key,
                                             java.lang.String Name,
                                             java.lang.String Value)
Sets a string value in the Windows registry for the specified root, key and name(Windows only) The name will be created if it doesn't already exist. Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:
Root - the registry hive to use
Key - the key path in the registry hive
Name - the name of the registry value to set
Value - the value of the specified registry setting as a string
Returns:
true if the operation was successful, false otherwise

PlaySound

public void PlaySound(java.lang.String SoundFile)
Plays the specified sound file (used for sound effects, don't use for music playback)

Parameters:
SoundFile - the path of the sound resource to play back

If

public java.lang.Object If(boolean Condition,
                           java.lang.Object True,
                           java.lang.Object False)
Returns the second argument if the first argument is true, otherwise the third argument is returned. All 3 arguments will be evaluated in all cases. This does NOT have a short-circuit which prevents evaluation of the third argument if the first is true.

Parameters:
Condition - the value to test to see if it is true
True - the value to return if the Condition is true
False - the value to return if the Condition is not true
Returns:
the appropriate value based on the condition

GetFileNameFromPath

public java.lang.String GetFileNameFromPath(java.io.File FilePath)
Returns the file name from the specified file path; this just returns the filename without any path information.

Parameters:
FilePath - the filepath to get the filename for
Returns:
the filename from the specified file path

GetAbsoluteFilePath

public java.lang.String GetAbsoluteFilePath(java.io.File FilePath)
Returns the full path name from the specified file path..

Parameters:
FilePath - the filepath to get the full path from
Returns:
the full path from the specified file path
Since:
7.0

GetFileExtensionFromPath

public java.lang.String GetFileExtensionFromPath(java.lang.String FilePath)
Returns the file name extension from the specified file path (not including the '.')

Parameters:
FilePath - the file path to get the extension of
Returns:
the extension from the specified file path
Since:
6.4

Wait

public void Wait(long Time)
Causes the currently executing thread to sleep for the specified amount of time in milliseconds.

Parameters:
Time - the amount of time to sleep this thread for in milliseconds

Max

public java.lang.Number Max(java.lang.Number Value1,
                            java.lang.Number Value2)
Returns the maximum of the two arguments; the type of the returned argument will be the same as the highest precision argument

Parameters:
Value1 - one of the values
Value2 - the other value
Returns:
the maximum of the passed in values

Min

public java.lang.Number Min(java.lang.Number Value1,
                            java.lang.Number Value2)
Returns the minimum of the two arguments; the type of the returned argument will be the same as the highest precision argument

Parameters:
Value1 - one of the values
Value2 - the other value
Returns:
the minimum of the passed in values

ExecuteProcess

public java.lang.Process ExecuteProcess(java.lang.String CommandString,
                                        java.lang.Object Arguments,
                                        java.io.File WorkingDirectory,
                                        boolean ConsoleApp)
Executes a new process on the system

Parameters:
CommandString - the command to execute (i.e. C:\windows\notepad.exe or ifconfig)
Arguments - the arguments to pass to the command that is executed, if it's a java.util.Collection or array then each element is an argument, otherwise it is considered a single argument; use null for no arguments
WorkingDirectory - the directory to execute the process from or null to execute it from the current working directory
ConsoleApp - if true then SageTV will consume the stdout and stderr output from the process that is launched; if false it will not
Returns:
the java.lang.Process object that represents the launched process

ExecuteProcessReturnOutput

public java.lang.String ExecuteProcessReturnOutput(java.lang.String CommandString,
                                                   java.lang.Object Arguments,
                                                   java.io.File WorkingDirectory,
                                                   boolean ReturnStdout,
                                                   boolean ReturnStderr)
Executes a new process on the system and returns as a String the output of the process

Parameters:
CommandString - the command to execute (i.e. C:\windows\notepad.exe or ifconfig)
Arguments - the arguments to pass to the command that is executed, if it's a java.util.Collection or array then each element is an argument, otherwise it is considered a single argument; use null for no arguments
WorkingDirectory - the directory to execute the process from or null to execute it from the current working directory
ReturnStdout - if true then SageTV will return the data from stdout as part of the return value
ReturnStderr - if true then SageTV will return the data from stderr as part of the return value
Returns:
a String which contains the data from stdout/stderr (depending upon the arguments), null if there was a failure
Since:
6.0

LoadImageFile

public sage.MetaImage LoadImageFile(java.io.File FilePath)
Returns a MetaImage object that refers to the specified image file. Used for passing images into Widgets.

Parameters:
FilePath - the file path of the image to load
Returns:
the loaded image object

LoadImage

public sage.MetaImage LoadImage(java.lang.Object Resource)
Returns a MetaImage object that refers to a specified image resource. This can be used to load images from URLs, JAR resources or the file system.

It also has a secondary purpose where you can pass it a MetaImage and then it will load that image into the current image cache so it will render as fast as possible in the next drawing cycle. Good for preloading the next image in a slideshow. If a MetaImage is passed in; this call will not return until that image is loaded into the cache.

Parameters:
Resource - if this is a MetaImage then the image is loaded into the cache, otherwise its converted to a string and then a MetaImage is returned for that resource
Returns:
the MetaImage that refers to the passed specified resource, if a MetaImage was passed in then the same object is returned

SaveImageToFile

public boolean SaveImageToFile(sage.MetaImage MetaImage,
                               java.io.File File,
                               int Width,
                               int Height)
Saves a MetaImage object to a file using the specified image size. The supported formats are JPG and PNG. The format is determined by the file extension, which must be either .jpg or .png. Use zero for the width and height to save it at the original image size. NOTE: This call is a NOOP on embedded platforms

Parameters:
MetaImage - the MetaImage object that should be saved to the specified file
File - the file to save the image to
Width - the width to use in the saved image file
Height - the height to use in the saved image file
Returns:
returns true on success or false on failure
Since:
7.1

GetMetaImageSourceFile

public java.io.File GetMetaImageSourceFile(sage.MetaImage MetaImage)
Returns the file path that a MetaImage was loaded from. Since not all MetaImage objects come from file paths, this will return null for any non-file based images.

Parameters:
MetaImage - the MetaImage to get the file path for
Returns:
the file path for the specified MetaImage, or null if it wasn't loaded from a file path
Since:
7.1

GetMetaImageAspectRatio

public float GetMetaImageAspectRatio(sage.MetaImage MetaImage)
Returns the aspect ratio of an image as a floating point number of width/height, zero if the image was a failed load or has not been loaded yet

Parameters:
MetaImage - the MetaImage to get the aspec for
Returns:
the aspect ratio of the image as a floating point number of width/height, zero if the image was a failed load or has not been loaded yet
Since:
8.0

IsMetaImage

public boolean IsMetaImage(java.lang.Object MetaImage)
Returns true if the argument is a MetaImage object.

Parameters:
MetaImage - the Object to test
Returns:
true if the argument is a MetaImage object, false otherwise
Since:
7.1

GetMetaImageBytes

public byte[] GetMetaImageBytes(sage.MetaImage MetaImage)
Returns a byte array which is the contents of the MetaImage source's data (i.e. compressed image data)

Parameters:
MetaImage - the MetaImage to get the compressed byte data for
Returns:
a byte array which is the contents of the MetaImage source's data (i.e. compressed image data), null if it cannot load the data or the argument is not a MetaImage
Since:
8.1

GetImageAsBufferedImage

public java.awt.image.BufferedImage GetImageAsBufferedImage(java.lang.Object Resource)
Returns a java.awt.image.BufferedImage object. This can be used to load images from URLs, JAR resources or the file system.

Parameters:
Resource - if this is a MetaImage then the buffered image is taken from that, otherwise its converted to a string and then the image is loaded from that path
Returns:
a newly allocated java.awt.image.BufferedImage corresponding to the specified resource
Since:
4.1

GetScaledImageAsBufferedImage

public java.awt.image.BufferedImage GetScaledImageAsBufferedImage(java.lang.Object Resource,
                                                                  int Width,
                                                                  int Height)
Returns a java.awt.image.BufferedImage object. This can be used to load images from URLs, JAR resources or the file system. The size of the returned image will match the passed in arguments.

Parameters:
Resource - if this is a MetaImage then the buffered image is taken from that, otherwise its converted to a string and then the image is loaded from that path
Width - the desired width of the returned image
Height - the desired height of the returned image
Returns:
a newly allocated java.awt.image.BufferedImage corresponding to the specified resource
Since:
4.1

UnloadImage

public void UnloadImage(java.lang.String ResPath)
Unloads the specified image resource from memory. NOTE: This does not care about the internal reference count in SageTV for this image which could mean bad things will happen if you use this on images other than ones that you are explicitly managing.

Parameters:
ResPath - the path to the image resource, can be a url, JAR resource path or a file path

IsImageLoaded

public boolean IsImageLoaded(java.lang.Object Image)
Checks whether the passed in MetaImage (from an API call that returns MetaImage), MediaFile, File, URL or Album is loaded into system memory or into the VRAM cache of the corresponding UI making the call.

Parameters:
Image - the MetaImage to check, or a MediaFile or an Album or a java.io.File or a java.net.URL
Returns:
true if the MetaImage (or the MetaImage that would correspond to the passed in resource) is loaded into system memory or the calling UI's VRAM, false otherwise
Since:
6.1

DidImageLoadFail

public boolean DidImageLoadFail(java.lang.Object Image)
Checks whether the passed in MetaImage (from an API call that returns MetaImage), MediaFile, File, URL or Album failed to load successfully. This will return false if the image load has not been attempted yet.

Parameters:
Image - the MetaImage to check, or a MediaFile or an Album or a java.io.File or a java.net.URL
Returns:
true if the MetaImage (or the MetaImage that would correspond to the passed in resource) has already tried to load; and the load failed
Since:
7.0

DirectoryListing

public java.io.File[] DirectoryListing(java.io.File DirectoryPath)
Returns a list of the files in the specified directory

Parameters:
DirectoryPath - the directory to list the files in
Returns:
a list of files in the specified directory

DirectoryListing

public java.io.File[] DirectoryListing(java.io.File DirectoryPath,
                                       java.lang.String MediaMask)
Returns a list of the files in the specified directory. Only directories and file matching the media mask will be returned.

Parameters:
DirectoryPath - the directory to list the files in
MediaMask - the types of content allowed, any combination of 'M'=Music, 'P'=Pictures or 'V'=Videos
Returns:
a list of folders and matching files in the specified directory
Since:
7.0

LocalDirectoryListing

public java.io.File[] LocalDirectoryListing(java.io.File DirectoryPath)
Returns a list of the files in the specified directory on the local filesystem

Parameters:
DirectoryPath - the directory to list the files in
Returns:
a list of files in the specified directory
Since:
6.4

GetFileSystemRoots

public java.io.File[] GetFileSystemRoots()
Returns the root directories of the file systems (on Linux this'll just be / and on Windows it'll be the drive letters)

Returns:
the root directories of the file systems

GetLocalFileSystemRoots

public java.io.File[] GetLocalFileSystemRoots()
Returns the root directories of the local file systems (on Linux this'll just be / and on Windows it'll be the drive letters)

Returns:
the root directories of the local file systems
Since:
6.4

StringEndsWith

public boolean StringEndsWith(java.lang.String FullString,
                              java.lang.String MatchString)
Returns true if the first string ends with the second, uses java.lang.String.endsWith

Parameters:
FullString - the string to search in
MatchString - the string to search for
Returns:
true if FullString ends with MatchString, false otherwise

StringStartsWith

public boolean StringStartsWith(java.lang.String FullString,
                                java.lang.String MatchString)
Returns true if the first string starts with the second, uses java.lang.String.startsWith

Parameters:
FullString - the string to search in
MatchString - the string to search for
Returns:
true if FullString starts with MatchString, false otherwise

StringIndexOf

public int StringIndexOf(java.lang.String FullString,
                         java.lang.String MatchString)
Returns the index of the second string within the first string, -1 if it is not found. Uses java.lang.String.indexOf

Parameters:
FullString - the string to search in
MatchString - the string to search for
Returns:
the first 0-based index in FullString that MatchString occurs at or -1 if it is not found

StringLastIndexOf

public int StringLastIndexOf(java.lang.String FullString,
                             java.lang.String MatchString)
Returns the last index of the second string within the first string, -1 if it is not found. Uses java.lang.String.lastIndexOf

Parameters:
FullString - the string to search in
MatchString - the string to search for
Returns:
the last 0-based index in FullString that MatchString occurs at or -1 if it is not found

GetWorkingDirectory

public java.lang.String GetWorkingDirectory()
Returns the current working directory for the application (if this is a client; it'll be the working directory of the server)

Returns:
the current working directory for the application

HasLocalFilesystem

public boolean HasLocalFilesystem()
Returns true if this client has a local file system that can be accessed.

Returns:
true if this client has a local file system that can be accessed
Since:
6.4

CreateFilePath

public java.io.File CreateFilePath(java.lang.String Directory,
                                   java.lang.String File)
Creates a new file object for the specified directory and file name or relative path

Parameters:
Directory - the directory name
File - the file within the directory or relative file path
Returns:
a new file object for the specified directory and file name or relative path

IsFilePathHidden

public boolean IsFilePathHidden(java.lang.String FilePath)
Returns true if the specified file path is marked as a hidden file

Parameters:
FilePath - the file path to test
Returns:
true if the specified file path is marked as a hidden file

IsLocalFilePathHidden

public boolean IsLocalFilePathHidden(java.lang.String FilePath)
Returns true if the specified local file path is marked as a hidden file

Parameters:
FilePath - the file path to test
Returns:
true if the specified local file path is marked as a hidden file
Since:
6.4

IsFilePath

public boolean IsFilePath(java.lang.String FilePath)
Returns true if the specified file path denotes a file that exists and is not a directory

Parameters:
FilePath - the file path to test
Returns:
true if the specified file path denotes a file that exists and is not a directory

IsLocalFilePath

public boolean IsLocalFilePath(java.lang.String FilePath)
Returns true if the specified local file path denotes a file that exists and is not a directory

Parameters:
FilePath - the file path to test
Returns:
true if the specified local file path denotes a file that exists and is not a directory
Since:
6.4

IsDirectoryPath

public boolean IsDirectoryPath(java.lang.String FilePath)
Returns true if the specified path denotes a directory that exists

Parameters:
FilePath - the file path to test
Returns:
true if the specified path denotes a directory that exists

IsLocalDirectoryPath

public boolean IsLocalDirectoryPath(java.lang.String FilePath)
Returns true if the specified local path denotes a directory that exists

Parameters:
FilePath - the file path to test
Returns:
true if the specified local path denotes a directory that exists
Since:
6.4

CreateNewDirectory

public boolean CreateNewDirectory(java.io.File DirectoryPath)
Creates a new directory and any parent directories for the specified directory path.

Parameters:
DirectoryPath - the directory to create
Returns:
true if successful, false otherwise

CreateNewLocalDirectory

public boolean CreateNewLocalDirectory(java.io.File DirectoryPath)
Creates a new local directory and any parent directories for the specified directory path.

Parameters:
DirectoryPath - the directory to create
Returns:
true if successful, false otherwise
Since:
6.4

GetPathParentDirectory

public java.io.File GetPathParentDirectory(java.io.File FilePath)
Returns the parent directory for the specified file path

Parameters:
FilePath - the file path to get the parent directory for
Returns:
the parent directory for the specified file path

GetPathLastModifiedTime

public long GetPathLastModifiedTime(java.io.File FilePath)
Returns the last modified time of the specified file path

Parameters:
FilePath - the file path
Returns:
the last modified time of the specified file path

GetLocalPathLastModifiedTime

public long GetLocalPathLastModifiedTime(java.io.File FilePath)
Returns the last modified time of the specified local file path

Parameters:
FilePath - the file path
Returns:
the last modified time of the specified local file path
Since:
6.4

GetFilePathSize

public long GetFilePathSize(java.io.File FilePath)
Returns the size in bytes of the specified file path

Parameters:
FilePath - the file path
Returns:
the size in bytes of the specified file path
Since:
6.4

GetLocalFilePathSize

public long GetLocalFilePathSize(java.io.File FilePath)
Returns the size in bytes of the specified local file path

Parameters:
FilePath - the file path
Returns:
the size in bytes of the specified local file path
Since:
6.4

DeleteFilePath

public boolean DeleteFilePath(java.io.File FilePath)
Deletes the file/directory at the corresponding file path (directories must be empty first)

Parameters:
FilePath - the file path
Returns:
true if successful, false otherwise
Since:
6.3.9

DeleteLocalFilePath

public boolean DeleteLocalFilePath(java.io.File FilePath)
Deletes the file/directory at the corresponding local file path (directories must be empty first)

Parameters:
FilePath - the file path
Returns:
true if successful, false otherwise
Since:
6.4

RenameFilePath

public boolean RenameFilePath(java.io.File OriginalFilePath,
                              java.io.File NewFilePath)
Renames a file/directory

Parameters:
OriginalFilePath - the file path to rename
NewFilePath - the new name for the file path
Returns:
true if successful, false otherwise
Since:
6.3.9

AddToGrouping

public boolean AddToGrouping(java.util.Map Grouping,
                             java.lang.Object Key,
                             java.lang.Object Value)
Adds the specified value into the grouping using the specified key. Useful on results from GroupByMethod() This works using a Map implementation that has Collections as the values and objects as the keys. So if two objects have the same key they will both still exist in the map by being in the Collection that corresponds to their key.

Parameters:
Grouping - the grouping (Map) to add the new key/value pair to
Key - the key to use to store the value in the map
Value - the value to store
Returns:
true is always returned

SendNetworkCommand

public boolean SendNetworkCommand(java.lang.String Hostname,
                                  int Port,
                                  java.lang.Object Command)
Opens a TCP/IP socket connection to the specified hostname on the specified port and then sends the specified command. After that the socket is closed.

Parameters:
Hostname - the hostname to connect to
Port - the port to connect on
Command - either a byte[] or a String to send across the socket
Returns:
true if successful, false otherwise

ScaleBufferedImage

public java.awt.image.BufferedImage ScaleBufferedImage(java.awt.image.BufferedImage JavaBufferedImage,
                                                       int Width,
                                                       int Height,
                                                       boolean Alpha)
Scales a java.awt.image.BufferedImage object using optimized techniques

Parameters:
JavaBufferedImage - the BufferedImage object that is the source for the scaling
Width - the width of the target image
Height - the height of the target image
Alpha - true if the scaling should be done in ARGB, false if it should be done in RGB
Returns:
a new BufferedImage that is a scaled version of the specified image

LocalizeString

public java.lang.String LocalizeString(java.lang.String EnglishText)
Returns a localized version of the specified string. Uses SageTV's core translation properties to do this.

Parameters:
EnglishText - the English string to translate from
Returns:
the translated version of the specified string in the currently configured language

GetLocalIPAddress

public java.lang.String GetLocalIPAddress()
Returns the IP address of the machine

Returns:
the IP address of the machine

IsImportableFileType

public boolean IsImportableFileType(java.lang.String Filename)
Returns true if the specified file path has a file extension which would be imported by SageTV into its library.

Parameters:
Filename - the file path to test
Returns:
true if the specified file path has a file extension which would be imported by SageTV into its library, false otherwise

GetSubnetMask

public java.lang.String GetSubnetMask()
Returns the subnet mask for the currently configured network adapter. NOTE: This is only valid on embedded platforms.

Returns:
the subnet mask for the currently configured network adapter

GetGatewayAddress

public java.lang.String GetGatewayAddress()
Returns the gateway address for the currently configured network adapter. NOTE: This is only valid on embedded platforms.

Returns:
the gateway address for the currently configured network adapter

GetDNSAddress

public java.lang.String GetDNSAddress()
Returns the DNS address for the currently configured network adapter. NOTE: This is only valid on embedded platforms.

Returns:
the DNS address for the currently configured network adapter

GuessMajorFileType

public java.lang.String GuessMajorFileType(java.lang.String Filename)
Guesses what media type the specified filename corresponds to. It does this based on the configuration for the import library file types.

Parameters:
Filename - the file path to test
Returns:
"M", "V", "P", "B" or "D" for a music, video, picture, BluRay or DVD file respectively; if it can't tell it returns "V"
Since:
6.4

TestPlaceshifterConnectivity

public int TestPlaceshifterConnectivity(java.lang.String LocatorID)
Connects to the SageTV Locator server and submits the specified Locator ID for a 'ping'. The Locator server will then attempt to connect to the IP for that GUID and report back the status. The return code is an integer as follows: -1 - Unable to connect to the locator server (internet connection is down or locator server is down) 0 - The locator server did not have an IP address registered for this GUID 1 - The locator server could not connect to the IP address registered for the GUID 2 - The locator server can connect to the IP address registered for the GUID, but not to the Placeshifter port 3 - The locator server can connect to the IP address/port for the GUID, but the server that is there is not the Placeshifter 10 - The ping was successful. External connections to the Placeshifter should work correctly.

Parameters:
LocatorID - the GUID that should be used for the 'ping'
Returns:
an integer status code as described above.

LookupIPForLocatorID

public java.lang.String LookupIPForLocatorID(java.lang.String LocatorID)
Connects to the SageTV Locator server and submits the specified Locator ID for a IP lookup. The Locator server will then lookup the IP for that GUID and report it back.

Parameters:
LocatorID - the GUID that should be used for the lookup
Returns:
an String of IP address:port or null if the lookup failed

CreateArray

public java.lang.Object[] CreateArray(java.lang.Object Value)
Creates a java.lang.Object array and initializes each element to the passed in argument. NOTE: This method takes a variable number of arguments, and the length of the returned array will be equal to the number of arguments. i.e. calling CreateArray(1, 2) returns an Object array with elements 1 and 2 in it

Parameters:
Value - a value for an element of the array (multiple arguments allowed)
Returns:
the newly allocated Object array with its elements set to the arguments
Since:
6.0

SetScrollPosition

public void SetScrollPosition(float RelativeX,
                              float RelativeY)
Scrolls the closest pageable UI parent component (or sibling of a parent) to the specified position.

Parameters:
RelativeX - the X position to scroll to between 0.0 and 1.0 (use a negative number to not change the X position)
RelativeY - the Y position to scroll to between 0.0 and 1.0 (use a negative number to not change the Y position)
Since:
6.2

ClearMenuCache

public void ClearMenuCache()
Clears the cache that links Widgets to the in memory-menu representations for this UI. This also clears the back/forward history to remove any references contained in there as well.

Since:
6.2

Animate

public boolean Animate(java.lang.String WidgetName,
                       java.lang.String LayerName,
                       java.lang.String AnimationName,
                       long Duration)
Starts an animation for the specified Widget in the specified Layer. If the Widget name ends with a '*' then all Widgets that match will be animated; otherwise only the first visible Widget matching the name will be animated. The Widget must also have the specified Layer as it's animation layer (i.e. if the Layer is Foreground, then the corresponding Widget should have an Animation property of LayerForeground). The type of animation is controlled by AnimtionName. There's also suffixes that can be appened to the AnimationName that effect how the timescale for the animation progresses. There's also other suffixes that can be used to specify other options for the animations.

Valid strings for the AnimationName are:

Timeline modifications for animations affect how the timescale progresses. For out animations, they are eased out if non-linear. For in animations, they are eased in if non-linear. For animations that are neither; the timescale modification occurs at both ends. Bounce only works properly for 'in' animations.

Valid suffixes for any of the animations are (default is Quadratic):

Additional options for the animation may also be specified by combining additional suffixes to the AnimationName. The following is a list of valid option suffixes.

You may combine the directional suffixes to get an additional four directions (i.e. ZoomOutNorthEast). And this can also be combined with the timeline suffixes as well, or even Fade (i.e. ZoomInQuadraticSouthWestFade)
For delaying the start of an animation; see here AnimateDelayed()

Parameters:
WidgetName - the name of the Widget that should be animated
LayerName - the name of the Layer the animated Widget must be in
AnimationName - the name of the animation to perform
Duration - the time in milliseconds that it should take for the animation to complete
Returns:
returns true if a matching Widget was found to perform the animation on; false otherwise
Since:
6.2

AnimateVariable

public boolean AnimateVariable(java.lang.String WidgetName,
                               java.lang.String LayerName,
                               java.lang.String VarName,
                               java.lang.Object VarValue,
                               java.lang.String AnimationName,
                               long Duration,
                               long StartDelay,
                               boolean Interruptable)
For more details on Animations see here: Animate() In addition to what's specified in the Animate API call; this also offers restricting of an Animation by a variable name and value. Usage of the '*' suffix on the WidgetName is allowed.

Parameters:
WidgetName - the name of the Widget that should be animated
LayerName - the name of the Layer the animated Widget must be in
VarName - the name of the variable that must match for the Widget to be animated
VarValue - the value of the variable to match
AnimationName - the name of the animation to perform
Duration - the time in milliseconds that it should take for the animation to complete
StartDelay - the delay in milliseconds before this animation should start
Interruptable - true if the animation can be interrupted to render the next UI update; false if it must complete (this parameter is optional and defaults to false)
Returns:
returns true if a matching Widget was found to perform the animation on; false otherwise
Since:
6.3

AnimateTransition

public boolean AnimateTransition(java.lang.String SourceWidgetName,
                                 java.lang.String TargetWidgetName,
                                 java.lang.String LayerName,
                                 java.lang.String AnimationName,
                                 long Duration,
                                 long StartDelay,
                                 boolean Interruptable)
Performs an Animation between two different Widgets. Normally animations are performed between two different states for a single Widget. This API call allows an animation to occur between two different Widgets and will usually be used with a 'Morph' AnimationName. This may only target a single Widget; so the '*' suffix is not used on the WidgetNames in this call.
For more details on Animations see here: Animate()

Parameters:
SourceWidgetName - the name of the Widget to use as the source for this animation
TargetWidgetName - the name of the Widget to use as the target (destination) for this animation
LayerName - the name of the Layer the animated Widget must be in
AnimationName - the name of the animation to perform
Duration - the time in milliseconds that it should take for the animation to complete
StartDelay - the delay in milliseconds before this animation should start
Interruptable - true if the animation can be interrupted to render the next UI update; false if it must complete (this parameter is optional and defaults to false)
Returns:
returns true if a matching Widget was found to perform the animation on; false otherwise
Since:
6.3

AnimateDelayed

public boolean AnimateDelayed(java.lang.String WidgetName,
                              java.lang.String LayerName,
                              java.lang.String AnimationName,
                              long Duration,
                              long StartDelay,
                              boolean Interruptable)
This is the same as the Animate API call; but it allows specifiying a delay that should occur before the animation actually starts. Useful for creating sequences of animation effects. For more details see here: Animate()

Parameters:
WidgetName - the name of the Widget that should be animated
LayerName - the name of the Layer the animated Widget must be in
AnimationName - the name of the animation to perform
Duration - the time in milliseconds that it should take for the animation to complete
StartDelay - the delay in milliseconds before this animation should start
Interruptable - true if the animation can be interrupted to render the next UI update; false if it must complete (this parameter is optional and defaults to false)
Returns:
returns true if a matching Widget was found to perform the animation on; false otherwise
Since:
6.2

SetCoreAnimationsEnabled

public void SetCoreAnimationsEnabled(boolean Enabled)
Sets whether or not animation support is enabled (either layered or Effect based animations; depending upon the STV configuration)

Parameters:
Enabled - true to enable core animations; false otherwise
Since:
6.2

AreCoreAnimationsEnabled

public boolean AreCoreAnimationsEnabled()
Returns whether or not animation support is enabled (either layered or Effect based animations; depending upon the STV configuration)

Returns:
true if core animations are enabled; false otherwise
Since:
6.2

AreCoreAnimationsSupported

public boolean AreCoreAnimationsSupported()
Returns whether or not animation support is possible in the current UI environment. Certain clients (like the MVP) do not support animations; and animations over remote connections are also disabled due to performance reasons.

Returns:
true if core animations are supported; false otherwise
Since:
7.0

GetUIRefreshLock

public boolean GetUIRefreshLock()
Acquires the lock for this user interface system to prevent other updates from occuring. This can be used at the start of an animation sequence before the refresh call is made to ensure that the animations will all occur on the same refresh cycle. The return value indicates if the lock was acquired. Do NOT release the lock unless you acquired the lock. This lock is re-entrant and is thread-based. You must release it from the same thread that acquired the lock. If this method return false, then you already have the lock. IMPORTANT: It is of CRITICAL IMPORTANCE that ReleaseUIRefreshLock() is called after GetUIRefreshLock() if this method returns true or the user interface system will become completely locked up for this client. It's also important to not release the lock unless you acquired it.

Returns:
true if the lock was acquired (which means it MUST be released), false if it was not
Since:
6.4

ReleaseUIRefreshLock

public void ReleaseUIRefreshLock()
Releases the lock for this user interface system to allow other updates to occur. This must ONLY be used after GetUIRefreshLock() was called and ONLY if GetUIRefreshLock() actually returned true. This must also be called from the same thread that called GetUIRefreshLock()

Since:
6.4

CalculateMD5Sum

public java.lang.String CalculateMD5Sum(java.io.File FilePath)
Calculates the MD5 Sum of a given file

Parameters:
FilePath - the path to the file who's MD sum should be calculated
Returns:
the MD5 sum of the specified file as a String, null if the file doesn't exist or there's an error reading it
Since:
6.3

ReloadNameserverCache

public void ReloadNameserverCache()
Reloads the name server cache. Should be used after reconfiguring the network adapter. NOTE: This is only valid on embedded platforms.


GetTimeSinceLastInput

public long GetTimeSinceLastInput()
Returns the amount of time in milliseconds since the last user input occurred for this UI (used for doing things while the user is idle)

Returns:
the amount of time in milliseconds since the last user input occurred
Since:
6.6

GetFileAsString

public java.lang.String GetFileAsString(java.io.File FilePath)
Opens the file at the specified path and reads the entire contents of it and returns it as a String. This will use the server's filesystem if executed on SageTVClient.

Parameters:
FilePath - the file path
Returns:
a String which represents the contents of the file; the emptry string if there was a failure
Since:
6.6

GetLocalFileAsString

public java.lang.String GetLocalFileAsString(java.io.File FilePath)
Opens the file at the specified path and reads the entire contents of it and returns it as a String.

Parameters:
FilePath - the file path
Returns:
a String which represents the contents of the file; the emptry string if there was a failure
Since:
8.0

IsLocalRestartNeeded

public boolean IsLocalRestartNeeded()
Returns true if the local instance of SageTV needs to be restarted due to a plugin install/uninstall

Returns:
true if the local instance of SageTV needs to be restarted due to a plugin install/uninstall, false otherwise
Since:
7.0

IsServerRestartNeeded

public boolean IsServerRestartNeeded()
Returns true if the server instance of SageTV needs to be restarted due to a plugin install/uninstall

Returns:
true if the server instance of SageTV needs to be restarted due to a plugin install/uninstall, false otherwise
Since:
7.0

Restart

public boolean Restart()
Restarts the local instance of SageTV. Sometimes needed after a plugin install/uninstall. If you want to restart the local and server instance; then perform the restart on the server first. This is only supported on Windows and Linux currently. If this is called from a SageTVClient running on the same machine as the server, this will invoke a restart of the locally running server as well in order to ensure proper file upgrade synchronization.

Returns:
true if restarting is supported (Although the restart will likely complete and the method will never return), false otherwise (Mac OS X does not have restart support)
Since:
7.0

ServerRestart

public boolean ServerRestart()
Restarts the server instance of SageTV. Sometimes needed after a plugin install/uninstall. If you want to restart the local and server instance; then perform the restart on the server first. This is only supported on Windows servers and Linux servers currently.

Returns:
true if restarting is supported (Although the restart will likely complete and the method will never return), false otherwise (Mac OS X server does not have restart support)
Since:
7.0

QueryServerMacAddress

public java.lang.String QueryServerMacAddress(java.lang.String Hostname)
Gets the MAC address of the SageTV server at the specified hostname. This will only work if SageTV is running on that host. This call uses a 3 second timeout internally.

Parameters:
Hostname - the hostname/IP of the SageTV server
Returns:
a String in the format 00:xx:xx:xx:xx:xx that represents the MAC of the server, or null if it fails
Since:
7.0

ScanWirelessAPs

public java.util.Map ScanWirelessAPs()
Scans for wireless access points and returns the results as a map. The keys are the SSID names and the values are Security;Strength where Security will be WEP/WPA/None and strength will be an integer between 0 and 100 NOTE: This is only valid on embedded platforms.

Returns:
a Map describing the results of the access point scan
Since:
6.6

ReformatDeviceAtPathAsEXT3

public int ReformatDeviceAtPathAsEXT3(java.lang.String DrivePath)
Determines the device that is mounted at the specified path, and then repartitions it to have a single EXT3 partition and then formats that partition. WARNING: THIS WILL DESTROY ALL INFORMATION ON THE TARGET DEVICE AND REFORMAT IT NOTE: This is only valid on embedded platforms.

Parameters:
DrivePath - the path string of a disk to reformat
Returns:
zero upon success, -1 if it is unable to find a device that corresponds to the requested path, -2 if it is unable to unmount that path, -3 if there was a problem re-partitioning or reformatting the drive, and -4 if there was a failure remounting the newly formatted drive
Since:
7.1

ConvertNteChars

public java.lang.String ConvertNteChars(java.lang.String NteString)
converts a string of NTE key characters (and normal characters) into their default character representation - given by the first character in the NTE chatacter list
The NTE key characters are the Unicode characters u2460-u2468 and u24EA (Unicode Circled Digits), representing the numeric Text Keys 1-9 and 0.
The characters represented by the keys are defined by the client properties "ui/numeric_text_input_<ui/translation_language_code>_<key>_lower.

Parameters:
NteString - the string to convert
Returns:
the converted string
Since:
8.0

StringIndexOfNTE

public java.lang.String StringIndexOfNTE(java.lang.String FullString,
                                         java.lang.String MatchStringNTE)
Returns the index of MatchStringNTE string within FullString, -1 if it is not found.
Search is case-insentive
The MatchStringNTE may contain the Unicode characters u2460-u2468 and u24EA (Unicode Circled Digits) representing numeric Text Keys 1-9 and 0. The characters represented by the keys are defined by the client properties "ui/numeric_text_input_<ui/translation_language_code>_<key>_lower.

Parameters:
FullString - the string to search in
MatchStringNTE - the string to search for
Returns:
the first 0-based index in FullString that MatchStringNTE occurs at or -1 if it is not found
Since:
8.0

StringStartsWithNTE

public java.lang.Boolean StringStartsWithNTE(java.lang.String FullString,
                                             java.lang.String MatchStringNTE)
Returns true if the Full String starts with characters matching MatchStringNTE
Search is case-insentive
The MatchStringNTE may contain the Unicode characters u2460-u2468 and u24EA (Unicode Circled Digits) representing numeric Text Keys 1-9 and 0. The characters represented by the keys are defined by the client properties "ui/numeric_text_input_<ui/translation_language_code>_<key>_lower.

Parameters:
FullString - the string to search in
MatchStringNTE - the string to search for
Returns:
true if FullString starts with characters matching MatchStringNTE
Since:
8.0

DumpServerThreadStates

public void DumpServerThreadStates()
Dumps all the java stack information on the SageTV server process to the server's debug output stream

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.