org.jmythapi.protocol
Interface IBackend

All Superinterfaces:
Closeable
All Known Implementing Classes:
Backend

public interface IBackend
extends Closeable

This interface is the main interface when communicating with a MythTV-backend. It allows to connect and to send commands to a MythTV-backend.

See the usage examples for a list of things you can do with a backend.

Supported Commands:

The following page contains a list of commands supported by a MythTV-backend: commands.
You can either send commands directly to a backend using a IBackendConnection, or you can use the more convenient functions provided by this backend class. Depending on the protocol version, different commands with different request arguments and response values are supported.

Supported Protocol Versions:

Protocol Version Ranges:
All listed functions are supported by at least one of the supported protocol-versions. If a given function is not supported by all known protocol-versions, it is marked with the MythProtoVersion annotation. Additionally the lower bound of the version range is documented with the @since javadoc tag, whereas the upper bound is documented with the @deprecated tag.

Extended Version Ranges:
Please note that many functions are usable (maybe with some restrictions) beyond the given protocol range, if an alternative set of functions can be used to achieve the same result. If such an "extended" version-range is available for a function, this is mentioned as "fallback-from"- and "fallback-to"-version in the functions javadoc.

Supported Versions:
Which protocol versions are in general supported by the jMythAPI can be seen in the enumeration ProtocolVersion.

How to start:

Connect to the backend:
There are a few mandatory steps to connect to a MythTV backend:
  1. Create a new backend object:
    IBackend backend = BackendFactory.createBackend(...)
  2. Establish a connection to the backend:
    backend.connect()
  3. Register the client to the backend: A playback connection blocks the shutdown of the backend whereas a monitoring does not.
  4. Use recorders:
    See here, if you need to work with recorders.

Use the backend:
Afterwards you can use any function provided by this interface to query and control your backend.
See the usage examples for some examples.

Disconnect from the backend:
To disconnect from the backend, backend.close() needs to be called.

Usage Examples:

The following section provides some examples how to use the backend class to send commands and get response.

Usage Example 1:

The following example shows how a connection can be established to a MythTV-backend and how a list of all pending recordings can be queried:


   // create a backend object
   IBackend backend = BackendFactory.createBackend("mythbox");
   
   // connect to the backend
   backend.connect();
   System.out.println("The backend is speeking protocol version: " + backend.getVersionNr());
   
   // register as a playback client
   backend.annotatePlayback();
   
   // query pending recordings
   IRecordingsPending pendingRecordings = backend.queryAllPending();
   System.out.println(String.format("MythTV has %d pending records", pendingRecordings.size()));
   for (IProgramInfo recording : pendingRecordings) {
   	System.out.println(recording);
   }
   
   // close backend connection
   backend.disconnect();
 

Usage Example 2:

An example how to connect to the next free recorder and to fetch all channels available on this recorder.


    // create a backend object
    IBackend backend = BackendFactory.createBackend("mythbox");
    backend.connect();
    backend.annotatePlayback();

    // searching for the next free recorder
    IRecorderInfo recorderInfo = backend.getNextFreeRecorder();
    if(recorderInfo == null) {
        System.out.println("No free recorder available");
    } else {
        // connect to the recorder
        IRecorder recorder = backend.getRecorder(recorderInfo);
        System.out.println("Connected to recorder " + recorder);
        
        // get all channels available on this recorder
        List<IRecorderChannelInfo> channels = recorder.getChannelInfos();
        for(IRecorderChannelInfo channel : channels) {
            System.out.println(String.format("Channel %d: %s",channel.getChannelID(),channel.getChannelName()));
        }
        
        // close recorder connection
        recorder.close();
    }
    
   // close backend connection
   backend.disconnect();
 

More usage Examples:

See the javadoc for the methods provided by this interface, e.g.

See Also:
All supported protocol version

Method Summary
<Event extends IMythEvent<?>>
void
addEventListener(Class<Event> eventClass, IMythEventListener<Event> listener)
           
 void addEventPacketListener(IMythEventPacketListener listener)
          Registers a new event listener.
 Boolean allowShutdown()
          Allows a backend to shutdown.
 IFileTransfer annotateFileTransfer(IProgramInfo programInfo)
          Announce a new file-transfer connection to the backend.
 IFileTransfer annotateFileTransfer(IProgramInfo programInfo, Boolean useReadAhead, Integer retries, Integer timeoutMs)
          Announce a new file-transfer connection to the backend.
 IFileTransfer annotateFileTransfer(String fileName, Boolean useReadAhead, Integer retries, Integer timeoutMs, String storageGroup)
          Announce a new file-transfer connection to the backend.
 FileTransfer annotateFileTransfer(String fileName, String storageGroup)
          Announce a new file-transfer connection to the backend.
 FileTransfer annotateFileTransfer(URI fileUrl)
          Announce a new file-transfer connection to the backend.
 boolean annotateMonitor()
          Announces a new monitor connection to the backend.
 boolean annotateMonitor(String clientHostName)
          Announces a new monitor connection to the backend.
 boolean annotateMonitor(String clientHostName, EPlaybackSockEventsMode eventsMode)
          Announces a new monitor connection to the backend.
 boolean annotatePlayback()
          Announce a new playback connection to the backend.
 boolean annotatePlayback(String clientHostName)
          Announce a new playback connection to the backend.
 boolean annotatePlayback(String clientHostName, EPlaybackSockEventsMode eventsMode)
          Announce a new playback connection to the backend.
 Boolean blockShutdown()
          Prevents a backend from shutting down.
 Integer checkRecording(IProgramInfo programInfo)
          Checks if the given program is currently being recorded.
 void clearSettingsCache()
          Forces the backend to clear its settings cache.
 void connect()
          Establishes a new connection to the backend.
 void connect(Integer connectionTimeout)
           
 boolean deleteFile(String fileName, String storageGroup)
          Delete a remote file.
 boolean deleteFile(URI fileUrl)
          Delete a remote file.
 boolean deleteRecording(Integer channelID, Date recordingStartTime)
          Deletes a recording-file.
 boolean deleteRecording(Integer channelID, Date recordingStartTime, Boolean forceMetadatDelete, Boolean forgetHistory)
          Delets a recording file, recording metadata and recording history.
 boolean deleteRecording(IProgramInfo programInfo)
          Deletes a recording file.
 boolean deleteRecording(IProgramInfo programInfo, Boolean forceMetadatDelete, Boolean forgetHistory)
          Delets a recording file, recording metadata and recording history.
 void disconnect()
          Disconnects from the backend.
 URI downloadFile(URI url, String storageGroup, String fileName)
          Downloads a file to the backend.
 URI downloadFileNow(URI url, String storageGroup, String fileName)
          Downloads a file to the backend.
 IProgramInfo fillProgramInfo(IProgramInfo programInfo)
          Fills in the pathname and file size fields of the given recording.
 IProgramInfo fillProgramInfo(IProgramInfo programInfo, String playBackHostname)
          Fills in the pathname and file size fields of the given recording.
 boolean forceDeleteRecording(IProgramInfo programInfo)
          Deletes a recording-file and recording metadata.
 boolean forgetRecording(IProgramInfo programInfo)
          Delets recording history.
 boolean freeTuner(Integer recorderID)
          Frees a previously locked tuner.
<C extends IBasicChannelInfo>
List<C>
getBasicChannelInfos()
          Get a list of all available channels on all available recorders.
 List<IRecorderChannelInfo> getChannelInfos()
          Get a list of all available channels on all available recorders.
 Map<String,String> getChannelLogoMap(IRecorderNextProgramInfo.Props keyProp)
          Gets a map containing the path to all channel logos.
 IBackendConnection getCommandConnection()
          Get the connection that was established to the backend.
 IRecorderInfo getFreeRecorder()
          A function to get the next free recorder.
 IRecorderInfo getFreeRecorder(String channelNumber)
          Gets the next free recorder that is capable to display the requested channel.
 int getFreeRecorderCount()
          Function to determine the amount of free recorders.
 int[] getFreeRecorderIDs()
          Gets the IDs of all free recorders.
 List<IRecorderInfo> getFreeRecorders()
          Gets the recorder-info objects of all free recorders.
 IBasicFreeSpace getFreeSpaceOverview()
          Gets the free space on the backend.
 String getHostName()
          Get the host name of the backend the client is connected to.
 int getHostPort()
          Get the connection port.
 IRecorderInfo getNextFreeRecorder()
          A function to get an info about the next free recorder.
 IRecorderInfo getNextFreeRecorder(Integer currentRecorderID)
          A function to get the next free recorder.
 IRecorderInfo getNextFreeRecorder(IRecorderInfo currentRecorder)
          A function to get the next free recorder.
 List<IRecorderNextProgramInfo> getNextProgramInfos(Date date)
          Gets the next programs of all known channels.
 IRecorder getRecorder(IRecorderInfo recorderInfo)
          Connects to the specified recorder.
 IRecorderInfo getRecorderForNum(int recorderId)
          Returns the recorder-info for the recorder, specified by id.
 IRecorderInfo getRecorderForProgram(IProgramInfo programInfo)
          Checks if the given program is currently being recorded and returns the recorder-info for the recorder or null, if it is not being recorded.
 int[] getRecorderIDs()
          Returns the IDs of all available recorders.
 IRecorderInfo getRecorderNum(IProgramInfo programInfo)
          Determines the recorder, which is currently recording the given program.
 List<IRecorderInfo> getRecorders()
          A function to get all available recorders, independently of their busy status.
 ProtocolVersion getVersionNr()
          Get the MythTV protocol-version the backend is speaking.
 boolean goToSleep()
          Signals a slave backend to go to sleep.
 boolean hasFreeRecorders()
          Determines if there are any free recorders.
 boolean isActiveBackend()
          Checks if the current backend is active.
 boolean isActiveBackend(String hostname)
          Checks if the given backend is active.
 boolean isConnected()
          Queries the current connection status.
 void liveTvChainUpdate(String chainId)
          XXX: is this event really required for a client?
 ITunerInfo lockTuner()
          Asks the backend to lock the next free tuner.
 ITunerInfo lockTuner(Integer recorderID)
          Asks the backend to lock the given tuner.
 List<String> queryActiveBackends()
          Queries the names of all active backends.
 IRecordingsPending queryAllPending()
          Gets all programs that will be recorded soon.
 IRecordingsScheduled queryAllScheduled()
          Gets all scheduled recordings.
 Long queryBookmark(Integer channelID, Date recordingStartTime)
          Queries the bookmark position for a given recording.
 Long queryBookmark(IProgramInfo program)
          Queries the bookmark position for a given recording.
 IFileStatus queryCheckFile(IProgramInfo programInfo, Boolean checkSlaves)
          Checks if a recording file exists that belongs to the given program.
 IRecordingsConflicting queryConflicting()
          Gets all programs that are in conflict which each other.
 IRecordingsConflicting queryConflicting(IProgramInfo programInfo)
          Gets all programs that are in conflict with the given program.
 IRecordingsExpiring queryExpiring()
          Gets all programs that will expiring soon.
 IFileStatus queryFileExists(IProgramInfo programInfo)
          Checks if a recording-file exists for the given program.
 IFileStatus queryFileExists(String fileName, String storageGroup)
          Checks if a the named file exists in the named storage group.
 FileStatus queryFileExists(URI fileUrl)
          Checks if given file exists on the backend.
 String queryFileHash(IProgramInfo programInfo)
          Queries a unique hash-value for the recording-file of the given program.
 String queryFileHash(String fileName, String storageGroup)
          Queries a unique hash-value for the given file stored in the given storage group.
 String queryFileHash(String fileName, String storageGroup, String hostName)
          Queries a unique hash-value for the given file stored in the given storage group.
 String queryFileHash(URI fileUrl)
          Queries a unique hash-value for the given remote file.
 IFreeSpace queryFreeSpace()
          Deprecated. 17 (fallback-to: -1), replaced by queryFreeSpaceList and queryFreeSpaceSummary
 IFreeSpaceList queryFreeSpaceList(boolean allhosts)
          Returns the free disk space on the connected or on all MythTV backends.
 IFreeSpaceSummary queryFreeSpaceSummary()
          Returns the free space on the connected backend.
 boolean queryGenPixmap(IProgramInfo program)
          Deprecated. 61 (fallback-to: -1), replaced by queryGenPixmap2
 boolean queryGenPixmap(IProgramInfo program, Boolean inSeconds, Long time, String fileName, Integer width, Integer height)
          Deprecated. 61 (fallback-to: -1), replaced by queryGenPixmap2
 boolean queryGenPixmap2(String token, IProgramInfo program)
          Generates a preview image of the requested show.
 boolean queryGenPixmap2(String token, IProgramInfo program, Boolean inSeconds, Long time, String fileName, Integer width, Integer height)
          Generates a preview image of the requested show.
 IGuideDataThrough queryGuideDataThrough()
          Queries the guide-date status of the backend.
 String queryHostname()
          Gets the hostname of the backend.
 IRecordingStatus queryIsRecording()
          Queries the current recording status of the backend.
 ILoad queryLoad()
          Queries the current load of the backend.
 IMemStats queryMemStats()
          Queries the current memory state of the backend.
 IPixmap queryPixmap(IProgramInfo program)
          Queries a preview image.
 IPixmap queryPixmap(String fileName, String storageGroup)
          Queries a preview image.
 IPixmap queryPixmapIfModified(IProgramInfo program, Date lastModifiedDate, Long fileSize)
          Queries a preview image.
 Date queryPixmapLastModified(IProgramInfo program)
          Queries the last-modified date of the pixmap of a given recording.
 IProgramInfo queryRecording(IBasicChannelInfo channel, Date recordingStartTime)
          Get a single recording by its channel and recording start-time.
 IProgramInfo queryRecording(Integer channelID, Date recordingStartTime)
          Get a single recording by its channel-id and start-time.
 IProgramInfo queryRecording(String baseName)
          Get the ProgramInfo for a single recording specified by the recordings base-name.
 IProgramInfoList queryRecordings()
          Queries for all available recordings.
 IProgramInfoList queryRecordings(ERecordingsType eRecordingsType)
          Queries for recordings with the given recording-type.
 ISetting querySetting(String hostName, String settingName)
          Queries the remote host for a specific setting.
 IStorageGroupFile queryStorageGroupFile(String hostName, String storageGroup, String fileName)
          Queries the a single file from the remote storage group.
 IStorageGroupFileList queryStorageGroupFileList(String hostName, String storageGroup, String path)
          Queries the a list of files from the remote storage group.
 IStorageGroupFileList queryStorageGroupFileList(String hostName, String storageGroup, String path, boolean fileNamesOnly)
          Queries the a list of files from the remote storage group.
 ITimezone queryTimeZone()
          Queries the timezone of the backend.
 IUptime queryUptime()
          Queries the uptime of the backend.
 boolean queueTranscode(IProgramInfo recording)
          Deprecated. 23
 boolean queueTranscodeCutlist(IProgramInfo recording)
          Deprecated. 23
 boolean queueTranscodeStop(IProgramInfo recording)
          Deprecated. 23
 boolean reactivateRecording(IProgramInfo programInfo)
          Deprecated. 19
 void recordingListChange()
           
 boolean refreshBackend()
          Forces the backend to reload the backend settings.
<Event extends IMythEvent<?>>
void
removeEventListener(Class<Event> eventClass, IMythEventListener<Event> listener)
           
 void removeEventPacketListener(IMythEventPacketListener listener)
          Unregisters a event listener.
 boolean rescheduleAllRecordings()
          Force MythTV to reschedule all recordings.
 Boolean rescheduleAllRecordingsAndWait(long timeout, TimeUnit unit)
          Forces MythTV to reschedule all recordings and thereafter to wait for an SCHEDULE_CHANGE event.
 boolean rescheduleRecordings(Integer recordingId)
          Deprecated. 73 (fallback-to: -1), use rescheduleRecordingsMatch(Integer, Integer, Integer, Date, String) instead.
 Boolean rescheduleRecordingsAndWait(Integer recordingId, long timeout, TimeUnit unit)
          Deprecated. 73 (fallback-to: -1)
 boolean rescheduleRecordingsMatch(Integer recordID, Integer sourceID, Integer multiplexID, Date maxStartTime, String reason)
          Deprecated. 73 (fallback-to: -1), use rescheduleRecordingsMatch(Integer, Integer, Integer, Date, String) instead.
 Boolean rescheduleRecordingsMatchAndWait(Integer recordID, Integer sourceID, Integer multiplexID, Date maxStartTime, String reason, long timeout, TimeUnit unit)
           
 boolean scanVideos()
          Trigger a scan of all video folders.
 boolean setBookmark(Integer channelID, Date recordingStartTime, Long bookmarkPosition)
          Sets the bookmark position for the given recording.
 boolean setBookmark(IProgramInfo recording, Long bookmarkPosition)
          Sets the bookmark position for the given recording.
 boolean setChannelInfo(String oldChannelNumber, IRecorderChannelInfo channelInfo)
          Changes detailed infos about the given channel.
 void setInitialVersionNr(ProtocolVersion protoVersion)
          Sets the initial protocol-version that should be used for handshake.
 boolean setSetting(String hostName, String settingName, String settingValue)
          Sets the given setting on the remote host.
 void shutdownNow()
          Forces a slave backend to shutdown now.
 Integer stopRecording(IProgramInfo programInfo)
          Stop a currently active recording.
 boolean undeleteRecording(IProgramInfo programInfo)
          Undelets a recording-file.
 
Methods inherited from interface java.io.Closeable
close
 

Method Detail

getCommandConnection

IBackendConnection getCommandConnection()
Get the connection that was established to the backend.

Returns:
the established connection or null if no connection was established so far

getHostName

String getHostName()
Get the host name of the backend the client is connected to.

Returns:
the host name of the backend

getHostPort

int getHostPort()
Get the connection port.

Returns:
the port of the backend

getVersionNr

ProtocolVersion getVersionNr()
Get the MythTV protocol-version the backend is speaking.

Returns:
the protocol version the backend is speaking.

setInitialVersionNr

void setInitialVersionNr(ProtocolVersion protoVersion)
Sets the initial protocol-version that should be used for handshake.

Parameters:
protoVersion - the initial protocol version

connect

void connect()
             throws IOException
Establishes a new connection to the backend.

Once the connection is established, the protocol-version is negotiated.

Throws:
IOException - on communication errors

connect

void connect(Integer connectionTimeout)
             throws IOException
Throws:
IOException

disconnect

void disconnect()
Disconnects from the backend.


isConnected

boolean isConnected()
Queries the current connection status.

Returns:
true if a connection was established.

annotatePlayback

boolean annotatePlayback()
                         throws IOException
Announce a new playback connection to the backend.

This signals that backend that a new client will start playback and prevents it from shutting down the socket.

Returns:
true if the backend respond with OK
Throws:
IOException - on communication errors
Since:
00
See Also:
ANN_PLAYBACK
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

annotatePlayback

boolean annotatePlayback(String clientHostName)
                         throws IOException
Announce a new playback connection to the backend.

This signals that backend that a new client will start playback and prevents it from shutting down the socket.

Parameters:
clientHostName - the name of the client
Returns:
true if the backend respond with OK
Throws:
IOException - on communication errors
Since:
00
See Also:
ANN_PLAYBACK
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

annotatePlayback

boolean annotatePlayback(String clientHostName,
                         EPlaybackSockEventsMode eventsMode)
                         throws IOException
Announce a new playback connection to the backend.

This signals that backend that a new client will start playback and prevents it from shutting down the socket.

Parameters:
clientHostName - the name of this client
eventsMode - the type of events the client is interested in.
Returns:
true if the backend respond with OK
Throws:
IOException - on communication errors
Since:
00
See Also:
ANN_PLAYBACK
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

annotateMonitor

boolean annotateMonitor()
                        throws IOException
Announces a new monitor connection to the backend.

This signals that backend that a new client will start querying the backend but does not prevents it from shutting down the socket.

Returns:
true if the backend respond with OK
Throws:
IOException - on communication errors
Since:
22
See Also:
ANN_MONITOR
MythTV protocol range: [22,-1)
 VersionDateAdditional Version Info
Added222005-11-15Changelog, SVN-Rev.: 7883
Removed-1 

annotateMonitor

boolean annotateMonitor(String clientHostName)
                        throws IOException
Announces a new monitor connection to the backend.

This signals that backend that a new client will start querying the backend but does not prevents it from shutting down the socket.

Parameters:
clientHostName - the host name of the client
Returns:
true if the backend respond with OK
Throws:
IOException - on communication errors
Since:
22
See Also:
ANN_MONITOR
MythTV protocol range: [22,-1)
 VersionDateAdditional Version Info
Added222005-11-15Changelog, SVN-Rev.: 7883
Removed-1 

annotateMonitor

boolean annotateMonitor(String clientHostName,
                        EPlaybackSockEventsMode eventsMode)
                        throws IOException
Announces a new monitor connection to the backend.

This signals that backend that a new client will start querying the backend but does not prevents it from shutting down the socket.

Parameters:
clientHostName - the name of this client
eventsMode - the type of events the client is interested in.
Returns:
true if the backend respond with OK
Throws:
IOException - on communication errors
Since:
22
See Also:
ANN_MONITOR
MythTV protocol range: [22,-1)
 VersionDateAdditional Version Info
Added222005-11-15Changelog, SVN-Rev.: 7883
Removed-1 

annotateFileTransfer

IFileTransfer annotateFileTransfer(IProgramInfo programInfo)
                                   throws IOException
Announce a new file-transfer connection to the backend.

Usage example:


    // getting previously recorded programs
    IProgramInfoList programs = backend.queryRecordings();
    
    // getting the recording to transfer (we just use the first recording)
    IProgramInfo program = programs.get(0);
    		
    // annotate a new file transfer
    IFileTransfer transfer = backend.annotateFileTransfer(program);	
    if (transfer.isOpen()) {
       // set fast timeout
       transfer.setTimeout(true);
       
       // copy data
       File tempFile = File.createTempFile("fileTransfer", ".mpg");
       transfer.transferTo(tempFile);
    }
    		
    // close file transfer
    transfer.close();
 

Parameters:
programInfo - the program, whose file should be transfered
Returns:
a file-transfer object that can be used to fetch the data.
Throws:
IOException - on communication errors
Since:
00
See Also:
annotateFileTransfer(String, Boolean, Integer, Integer, String), ANN_FILE_TRANSFER
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

annotateFileTransfer

IFileTransfer annotateFileTransfer(IProgramInfo programInfo,
                                   Boolean useReadAhead,
                                   Integer retries,
                                   Integer timeoutMs)
                                   throws IOException
Announce a new file-transfer connection to the backend.

It reads the file-name and storage-group from the given program-info object and calls annotateFileTransfer(String, Boolean, Integer, Integer, String).

Parameters:
programInfo - the program, whose file should be transfered
useReadAhead - if the backend should read ahead the requested location via a separate thread (since 29)
retries - how many retries should be done before giving up (since 29, deprecated 60)
timeoutMs - the timeout to wait for data in milliseconds (since 60)
Returns:
a file-transfer object that can be used to fetch the data.
Throws:
IOException - on communication errors
Since:
00
See Also:
annotateFileTransfer(String, Boolean, Integer, Integer, String), ANN_FILE_TRANSFER
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Changed292006-04-01Changelog, SVN-Rev.: 9592
Changed602010-09-03Changelog, SVN-Rev.: 26101
Removed-1 

annotateFileTransfer

FileTransfer annotateFileTransfer(URI fileUrl)
                                  throws IOException
Announce a new file-transfer connection to the backend.

This method calls URI.getUserInfo() and URI.getPath() to determine the storage-group and file name and calls annotateFileTransfer(String, Boolean, Integer, Integer, String) afterwards.

Parameters:
fileUrl - the URI to the file to transfer
Returns:
a file-transfer object that can be used to fetch the data.
Throws:
IOException - on communication errors
Since:
00
See Also:
ANN_FILE_TRANSFER
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

annotateFileTransfer

FileTransfer annotateFileTransfer(String fileName,
                                  String storageGroup)
                                  throws IOException
Announce a new file-transfer connection to the backend.

This method internally calls annotateFileTransfer(String, Boolean, Integer, Integer, String).

Usage example:


     IBackend backend = ...;      // an already connected backend
     IProgramInfo program = ...;  // a previously recorded program
     
     // the storage group and name of the recording preview image
     String storagGroup = program.getStorageGroup();
     String previewFileName = program.getPreviewImageName();
     
     // transfering the recording preview image to the client
     File targetFile = File.createTempFile("preview", ".png");
     IFileTransfer transfer = backend.annotateFileTransfer(previewFileName,storagGroup);
     transfer.transferTo(targetFile);
     transfer.close();
 

Parameters:
fileName - the name of the file to be transfered
storageGroup - the name of the storage-group the file is located in (since 44)
Returns:
a file-transfer object that can be used to fetch the data.
Throws:
IOException - on communication errors
Since:
00
See Also:
ANN_FILE_TRANSFER
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Changed442009-02-12Changelog, SVN-Rev.: 19978
Removed-1 

annotateFileTransfer

IFileTransfer annotateFileTransfer(String fileName,
                                   Boolean useReadAhead,
                                   Integer retries,
                                   Integer timeoutMs,
                                   String storageGroup)
                                   throws IOException
Announce a new file-transfer connection to the backend.

This command must be sent as first command after calling connect().

Usage example:


     IBackend backend = ...;      // an already connected backend
     IProgramInfo program = ...;  // a previously recorded program
     
     // the storage group and name of the recording preview image
     String storagGroup = program.getStorageGroup();
     String previewFileName = program.getPreviewImageName();
     
     // transfering the recording preview image to the client
     File targetFile = File.createTempFile("preview", ".png");
     IFileTransfer transfer = backend.annotateFileTransfer(previewFileName, Boolean.TRUE, -1, 2000, storagGroup);
     transfer.transferTo(targetFile);
     transfer.close();
 

Parameters:
fileName - the name of the file to be transfered
storageGroup - the name of the storage-group the file is located in (since 44)
useReadAhead - if the backend should read ahead the requested location via a separate thread. If null then true is used. (since 29)
retries - how many retries should be done before giving up. If null then -1 is used. (since 29, deprecated 60)
timeoutMs - the timeout to wait for data in milliseconds. If null then 2000 is used. (since 60)
Returns:
a file-transfer object that can be used to fetch the data.
Throws:
IOException - on communication errors
Since:
00
See Also:
ANN_FILE_TRANSFER
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Changed292006-04-01Changelog, SVN-Rev.: 9592
Changed442009-02-12Changelog, SVN-Rev.: 19978
Changed602010-09-03Changelog, SVN-Rev.: 26101
Removed-1 

getRecorder

IRecorder getRecorder(IRecorderInfo recorderInfo)
                      throws IOException
Connects to the specified recorder.

This method and returns a recorder object which allows to send command to the recorder.

Usage example:


    IBackend backend = ....; // an already connected backend
 
    // getting the next free recorder
    IRecorderInfo recorderInfo = backend.getNextFreeRecorder();
    if(recorderInfo != null) {
       // connect to the recorder
       IRecorder recorder = backend.getRecorder(recorderInfo);
       
       // send commands to the recorder ...
       
       // e.g., getting all available channel 
       List<IBasicChannelInfo> channels = recorder.getBasicChannelInfos();
       for(IBasicChannelInfo channel : channels) {
          System.out.println(String.format("Channel %d: %s",channel.getChannelID(),channel.getChannelSign()));
       }
    } else {
       System.out.println("No free recorder available");
    }
  

Parameters:
recorderInfo - informations about the recorder
Returns:
the connected recorder
Throws:
IOException - on communication errors
Since:
00
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

getNextFreeRecorder

IRecorderInfo getNextFreeRecorder()
                                  throws IOException
A function to get an info about the next free recorder.

Throws:
IOException
Since:
03
See Also:
GET_NEXT_FREE_RECORDER
MythTV protocol range: [03,-1)
 VersionDateAdditional Version Info
Added032004-02-05Changelog, SVN-Rev.: 3112
Removed-1 

getNextFreeRecorder

IRecorderInfo getNextFreeRecorder(Integer currentRecorderID)
                                  throws IOException
A function to get the next free recorder. Searching is started with the given recorder-ID.

Parameters:
currentRecorderID - the current recorder id
Returns:
info about the next free recorder or null if no recorder is available.
Throws:
IOException - on communication errors
Since:
03
See Also:
GET_NEXT_FREE_RECORDER
MythTV protocol range: [03,-1)
 VersionDateAdditional Version Info
Added032004-02-05Changelog, SVN-Rev.: 3112
Removed-1 

getNextFreeRecorder

IRecorderInfo getNextFreeRecorder(IRecorderInfo currentRecorder)
                                  throws IOException
A function to get the next free recorder. Searching is started with the given recorder.

Parameters:
currentRecorder - the current recorder
Returns:
info about the next free recorder or null if no recorder is available.
Throws:
IOException - on communication errors
Since:
03
See Also:
GET_NEXT_FREE_RECORDER
MythTV protocol range: [03,-1)
 VersionDateAdditional Version Info
Added032004-02-05Changelog, SVN-Rev.: 3112
Removed-1 

getFreeRecorder

IRecorderInfo getFreeRecorder()
                              throws IOException
A function to get the next free recorder.

This is similar to getNextFreeRecorder(), except that it tries to get a recorder on the local machine if possible.

Throws:
IOException - on communication errors
Since:
00
See Also:
GET_FREE_RECORDER
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

getFreeRecorder

IRecorderInfo getFreeRecorder(String channelNumber)
                              throws IOException
Gets the next free recorder that is capable to display the requested channel.

Parameters:
channelNumber - the desired channel
Returns:
the next free recorder or null
Throws:
IOException - on communication errors
Since:
03
See Also:
IRecorder.checkChannel(String)

getRecorders

List<IRecorderInfo> getRecorders()
                                 throws IOException
A function to get all available recorders, independently of their busy status.

This function uses getRecorderForNum, starting with recorder-index 1, to determine all available recorders.

Usage Hint:

Use getFreeRecorders to only get free recorders.

Usage example:


    IBackend backend = ...; // an already connected backend
    
    // determine all available recorders
    List<IRecorderInfo> recorderInfos = backend.getRecorders();
    
    // print out the recorder connection infos
    System.out.println(String.format("%d recorders found:",recorderInfos.size()));
    for(IRecorderInfo recorderInfo : recorderInfos) {
       System.out.println(String.format(
          "%02d: %s:%d",
          recorderInfo.getRecorderID(),
          recorderInfo.getHostName(),
          recorderInfo.getHostPort()
       ));
    }
 

The above example will output, e.g.
 3 recorders found:
 01: 192.168.10.202:6543
 02: 192.168.10.202:6543
 03: 192.168.10.202:6543
 

Returns:
a list of all available (but not necessarily free) recorders.
Throws:
IOException - on communication errors
Since:
00
See Also:
GET_RECORDER_FROM_NUM, getRecorderForNum(int)
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

getRecorderIDs

int[] getRecorderIDs()
                     throws IOException
Returns the IDs of all available recorders.

This method returns all recorders, independently of their busy status.
The returned IDs can be used as argument for function getRecorderForNum to fetch further information about the recorders.

Usage Hint:

Use getFreeRecorderIDs to only get the IDs of all free recorders.

Usage example:


    IBackend backend = ...; // an already connected backend
    
    // get the IDs of all available (busy or idle) recorders
    int[] allRecorderIDs = backend.getRecorderIDs();
    System.out.println(String.format(
       "%d recorders are available:", allRecorderIDs.length
    ));
    
    for(int recorderId : allRecorderIDs) {
       // get the recorder info
       IRecorderInfo recorderInfo = backend.getRecorderForNum(recorderId);
       
       // connect to the recorder
       IRecorder recorder = backend.getRecorder(recorderInfo);
       
       // get the recorder status
       boolean isRecording = recorder.isRecording();
       System.out.println(String.format(
          "Recorder %d is currently %s",
          recorderId,
          isRecording?"busy":"idle"
       ));
    }
 

The above example will output, e.g.:
 3 recorders are available:
 Recorder 1 is currently busy
 Recorder 2 is currently idle
 Recorder 3 is currently idle
 

Returns:
the IDs of all available recorders.
Throws:
IOException - on communication errors
Since:
00
See Also:
GET_RECORDER_FROM_NUM, getRecorders()
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

getRecorderForNum

IRecorderInfo getRecorderForNum(int recorderId)
                                throws IOException
Returns the recorder-info for the recorder, specified by id.

Usage example:


    IBackend backend = ...; // an already connected backend
    
    // getting recorder info by recorder-id
    IRecorderInfo recorderInfo = backend.getRecorderForNum(recorderId);
    
    // connect to the recorder
    IRecorder recorder = backend.getRecorder(recorderInfo);
    
    // getting the currently active recorder input and channel			
    String recorderInput = recorder.getInput();
    IBasicChannelInfo recorderChannel = recorder.getCurrentChannel();
    System.out.println(String.format(
       "Recorder %d is using input: %s (channel: %s).",
       recorderId, recorderInput, recorderChannel.getChannelSign()
    ));
 

The above example will output, e.g.:
 Recorder 1 is using input: Tuner 1 (channel: PRO7).
 

Parameters:
recorderId - the recorder id
Returns:
info about the recorder or null if no recorder was found.
Throws:
IOException - on communication errors
Since:
00
See Also:
GET_RECORDER_FROM_NUM
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

getRecorderNum

IRecorderInfo getRecorderNum(IProgramInfo programInfo)
                             throws IOException
Determines the recorder, which is currently recording the given program.

Parameters:
programInfo - the recording
Returns:
the recorder-info object about the recorder, that is currently recording the given program, or null if no recorder was found.
Throws:
IOException - on communication errors
Since:
00
See Also:
GET_RECORDER_NUM
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

getFreeRecorderCount

int getFreeRecorderCount()
                         throws IOException
Function to determine the amount of free recorders.

Protocol Version Hint:

If this function is called prior to 09, then getFreeRecorderIDs() is called to determine the amount of free recorders.

Usage example:


    IBackend backend = ...; // an already connected backend
    
    // get the amount of free recorders
    int freeRecorderCount = backend.getFreeRecorderCount();
    System.out.println(String.format(
       "%d free recorders found.",
       freeRecorderCount
    ));
 

Returns:
the current amount of free recorders.
Throws:
IOException - on communication errors
Since:
09 (fallback-from: 03)
See Also:
GET_FREE_RECORDER_COUNT
MythTV protocol range: [09,-1)
 VersionDateAdditional Version Info
Fallback032004-02-05The function can be can be used with restrictions starting with version 3.
Added092004-06-04Changelog, SVN-Rev.: 3838
Removed-1 

getFreeRecorderIDs

int[] getFreeRecorderIDs()
                         throws IOException
Gets the IDs of all free recorders.

This function returns a list of free recorders IDs, or an empty list if none. The returned IDs can be used as argument for function getRecorderForNum(int) to fetch further information about the recorders.

Usage Hint:

Use getRecorderIDs to get the id of all (busy or idle) recorders.

Protocol Version Hint:

If this function is called prior to protocol-version 17, then it uses getNextFreeRecorder(Integer) to determine the IDs of all free recorders.

Usage example:


    IBackend backend = ...; // an already connected backend
    
    // query the IDs of all free recorders
    int[] freeRecorderIDs = backend.getFreeRecorderIDs();
    System.out.println(String.format(
       "The following recorders are ready to use: %s",
       Arrays.toString(freeRecorderIDs)
    ));
 

Returns:
the IDs of all currently free recorders.
Throws:
IOException - on communication errors
Since:
17 (fallback-from: 03)
See Also:
GET_FREE_RECORDER_LIST
MythTV protocol range: [17,-1)
 VersionDateAdditional Version Info
Fallback032004-02-05The function can be can be used with restrictions starting with version 3.
Added172005-05-24Changelog, SVN-Rev.: 6482
Removed-1 

hasFreeRecorders

boolean hasFreeRecorders()
                         throws IOException
Determines if there are any free recorders.

This function used getFreeRecorderCount to determine if there is at lease one free recorder available.

Returns:
true if there is at least one free recorder available
Throws:
IOException - on communication errors
Since:
03
See Also:
GET_FREE_RECORDER_COUNT
MythTV protocol range: [03,-1)
 VersionDateAdditional Version Info
Added032004-02-05Changelog, SVN-Rev.: 3112
Removed-1 

getFreeRecorders

List<IRecorderInfo> getFreeRecorders()
                                     throws IOException
Gets the recorder-info objects of all free recorders.

This method internally uses getFreeRecorderIDs() to determine all free recorders and getRecorderForNum(int) to fetch the information for a recorder.

Usage Hint:

Use getRecorders to get all (busy or idel) recorders.

Returns:
a list of free recorders
Throws:
IOException - on communication errors
Since:
03
See Also:
GET_FREE_RECORDER_LIST, GET_RECORDER_FROM_NUM
MythTV protocol range: [03,-1)
 VersionDateAdditional Version Info
Added032004-02-05Changelog, SVN-Rev.: 3112
Removed-1 

recordingListChange

void recordingListChange()
                         throws IOException
Throws:
IOException - on communication errors
See Also:
BACKEND_MESSAGE_RECORDING_LIST_CHANGE

liveTvChainUpdate

void liveTvChainUpdate(String chainId)
                       throws IOException
XXX: is this event really required for a client?

Parameters:
chainId - TODO
Throws:
IOException - on communication errors
Since:
20
See Also:
BACKEND_MESSAGE_LIVETV_CHAIN
MythTV protocol range: [20,-1)
 VersionDateAdditional Version Info
Added202005-11-05Changelog, SVN-Rev.: 7739
Removed-1 

queryRecordings

IProgramInfoList queryRecordings()
                                 throws IOException
Queries for all available recordings.

Usage Hint:

Use queryAllScheduled to get all scheduled recordings.
Use queryAllPending to get all pending recordings.
Use queryConflicting to get all conflicting recordings.
Use queryExpiring to get all expiring recordings.

Protocol Version Hint:

Prior to protocol version 19 the recording-status was not set properly by the MythTV-backend. For this protocol versions, this function additionally uses queryAllPending() to determine, which of the returned recordings are still in progress.

Usage example:


    // query all available recordings
    IProgramInfoList allRecordings = backend.queryRecordings();
    
    // print the channel, length, file-size and title of all recordings
    System.out.println("Channel | Length  | Size     | Title");
    for(IProgramInfo program : allRecordings) {
       // print out the found recodings
       System.out.println(String.format(
          "%-5s | %3d min | %8s | %s",
          program.getChannelSign(),
          program.getDuration(),
          EncodingUtils.getFormattedFileSize(Locale.ENGLISH,program.getFileSize()),
          program.getFullTitle()
       ));			
    }
 

The above example will output, e.g.

 Channel | Length  | Size     | Title
 ATV+    |  55 min |  3.51 GB | Dr. Quinn - Ärztin aus Leidenschaft - Für das Leben der Cheyenne
 RTL2    |  30 min |  2.34 GB | King of Queens - Wer schön sein will ...
 RTL2    |  30 min |  2.34 GB | King of Queens - Das Haus am See
 

Returns:
all found recordings
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_RECORDINGS, QUERY_ISRECORDING, QUERY_GETALLPENDING
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Changed192005-10-09Changelog, SVN-Rev.: 7427
Removed-1 

queryRecordings

IProgramInfoList queryRecordings(ERecordingsType eRecordingsType)
                                 throws IOException
Queries for recordings with the given recording-type.

Usage Hint:

Use queryAllScheduled to get all scheduled recordings.
Use queryAllPending to get all pending recordings.
Use queryConflicting to get all conflicting recordings.
Use queryExpiring to get all expiring recordings.

Protocol Version Hint:

Prior to protocol version 19 the recording-status was not set properly by the MythTV-backend. For this protocol versions, this function additionally uses queryAllPending() to determine, which of the returned recordings are still in progress.

Parameters:
eRecordingsType - the type of the requested recordings. Use null or ERecordingsType.Play to query all available recordings.
Returns:
all found recordings for the given type
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_RECORDINGS, QUERY_ISRECORDING, QUERY_GETALLPENDING
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Changed192005-10-09Changelog, SVN-Rev.: 7427
Removed-1 

queryGenPixmap

boolean queryGenPixmap(IProgramInfo program)
                       throws IOException
Deprecated. 61 (fallback-to: -1), replaced by queryGenPixmap2

Generates a preview image of the requested show.

Usage Hint:

Use queryPixmapLastModified to query the last modified date of the pixmap.
Use queryPixmap to download the pixmap file.

Protocol Version Hint:

If this method is called with a protocol version greater than 60, then this method calls queryGenPixmap2(...).

Usage example:


      IBackend backend = ....;    // an already connected backend
      IProgramInfo program = ...; // a previously recorded program
 
      // generate the preview image
      if (backend.queryGenPixmap(program) {
          // getting the preview image name
          String imageName = program.getPreviewImageName();
          
          // create a temp file to store the preview image
          File targetFile = File.createTempFile("preview", ".png");
          
          // copy the png to the client
          IFileTransfer transfer = backend.annotateFileTransfer(imageName, null, null, null);
          transfer.transferTo(targetFile);
          transfer.close();
          
          // load the image
          BufferedImage image = ImageIO.read(targetFile);
          System.out.println(String.format(
          	"Image %s has a size of %dx%d",
          	targetFile.getName(),
          	image.getWidth(), image.getHeight()
          ));
      } else {
      	Sytem.error.println("Preview image generation failed.");
      }
 

Parameters:
program - the recording, for which a preview image should be generated
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_GENPIXMAP
MythTV protocol range: [00,61)
 VersionDateAdditional Version Info
Added00 
Changed602010-09-03Changelog, SVN-Rev.: 26101
Removed612010-09-03Changelog, SVN-Rev.: 26106
Fallback-1 The function can be can be used with restrictions till version 77.

queryGenPixmap

boolean queryGenPixmap(IProgramInfo program,
                       Boolean inSeconds,
                       Long time,
                       String fileName,
                       Integer width,
                       Integer height)
                       throws IOException
Deprecated. 61 (fallback-to: -1), replaced by queryGenPixmap2

Generates a preview image of the requested show.

Usage Hint:

Use queryPixmapLastModified to query the last modified date of the pixmap.
Use queryPixmap to download the pixmap file.

Protocol Version Hint:

If this method is called with a protocol version greater or equal to 61, then this method calls queryGenPixmap2(...).

Parameters:
program - the recording, to grab a preview image from
inSeconds - if true time is in seconds, otherwise it is in frames (since 37)
time - the seconds or frames into the video to seek before capturing a frame (since 37)
fileName - the filename to use (since 37)
width - the preview image width (since 37)
height - the preview image height (since 37)
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_GENPIXMAP
MythTV protocol range: [00,61)
 VersionDateAdditional Version Info
Added00 
Changed372008-01-14Changelog, SVN-Rev.: 15437
Removed612010-09-03Changelog, SVN-Rev.: 26106
Fallback-1 The function can be can be used with restrictions till version 77.

queryGenPixmap2

boolean queryGenPixmap2(String token,
                        IProgramInfo program)
                        throws IOException
Generates a preview image of the requested show.

Usage Hint:

Use queryPixmapLastModified to query the last modified date of the pixmap.
Use queryPixmap to download the pixmap.
Use queryGenPixmap2 to generate an alternative pixmap.

Listen to the event IPixmapGenerated to receive a notification about the finished generation of the pixmap.

Protocol Version Hint:

If this method is called with a protocol version less than 61, then queryGenPixmap is called instead.

Parameters:
token - a unique token that is assigned to the generation job.
program - the recording, for which a preview image should be generated
Returns:
true on success
Throws:
IOException - on communication errors
Since:
61 (fallback-from: 00), replaces queryGenPixmap
See Also:
QUERY_GENPIXMAP2
MythTV protocol range: [61,-1)
 VersionDateAdditional Version Info
Fallback00 The function can be can be used with restrictions starting with version 0.
Added612010-09-03Changelog, SVN-Rev.: 26106
Removed-1 

queryGenPixmap2

boolean queryGenPixmap2(String token,
                        IProgramInfo program,
                        Boolean inSeconds,
                        Long time,
                        String fileName,
                        Integer width,
                        Integer height)
                        throws IOException
Generates a preview image of the requested show.

Usage Hint:

Use queryPixmapLastModified to query the last modified date of the pixmap.
Use queryPixmap to download the pixmap file.

Listen to the event IPixmapGenerated to receive a notification about the finished generation of the pixmap.

Protocol Version Hint:

If this method is called with a protocol version less than 61, then queryGenPixmap is called instead.

Parameters:
token - a unique token that is assigned to the generation job.
program - the recording, for which a preview image should be generated
inSeconds - if true time is in seconds, otherwise it is in frames
time - the seconds or frames into the video to seek before capturing a frame
fileName - the filename to use
width - the preview image width
height - the preview image height
Returns:
true on success
Throws:
IOException - on communication errors
Since:
61 (fallback-from: 00), replaces queryGenPixmap
See Also:
QUERY_GENPIXMAP2
MythTV protocol range: [61,-1)
 VersionDateAdditional Version Info
Fallback00 The function can be can be used with restrictions starting with version 0.
Added612010-09-03Changelog, SVN-Rev.: 26106
Removed-1 

queryPixmapLastModified

Date queryPixmapLastModified(IProgramInfo program)
                             throws IOException
Queries the last-modified date of the pixmap of a given recording.

Usage Hint:

Use queryGenPixmap2 to generate the pixmap.
Use queryPixmap to download the pixmap.

Usage example:


    IBackend backend = ...;      // an already connected backend
    IProgramInfo program = ...;  // a previously recorded program
    
    // get the pixmal last modified date
    Date lastMod = backend.queryPixmapLastModified(program);
    System.out.println(String.format(
       "Pixmap of program '%s' was last modified at '%tc'.",
       program.getTitle(),
       lastMod
    ));
 

Parameters:
program - the recording whose pixmap should be checked.
Returns:
the last-modified date of the pixmap
Throws:
IOException - on communication errors
Since:
17
See Also:
QUERY_PIXMAP_LASTMODIFIED
MythTV protocol range: [17,-1)
 VersionDateAdditional Version Info
Added172005-05-24Changelog, SVN-Rev.: 6482
Removed-1 

queryPixmap

IPixmap queryPixmap(IProgramInfo program)
                    throws IOException
Queries a preview image.

Usage Hint:

Use queryPixmapLastModified to determine the last-modified date of the pixmap.
Use queryGenPixmap2 to generate the pixmap.
Use queryPixmap do download a pixmap with a different name.

Protocol Version Hint:

For version prior to 49, this method uses annotateFileTransfer(String, String) to download the preview image. For later versions queryPixmapIfModified(IProgramInfo, Date, Long) is used.

Parameters:
program - the recording whose pixmap should be returned
Returns:
the downloaded preview image or null
Throws:
IOException - on communication errors
Since:
00
See Also:
IMythCommand.QUERY_PIXMAP_GET_IF_MODIFIED, IMythCommand.ANN_FILE_TRANSFER
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Changed492009-10-01Changelog, SVN-Rev.: 22164
Removed-1 

queryPixmap

IPixmap queryPixmap(String fileName,
                    String storageGroup)
                    throws IOException
Queries a preview image.

This function uses annotateFileTransfer(String, String) to download the preview image file with the given name.

See queryPixmapLastModified if you just want to determine the last-modified date of the pixmap.
See queryGenPixmap2 on how to generate the pixmap.

Parameters:
fileName - the name of the pixmap file
storageGroup - the storage group of the pixmap. If null then Default is used.
Returns:
the downloaded preview image or null
Throws:
IOException - on communication errors
Since:
00
See Also:
IMythCommand.ANN_FILE_TRANSFER
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

queryPixmapIfModified

IPixmap queryPixmapIfModified(IProgramInfo program,
                              Date lastModifiedDate,
                              Long fileSize)
                              throws IOException
Queries a preview image.

This command can be used to download a previously generated preview image.
Optionally it can be specified that the preview image should only be returned:

Usage Hint:

Use queryPixmapLastModified if you just want to determine the last-modified date of the pixmap.
Use queryGenPixmap2 to generate the pixmap.

Protocol Version Hint:

If this funtion is called prior to proto version 49, than it uses queryPixmapLastModified to determine the last modified timestamp of the image, and calls annotateFileTransfer afterwards to download the image.

Parameters:
program - the recording whose pixmap should be returned
lastModifiedDate - the last modified date or null if the preview image should be downloaded
fileSize - the maximum file size. If this is 0 only the last modified timestamp is returned.
Use null if you do not care about the size.
Returns:
the downloaded preview image or null if the size was exceeded or if an error has occured.
Throws:
IOException - on communication errors
Since:
49 (fallback-from: 17)
See Also:
QUERY_PIXMAP_GET_IF_MODIFIED
MythTV protocol range: [49,-1)
 VersionDateAdditional Version Info
Fallback172005-05-24The function can be can be used with restrictions starting with version 17.
Added492009-10-01Changelog, SVN-Rev.: 22164
Removed-1 

deleteRecording

boolean deleteRecording(IProgramInfo programInfo)
                        throws IOException
Deletes a recording file.

This function marks a recording for deletion, following the existing deletion rules, but does not delete the recording-metadata and -history.

Usage Hint

Use forceDeleteRecording for also deleting the recording metadata.
Use forgetRecording for also deleting the recording history.

Usage example:


    IBackend backend = ...;      // an already connected backend
    IProgramInfo program = ...;  // a previously recorded program
    
    // delete the recording
    if(backend.deleteRecording(program)) {
       System.out.println(String.format(
          "Recording '%s' successfully deleted.",
          program.getTitle(),
       ));
    } 
 

Parameters:
programInfo - the recording to be deleted.
Returns:
true if the backend respond with -1.
Throws:
IOException - on communication errors
Since:
00
See Also:
DELETE_RECORDING
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

deleteRecording

boolean deleteRecording(IProgramInfo programInfo,
                        Boolean forceMetadatDelete,
                        Boolean forgetHistory)
                        throws IOException
Delets a recording file, recording metadata and recording history.

This function marks a recording for deletion, following the existing deletion rules. Optionally this function can delete the metadata of a recording and the recording history.

Protocol Version Hint:

If this function is called under the following conditions ...
... then the following functions are called:

Parameters:
programInfo - the recording
forceMetadatDelete - forces deletion of recording metadata (since 56)
forgetHistory - forces deletion of recording history (since 59)
Returns:
true on success
Throws:
IOException - on communication errors
Since:
41 (fallback-from: 16)
See Also:
DELETE_RECORDING
MythTV protocol range: [41,-1)
 VersionDateAdditional Version Info
Fallback162005-05-03The function can be can be used with restrictions starting with version 16.
Added412008-09-25Changelog, SVN-Rev.: 18419
Changed562009-12-29Changelog, Changelog, MythBuntu-Release: 10.04, MythTV-Release: 0.23, SVN-Rev.: 23028, SVN-Rev.: 23012
Changed592010-08-26Changelog, SVN-Rev.: 25858
Removed-1 

deleteRecording

boolean deleteRecording(Integer channelID,
                        Date recordingStartTime)
                        throws IOException
Deletes a recording-file.

This function marks a recording for deletion, following the existing deletion rules, but does not delete the recording metadata and history.

Usage Hint:

Use forceDeleteRecording for also deleting the recording metadata.
Use forgetRecording for also deleting the recording history.

Protocol Version Hint:

If this function is called prior to 41, than the recording is queried uses queryRecording(Integer, Date), and deleteRecording(IProgramInfo) is called afterwards.

Parameters:
channelID - the channel id of the recording
recordingStartTime - the recording-start-time
Returns:
true on success
Throws:
IOException - on communication errors
Since:
41 (fallback-from: 00)
See Also:
DELETE_RECORDING
MythTV protocol range: [41,-1)
 VersionDateAdditional Version Info
Fallback00 The function can be can be used with restrictions starting with version 0.
Added412008-09-25Changelog, SVN-Rev.: 18419
Removed-1 

deleteRecording

boolean deleteRecording(Integer channelID,
                        Date recordingStartTime,
                        Boolean forceMetadatDelete,
                        Boolean forgetHistory)
                        throws IOException
Delets a recording file, recording metadata and recording history.

This function marks a recording-file for deletion, following the existing deletion rules. Optionally this function can delete the metadata of a recording and the recording history.

Protocol Version Hint:

If this function is called under the following conditions ...
... then the following functions are called:

Parameters:
channelID - the channel id of the recording
recordingStartTime - the recording start time
forceMetadatDelete - forces deletion of recording metadata (since 56)
forgetHistory - forces deletion of recording history (since 59)
Returns:
true on success
Throws:
IOException - on communication errors
Since:
41 (fallback-from: 16)
See Also:
DELETE_RECORDING
MythTV protocol range: [41,-1)
 VersionDateAdditional Version Info
Fallback162005-05-03The function can be can be used with restrictions starting with version 16.
Added412008-09-25Changelog, SVN-Rev.: 18419
Changed562009-12-29Changelog, Changelog, MythBuntu-Release: 10.04, MythTV-Release: 0.23, SVN-Rev.: 23028, SVN-Rev.: 23012
Changed592010-08-26Changelog, SVN-Rev.: 25858
Removed-1 

undeleteRecording

boolean undeleteRecording(IProgramInfo programInfo)
                          throws IOException
Undelets a recording-file.

This function undeletes a previously deleted recording.

Usage Note:

Undeleting a recording only works if the MythTV property AutoExpireInsteadOfDelete is set to 1 in the MythTV settings table.

Parameters:
programInfo - the recording to undelete
Returns:
true on success
Throws:
IOException - on communication errors
Since:
36
See Also:
UNDELETE_RECORDING
MythTV protocol range: [36,-1)
 VersionDateAdditional Version Info
Added362007-09-11Changelog, SVN-Rev.: 14483
Removed-1 

forgetRecording

boolean forgetRecording(IProgramInfo programInfo)
                        throws IOException
Delets recording history.

This function deletes the history of a recording but not the recording itself.
The recording is marked as never duplicates, so it can be re-recorded.

This is similar to the option "Forget Old" on MythWeb.

Usage Hint:

Use forceDeleteRecording to also delete the recording-file and recording-metadata.
Use deleteRecording to only delete the recording.

Parameters:
programInfo - the recording to forget
Returns:
true on success
Throws:
IOException - on communication errors.
Since:
00
See Also:
FORGET_RECORDING
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

forceDeleteRecording

boolean forceDeleteRecording(IProgramInfo programInfo)
                             throws IOException
Deletes a recording-file and recording metadata.

This command forces the backend to delete a recording and its metadata.
See forgetRecording(IProgramInfo) to also delete the recording-history.

Usage Hint:

Use forgetRecording to just delete the recording history.
Use deleteRecording to just delete the recording but not the recording metadata.

Parameters:
programInfo - the recording to delete
Returns:
true on success
Throws:
IOException - on communication errors
Since:
16
See Also:
FORCE_DELETE_RECORDING
MythTV protocol range: [16,-1)
 VersionDateAdditional Version Info
Added162005-05-03Changelog, SVN-Rev.: 6284
Removed-1 

reactivateRecording

boolean reactivateRecording(IProgramInfo programInfo)
                            throws IOException
Deprecated. 19

Reactivates a inactive recording.

This function allows inactive recordings to be reactivated.

This can be used fro things like restarting a program that was stopped or deleted in progress or starting a program after correcting a low disk space or tuner busy condition.

Protocol Version Hint:

Starting with protocol version 19, a recording can be only reactivated by setting the reactivate property in database table oldrecorded.

Throws:
IOException - on communication errors
Since:
05
See Also:
REACTIVATE_RECORDING
MythTV protocol range: [05,19)
 VersionDateAdditional Version Info
Added052004-04-10Changelog, SVN-Rev.: 3503
Removed192005-10-09Changelog, SVN-Rev.: 7427

rescheduleAllRecordings

boolean rescheduleAllRecordings()
                                throws IOException
Force MythTV to reschedule all recordings.

This should be called if you have manually inserted a recording into the record table.

Returns:
true if rescheduling command was received successfully.
Throws:
IOException - on communication errors
Since:
15
See Also:
RESCHEDULE_RECORDINGS
MythTV protocol range: [15,-1)
 VersionDateAdditional Version Info
Added152005-03-23Changelog, MythTV-Release: 0.18, SVN-Rev.: 5833
Removed-1 

rescheduleAllRecordingsAndWait

Boolean rescheduleAllRecordingsAndWait(long timeout,
                                       TimeUnit unit)
                                       throws IOException,
                                              InterruptedException,
                                              IllegalStateException
Forces MythTV to reschedule all recordings and thereafter to wait for an SCHEDULE_CHANGE event.

Usage Note

If the current connection needs to be in the events-listening modes EPlaybackSockEventsMode.NORMAL or EPlaybackSockEventsMode.NON_SYSTEM, otherwise an IllegalStateException is thrown.

Returns:
true if rescheduling command was transmitted and the rescheduling was done successfully, or null if the specified waiting time elapses before the rescheduling process finished.
Throws:
IOException - on communication errors
InterruptedException - if interrupted while waiting.
IllegalStateException - if the connection was not annotated with the proper events-listening-mode.
Since:
15
MythTV protocol range: [15,-1)
 VersionDateAdditional Version Info
Added152005-03-23Changelog, MythTV-Release: 0.18, SVN-Rev.: 5833
Removed-1 

rescheduleRecordings

boolean rescheduleRecordings(Integer recordingId)
                             throws IOException
Deprecated. 73 (fallback-to: -1), use rescheduleRecordingsMatch(Integer, Integer, Integer, Date, String) instead.

Force MythTV to reschedule the given recording.

This should be called if you have manually inserted a recording into the record table.

Parameters:
recordingId - the ID of the recording to reschedule (see IProgramInfo.getRecordingId().
null or -1 forces the backend to reschedule all recordings.
Use 0 if the change isn't specific to a single record entry (e.g. channel or record type priorities)
Returns:
true if rescheduling command was transmitted successfully.
Throws:
IOException - on communication errors
Since:
15
See Also:
RESCHEDULE_RECORDINGS
MythTV protocol range: [15,73)
 VersionDateAdditional Version Info
Added152005-03-23Changelog, MythTV-Release: 0.18, SVN-Rev.: 5833
Removed732012-04-11Changelog
Fallback-1 The function can be can be used with restrictions till version 77.

rescheduleRecordingsMatch

boolean rescheduleRecordingsMatch(Integer recordID,
                                  Integer sourceID,
                                  Integer multiplexID,
                                  Date maxStartTime,
                                  String reason)
                                  throws IOException
Deprecated. 73 (fallback-to: -1), use rescheduleRecordingsMatch(Integer, Integer, Integer, Date, String) instead.

Parameters:
recordID -
sourceID -
multiplexID -
maxStartTime -
reason -
Returns:
Throws:
IOException
Since:
05
See Also:
RESCHEDULE_RECORDINGS
MythTV protocol range: [73,-1)
 VersionDateAdditional Version Info
Fallback152005-03-23The function can be can be used with restrictions starting with version 15.
Added732012-04-11Changelog
Removed-1 

rescheduleRecordingsAndWait

Boolean rescheduleRecordingsAndWait(Integer recordingId,
                                    long timeout,
                                    TimeUnit unit)
                                    throws IOException,
                                           InterruptedException,
                                           IllegalStateException
Deprecated. 73 (fallback-to: -1)

Forces MythTV to reschedule a given recording and waits for an SCHEDULE_CHANGE event.

Usage Note:

If the current connection needs to be in the events-listening modes EPlaybackSockEventsMode.NORMAL or EPlaybackSockEventsMode.NON_SYSTEM, otherwise an IllegalStateException is thrown.

Usage example:


    IBackend backend = ...;      // an already connected backend
    Integer recordingId = ...;   // the id of a modfied scheduling rule
    
    // signal the backend to reschedule the recording and wait for
    // the rescheduling process to finish.
    long timeoutSeconds = 5;
    Boolean rescheduled = backend.rescheduleRecordingsAndWait(recordingId,timeoutSeconds,TimeUnit.SECONDS);
    if(rescheduled == null) {
       System.err.println(String.format(
          "The backend did not finish rescheduling for recording-id %d within %d %s",
          recordingId, Long.valueOf(timeoutSeconds),TimeUnit.SECONDS
       ));
    } else if (!rescheduled.booleanValue()) {
       System.err.println(String.format(
          "Unable to transmit the reschedule-recordings command for recording-id %d to the backend.",
          recordingId
       ));
    } else {
       System.err.println(String.format(
          "Rescheduling for recording-id %d was done successfully.",
          recordingId
       ));
    } 
 

Parameters:
recordingId - the ID of the recording to reschedule (see IProgramInfo.getRecordingId(). null or -1 forces the backend to reschedule all recordings.
Returns:
true if rescheduling command was transmitted and the rescheduling was done successfully, or null if the specified waiting time elapses before the rescheduling process finished.
Throws:
IOException - on communication errors
InterruptedException - if interrupted while waiting.
IllegalStateException - if the connection was not annotated with the proper events-listening-mode.
Since:
05
MythTV protocol range: [15,73)
 VersionDateAdditional Version Info
Added152005-03-23Changelog, MythTV-Release: 0.18, SVN-Rev.: 5833
Removed732012-04-11Changelog
Fallback-1 The function can be can be used with restrictions till version 77.

rescheduleRecordingsMatchAndWait

Boolean rescheduleRecordingsMatchAndWait(Integer recordID,
                                         Integer sourceID,
                                         Integer multiplexID,
                                         Date maxStartTime,
                                         String reason,
                                         long timeout,
                                         TimeUnit unit)
                                         throws IOException,
                                                InterruptedException,
                                                IllegalStateException
Throws:
IOException
InterruptedException
IllegalStateException

getFreeSpaceOverview

IBasicFreeSpace getFreeSpaceOverview()
                                     throws IOException
Gets the free space on the backend.

Protocol Version Hint:

Depending on the used MythTV-protocol, this function uses a different myth-protocol command.
Protocol [min,max) Used function
Min Max
00 17 queryFreeSpace()
17 32 queryFreeSpaceList(boolean)
32 - queryFreeSpaceSummary()

Usage Example:


    // the connected backend
    IBackend backend = ...;
    
    // query the used space
    IBasicFreeSpace freeSpaceOverview = backend.getFreeSpaceOverview();
    System.out.println(String.format(
       "MythTV has used %d space out of %d.", 
       freeSpaceOverview.getTotalSpace(),
       freeSpaceOverview.getUsedSpace()
    ));
 

Returns:
the free space overview
Throws:
IOException - on communication errors
Since:
00
See Also:
queryFreeSpace(), queryFreeSpaceList(boolean), queryFreeSpaceSummary(), QUERY_FREESPACE, QUERY_FREE_SPACE_LIST, QUERY_FREE_SPACE_SUMMARY
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Changed172005-05-24Changelog, SVN-Rev.: 6482
Changed322006-11-30Changelog, SVN-Rev.: 12151
Removed-1 

queryFreeSpace

IFreeSpace queryFreeSpace()
                          throws IOException
Deprecated. 17 (fallback-to: -1), replaced by queryFreeSpaceList and queryFreeSpaceSummary

Geturns the free space on the backend.

Protocol Version Hint:

If this method is called for versions greater or equal to 17, then queryFreeSpaceSummary() is used.

Returns:
the free space
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_FREESPACE
MythTV protocol range: [00,17)
 VersionDateAdditional Version Info
Added00 
Removed172005-05-24Changelog, SVN-Rev.: 6482
Fallback-1 The function can be can be used with restrictions till version 77.

queryFreeSpaceList

IFreeSpaceList queryFreeSpaceList(boolean allhosts)
                                  throws IOException
Returns the free disk space on the connected or on all MythTV backends.

Usage example:


    // query freespace for all hosts
    IFreeSpaceList freeSpaceList = backend.queryFreeSpaceList(true);
    
    // print the summary
    System.out.println(String.format(
       "MythTV has used %s space out of %s used on %d storage groups.",
       EncodingUtils.getFormattedFileSize(freeSpaceList.getUsedSpace()),
       EncodingUtils.getFormattedFileSize(freeSpaceList.getTotalSpace()),
       freeSpaceList.size()
    ));
    
    // print details for each storage group
    for (IFreeSpaceListEntry entry : freeSpaceList) {
       System.out.println(String.format(
          "- %s : %s space out of %s used",
          entry.getDirectories(),
          EncodingUtils.getFormattedFileSize(entry.getUsedSpace()),
          EncodingUtils.getFormattedFileSize(entry.getTotalSpace())
       ));
    }
 
The above example will output, e.g.
 MythTV has used 3,17 GB space out of 3,72 GB used on 2 storage groups.
 - [mythbox:/mnt/data/mythpinky] : 3,14 GB space out of 3,58 GB used
 - [mythbox:/var/lib/mythtv/livetv, mythbox:/var/lib/mythtv/recordings] : 28,00 MB space out of 137,93 MB used
 

Parameters:
allhosts - if the disk space status of all backends should be returned. if this is false only the current connected backend is returned.
Returns:
the disk space for all backends and a additional summary.
Throws:
IOException - on communication errors
Since:
17
See Also:
QUERY_FREE_SPACE_LIST, QUERY_FREE_SPACE
MythTV protocol range: [17,-1)
 VersionDateAdditional Version Info
Added172005-05-24Changelog, SVN-Rev.: 6482
Removed-1 

queryFreeSpaceSummary

IFreeSpaceSummary queryFreeSpaceSummary()
                                        throws IOException
Returns the free space on the connected backend.

Returns:
the free space summary
Throws:
IOException - on communication errors
Since:
32
See Also:
QUERY_FREE_SPACE_SUMMARY
MythTV protocol range: [32,-1)
 VersionDateAdditional Version Info
Added322006-11-30Changelog, SVN-Rev.: 12151
Removed-1 

queryLoad

ILoad queryLoad()
                throws IOException
Queries the current load of the backend.

Returns:
the load information
Throws:
IOException - on communication errors
Since:
15
See Also:
QUERY_LOAD
MythTV protocol range: [15,-1)
 VersionDateAdditional Version Info
Added152005-03-23Changelog, MythTV-Release: 0.18, SVN-Rev.: 5833
Removed-1 

queryUptime

IUptime queryUptime()
                    throws IOException
Queries the uptime of the backend.

Returns:
the uptime-info of the backend
Throws:
IOException - on communication errors
Since:
15
See Also:
QUERY_UPTIME
MythTV protocol range: [15,-1)
 VersionDateAdditional Version Info
Added152005-03-23Changelog, MythTV-Release: 0.18, SVN-Rev.: 5833
Removed-1 

queryMemStats

IMemStats queryMemStats()
                        throws IOException
Queries the current memory state of the backend.

Returns:
the current memory state of the backend
Throws:
IOException - on communication errors
Since:
15
See Also:
QUERY_MEMSTATS
MythTV protocol range: [15,-1)
 VersionDateAdditional Version Info
Added152005-03-23Changelog, MythTV-Release: 0.18, SVN-Rev.: 5833
Removed-1 

queryGuideDataThrough

IGuideDataThrough queryGuideDataThrough()
                                        throws IOException
Queries the guide-date status of the backend.

Usage example:


    IGuideDataThrough data = backend.queryGuideDataThrough();
    
    System.out.println(String.format(
       "There's guide data until %1$tF %1$tT (%2$d days).",
       data.getDate(),
       EncodingUtils.getMinutesDiff(new Date(), data.getDate()) / 60 / 24
    ));
  

Returns:
the guide-data status.
Throws:
IOException - on communication errors
Since:
15
See Also:
QUERY_GUIDEDATATHROUGH
MythTV protocol range: [15,-1)
 VersionDateAdditional Version Info
Added152005-03-23Changelog, MythTV-Release: 0.18, SVN-Rev.: 5833
Removed-1 

queryIsRecording

IRecordingStatus queryIsRecording()
                                  throws IOException
Queries the current recording status of the backend. The status object contains the amount of current-recordings and live-tv-session.

Usage example:


    IBackend backend = ...; // an already connected backend
    
    // query recording status
    IRecordingStatus recordingStatus = backend.queryIsRecording();
    System.out.println(String.format(
       "MythTV has %d active recordings. %d are Live-TV recordings.", 
       recordingStatus.getActiveRecordings(),
       recordingStatus.getLiveTVRecordings()
    ));
  

Returns:
the recording status containing the amount of current-recordings and live-tv-session
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_ISRECORDING
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

queryAllPending

IRecordingsPending queryAllPending()
                                   throws IOException
Gets all programs that will be recorded soon.

Usage Hint:

Use queryAllScheduled to get all scheduled recordings.
Use queryConflicting to get all conflicting recordings.
Use queryRecordings to get all finished recordings.
Use queryExpiring to get all expiring recordings.

Usage Example:


       IBackend backend = ....;     // an already connected backend
       
       // get all pending recordings
       IRecordingsPending pendingRecords = backend.queryAllPending();
       for (IProgramInfo program : pendingRecords) {
          // we are only interrested in recordings with "WILL_RECORD" status
          IProgramRecordingStatus recStatus = program.getRecordingStatus();
          if(recStatus != null && !recStatus.hasStatus(Status.WILL_RECORD)) continue;
          
          // print out the found recodings
          System.out.println(String.format(
             "%1$tF %1$tT - %2$s (%3$s)",
             program.getStartDateTime(),
             program.getTitle(),
             program.getChannelSign()
          ));
       }
  

The above example will output, e.g.

 MythTV has 4 pending records
 2011-04-17 18:10:00 - Die Simpsons (PRO7)
 2011-04-17 20:15:00 - 10.000 BC (PRO7)
 2011-04-18 22:15:00 - Roter Drache (ZDF)
 2011-04-21 20:15:00 - Dr. House (ORF1)
 

Returns:
a list of scheduled programs. If IRecordings.size() returns 0, no scheduled programs were found.
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_GETALLPENDING
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

queryAllScheduled

IRecordingsScheduled queryAllScheduled()
                                       throws IOException
Gets all scheduled recordings.

Usage Hint:

Use queryAllPending to get all pending recordings.
Use queryConflicting to get all conflicting recordings.
Use queryRecordings to get all finished recordings.
Use queryExpiring to get all expiring recordings.

Usage example


 
       IBackend backend = ....;     // an already connected backend
       
       // getting all recording schedules
       IRecordingsScheduled scheduledRecords = backend.queryAllScheduled();
       System.out.println(String.format("MythTV has %d recording schedules:", scheduledRecords.size()));
       System.out.println(String.format(
          "%-35s | %-4s | %-7s | %-15s | %-22s | %-15s",
          "Title","Prio","Channel","Recording Group","Type","Storage Group"
       ));
       
       // print all scheduled recordings
       for (IProgramInfo program : scheduledRecords) {
          System.out.println(String.format(
             "%-35s | %4d | %-7s | %-15s | %-22s | %-15s",
             program.getTitle(),
             program.getRecordingPriority(),
             program.getChannelSign(),
             program.getRecordingGroup(),
             program.getRecordingType(),
             program.getStorageGroup()
          ));		
       }
  

The above example will output, e.g.

 MythTV has 6 recording schedules:
 Title                               | Prio | Channel | Recording Group | Type                   | Storage Group  
 10.000 BC                           |    0 | PRO7    | Default         | 6=> {FIND_ONE_RECORD}  | Default       
 Die Simpsons                        |    0 | PRO7    | Default         | 3=> {CHANNEL_RECORD}   | Default        
 Dr. House                           |    0 | ORF1    | Default         | 5=> {WEEKSLOT_RECORD}  | Default        
 Fantastic Four: Rise of the Silver  |    0 | ORF1    | Default         | 6=> {FIND_ONE_RECORD}  | Default        
 Geisterhaus (Title Suche)           |    0 | PRO7    | Default         | 6=> {FIND_ONE_RECORD}  | Default              
 Stieg Larsson (Title Suche)         |    5 | PRO7    | Default         | 4=> {ALL_RECORD}       | Default 
 

Returns:
a list of scheduled recordings. If IRecordings.size() returns 0, no scheduled programs were found.
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_GETALLSCHEDULED
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

queryExpiring

IRecordingsExpiring queryExpiring()
                                  throws IOException
Gets all programs that will expiring soon.

Usage Hint:

Use queryAllScheduled to get all scheduled recordings.
Use queryAllPending to get all pending recordings.
Use queryConflicting to get all conflicting recordings.
Use queryRecordings to get all finished recordings.

Protocol Version Hint:

If this method is used prior to 23, then queryRecordings() is used and the expiring recordings are filtered using the program-flag-filter.

Usage example:


In the example shown below we fetch the list of expiring recordings, print their names and the sum of disk space used by all expiring recordings.

    // fetch all expiring recordings
    IRecordingsExpiring expiringRecords = backend.queryExpiring();
    long spaceUsed = 0;
    
    // print names of expiring recordings
    System.out.println("Expiring records:");
    for(IProgramInfo program : expiringRecords) {
       spaceUsed += program.getFileSize().longValue();
       System.out.println("- " + program.getFullTitle());
    }
    
    // print disk space used by expiring recordings
    System.out.println(String.format(
       "%s used by %d expiring recordings.",
       EncodingUtils.getFormattedFileSize(spaceUsed),
       expiringRecords.size()
    ));
  

The above example will output, e.g.

 Expiring records:
 - King of Queens - E-Mail für dich
 - King of Queens - Wilde Bullen
 - WALL-E - Der Letzte räumt die Erde auf
 9,82 GB used by 3 expiring recordings.
 

Returns:
a list of expiring programs. If IRecordings.size() returns 0, no expiring programs were found.
Throws:
IOException - on communication errors
Since:
23 (fallback-from: 00)
See Also:
QUERY_GETEXPIRING
MythTV protocol range: [23,-1)
 VersionDateAdditional Version Info
Fallback00 The function can be can be used with restrictions starting with version 0.
Added232006-01-10Changelog, SVN-Rev.: 8553
Removed-1 

queryConflicting

IRecordingsConflicting queryConflicting()
                                        throws IOException
Gets all programs that are in conflict which each other.

Usage Hint:

Use queryAllScheduled to get all scheduled recordings.
Use queryAllPending to get all pending recordings.
Use queryRecordings to get all finished recordings.
Use queryExpiring to get all expiring recordings.

Protocol Version Hint:

Starting with protocol version 57, the backend seens not to return a conflicting recording anymore, without specifying a recording as input parameter. Therefore starting with version 57 we all pending recordings and use a status-filter to get all conflicting recordings.

Usage example:


    // query all conflicting recordings
    IRecordingsConflicting conflictingRecordings = backend.queryConflicting();
    if(!conflictingRecordings.isEmpty()) {
       System.out.println(String.format(
          "%d conflicting records:", 
          conflictingRecordings.size()
       ));
       
       // print all conflicting recordings
       for(IProgramInfo program : conflictingRecordings) {
          System.out.println(String.format(
             "+-- %1$tF %1$tT - %2$s (%3$s)",
             program.getStartDateTime(),
             program.getFullTitle(),
             program.getChannelSign()
          ));
          
          // fetch all recordings the current recording is in conflict with
          IRecordingsConflicting others = backend.queryConflicting(program);
          for(IProgramInfo other : others) {
             System.out.println(String.format(
                "  | %1$tF %1$tT - %2$s (%3$s)",
                other.getStartDateTime(),
                other.getFullTitle(),
                other.getChannelSign()
             ));
          }
       }
    }
  
The above example will output, e.g.
 1 conflicting records:
 +-- 2012-01-10 09:30:00 - Scrubs - Meine Sitcom (PRO7)
   | 2012-01-10 09:30:00 - Mitten im Leben! (RTL)
   | 2012-01-10 09:30:00 - Das Traumhotel (ARD)
 

Returns:
a list of conflicting programs. If IRecordings.size() returns 0, no conflicts were found
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_GETCONFLICTING
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Changed572010-05-16Changelog, Changelog, SVN-Rev.: 24694, SVN-Rev.: 23636
Removed-1 

queryConflicting

IRecordingsConflicting queryConflicting(IProgramInfo programInfo)
                                        throws IOException
Gets all programs that are in conflict with the given program.

Usage Hint:

Use queryConflicting if you need to check all pending recordings for conflicts.

Parameters:
programInfo - the program to check
Returns:
a list of conflicting programs. If IRecordings.size() returns 0, no conflicts were found
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_GETCONFLICTING
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

isActiveBackend

boolean isActiveBackend()
                        throws IOException
Checks if the current backend is active.

This function internally uses queryHostname() to determine the hostname of the connected backend and thereafter calls isActiveBackend(String) with this hostname.

Returns:
true if the given backend is active.
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_IS_ACTIVE_BACKEND
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

isActiveBackend

boolean isActiveBackend(String hostname)
                        throws IOException
Checks if the given backend is active.

This function can be used on master backends to checks the activation status of slave backends, which has been connected to the master using ANN SlaveBackend.

Usage example:


    IBackend backend = ...; // an already connected backend
    
    // the hostname of a backend to check
    String slaveBackendName = "mythbox2";
    
    // checking the is-active status
    boolean isActiveBackend = backend.isActiveBackend(slaveBackendName);
    System.out.println(String.format(
       "The backend '%s' is currently ",
       slaveBackendName,
       (isActiveBackend?"active":"idle")
    ));
 

Parameters:
hostname - the hostname of the backend. This must be the hostname of the mythtv box, using the IP-address seems not to work
Returns:
true if the given backend is active.
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_IS_ACTIVE_BACKEND
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

queryActiveBackends

List<String> queryActiveBackends()
                                 throws IOException
Queries the names of all active backends.

This function returns the names of all currently active backends.

Returns:
a list containing the names of all active backends
Throws:
IOException - on communication errors
Since:
72
See Also:
QUERY_ACTIVE_BACKENDS
MythTV protocol range: [72,-1)
 VersionDateAdditional Version Info
Added722012-01-29Changelog, MythBuntu-Release: 12.04, MythTV-Release: 0.25
Removed-1 

refreshBackend

boolean refreshBackend()
                       throws IOException
Forces the backend to reload the backend settings.

Returns:
true if the backend has reload the backend-settings successfully.
Throws:
IOException - on communication errors
Since:
05
MythTV protocol range: [05,-1)
 VersionDateAdditional Version Info
Added052004-04-10Changelog, SVN-Rev.: 3503
Removed-1 

queryFileExists

IFileStatus queryFileExists(IProgramInfo programInfo)
                            throws IOException
Checks if a recording-file exists for the given program.

Protocol Version Hint:

If this function is called prior to protocol version 49, then function queryCheckFile is used instead.

Parameters:
programInfo - the program for which the file should be searched
Returns:
detailed information about the found file or null
Throws:
IOException - on communication errors
Since:
49 (fallback-from: 00)
See Also:
queryFileExists(String, String), QUERY_FILE_EXISTS
MythTV protocol range: [49,-1)
 VersionDateAdditional Version Info
Fallback00 The function can be can be used with restrictions starting with version 0.
Added492009-10-01Changelog, SVN-Rev.: 22164
Removed-1 

queryFileExists

FileStatus queryFileExists(URI fileUrl)
                           throws IOException
Checks if given file exists on the backend.

This method calls URI.getUserInfo() and URI.getPath() to determine the storage-group and file-name and calls queryFileExists(String, String) afterwards.

Parameters:
fileUrl - the remote file
Returns:
detailed information about the found file or null
Throws:
IOException - on communication errors
Since:
49 (fallback-from: 00)
See Also:
QUERY_FILE_EXISTS, queryFileExists(String, String)
MythTV protocol range: [49,-1)
 VersionDateAdditional Version Info
Fallback00 The function can be can be used with restrictions starting with version 0.
Added492009-10-01Changelog, SVN-Rev.: 22164
Removed-1 

queryFileExists

IFileStatus queryFileExists(String fileName,
                            String storageGroup)
                            throws IOException
Checks if a the named file exists in the named storage group.

Protocol Version Hint:

If this function is called prior to protocol version 49, then function IFileTransfer.isOpen() is used to determine the file exists status.

Usage example:


      IBackend backend = ....;     // an already connected backend
      IProgramInfo program = ....; // a previously recorded program
      
      // query if the preview image exists
      String previewImageName = program.getPreviewImageName();
      IFileStatus fileStatus = backend.queryFileExists(previewImageName,"Default");	
      if (fileStatus.fileExists()) {
         System.out.println("Preview image found: " + fileStatus.getFilePath());
      } else {
         System.out.println("Preview image not found.");
      }
 

Parameters:
fileName - the remote file name
storageGroup - the storage group name, or null to search in the default group
Returns:
detailed information about the found file or null
Throws:
IOException - on communication errors
Since:
49 (fallback-from: 00)
See Also:
QUERY_FILE_EXISTS
MythTV protocol range: [49,-1)
 VersionDateAdditional Version Info
Fallback00 The function can be can be used with restrictions starting with version 0.
Added492009-10-01Changelog, SVN-Rev.: 22164
Removed-1 

queryCheckFile

IFileStatus queryCheckFile(IProgramInfo programInfo,
                           Boolean checkSlaves)
                           throws IOException
Checks if a recording file exists that belongs to the given program.

Usage Hint:

Use queryFileExists to check the existance of a non recording file, e.g. a preview-image or a channel-logo.

Usage Example:


      IBackend backend = ....;       // an already connected backend
      IProgramInfo recording = ....; // a previously recorded program
      
      // check if the file exists
      IFileStatus fileStatus = backend.queryCheckFile(recording);
      if(fileStatus.fileExists()) {
         System.out.println("Recording file found.");
      } else {
         System.out.println("Recording file not found.");
      }
  

Parameters:
programInfo - the given program
checkSlaves - specifies if all slaves should be checked too. (Since 32)
Returns:
detailed information about the found file or null
Throws:
IOException - on communication errors
Since:
00
See Also:
QUERY_CHECKFILE
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Changed322006-11-30Changelog, SVN-Rev.: 12151
Removed-1 

queryFileHash

String queryFileHash(IProgramInfo programInfo)
                     throws IOException
Queries a unique hash-value for the recording-file of the given program.

Parameters:
programInfo - the program referencing a file, for which the file hash should be generated.
Returns:
the generated hash-value, e.g. 75aa72141cd08662
Throws:
IOException - on communication errors
Since:
51
See Also:
queryFileHash(String, String, String), QUERY_FILE_HASH
MythTV protocol range: [51,-1)
 VersionDateAdditional Version Info
Added512009-11-23Changelog, SVN-Rev.: 22892
Removed-1 

queryFileHash

String queryFileHash(URI fileUrl)
                     throws IOException
Queries a unique hash-value for the given remote file.

This method calls URI.getUserInfo(), URI.getHost() and URI.getPath() to determine the storage-group, host-name and file-name and calls queryFileHash(String, String, String) afterwards.

Usage Hint:

To compate the remotely calculated has with a locally generated one, the class OpenSubtitlesHasher could be used.

Parameters:
fileUrl - the remote file
Returns:
the generated hash-value, e.g. 75aa72141cd08662
Throws:
IOException - on communication errors
Since:
51
See Also:
QUERY_FILE_HASH
MythTV protocol range: [51,-1)
 VersionDateAdditional Version Info
Added512009-11-23Changelog, SVN-Rev.: 22892
Removed-1 

queryFileHash

String queryFileHash(String fileName,
                     String storageGroup)
                     throws IOException
Queries a unique hash-value for the given file stored in the given storage group.

Usage Hint:

To compate the remotely calculated has with a locally generated one, the class OpenSubtitlesHasher could be used.

Parameters:
fileName - the remote file name
storageGroup - the storage group name, or null if the default group should be used
Returns:
the generated hash-value, e.g. 75aa72141cd08662
Throws:
IOException - on communication errors
Since:
51
See Also:
QUERY_FILE_HASH
MythTV protocol range: [51,-1)
 VersionDateAdditional Version Info
Added512009-11-23Changelog, SVN-Rev.: 22892
Removed-1 

queryFileHash

String queryFileHash(String fileName,
                     String storageGroup,
                     String hostName)
                     throws IOException
Queries a unique hash-value for the given file stored in the given storage group.

Usage Hint:

To compate the remotely calculated has with a locally generated one, the class OpenSubtitlesHasher could be used.

Parameters:
fileName - the remote file name
storageGroup - the storage group name, or null if the default group should be used
hostName - the name of the backend, storing the file. (since 69). If this is null the current backend will be queried.
Returns:
the generated hash-value, e.g. 75aa72141cd08662
Throws:
IOException - on communication errors
Since:
51
See Also:
QUERY_FILE_HASH
MythTV protocol range: [51,-1)
 VersionDateAdditional Version Info
Added512009-11-23Changelog, SVN-Rev.: 22892
Changed692011-07-11Changelog
Removed-1 

queryStorageGroupFile

IStorageGroupFile queryStorageGroupFile(String hostName,
                                        String storageGroup,
                                        String fileName)
                                        throws IOException
Queries the a single file from the remote storage group.

Protocol Version Hint:

For protocol versions prior to 58 the given file-path must be an absolute path. If the path is not absolute, queryFileExists(String, String) is used to determine the proper absolute path.

Usage example:


     IBackend backend = ...;     // an already connected backend
     IProgramInfo program = ...; // a previously recorded program
     
     // getting all required parameters
     String hostName = program.getHostName();
     String storageGroup = program.getStorageGroup();
     String previewFileName = program.getPreviewImageName();
     
     // query infos about the recording preview image
     IStorageGroupFile previewFile = backend.queryStorageGroupFile(hostName,storageGroup,previewFileName);
     if(previewFile != null) {
        System.out.println(String.format(
           "Preview image path: '%s', last-modified date: '%tF', file-size: '%d'.",
           previewFile.getFilePath(),
           previewFile.getLastModified(),
           previewFile.getSize()
        ));	
     } else {
        System.err.println("Preview image not found");
     }
 

Parameters:
hostName - the backend host to query. if null the result of queryHostname() is used to determine the hostname.
storageGroup - the storage group name. If null Default is used.
fileName - the file name to search for. Till 58 this path must be an absolute path.
Returns:
information about the found file or null
Throws:
IOException - on communication errors
Since:
44
See Also:
QUERY_SG_FILEQUERY
MythTV protocol range: [44,-1)
 VersionDateAdditional Version Info
Added442009-02-12Changelog, SVN-Rev.: 19978
Changed582010-07-17Changelog, Changelog, Changelog, SVN-Rev.: 25362, SVN-Rev.: 25229
Removed-1 

queryStorageGroupFileList

IStorageGroupFileList queryStorageGroupFileList(String hostName,
                                                String storageGroup,
                                                String path)
                                                throws IOException
Queries the a list of files from the remote storage group.

Usage example:


     IBackend backend = ....; // an already connected backend
     
     // query all files stored in the storage-group "Default"
     String hostName = backend.queryHostname();
     IStorageGroupFileList fileList = backend.queryStorageGroupFileList(hostName, "Default", "/", true);
     if(fileList != null) {
         // loop through all found files
         for(IStorageGroupFile file : fileList) {
             // fetch the program info for all found recordings
             final String fileName = file.getFilePath(); // e.g. 1064_20110403184000.mpg			
             if(fileName.matches("\\d+_\\d+\\.mpg")) {
                 // fetch the program info for the recording file
                 IProgramInfo program = backend.queryRecording(fileName);
                 if(program != null) {
                    System.out.println(program);
                 }
             }
         }
     }
  

Parameters:
hostName - the backend host to query. If this is null queryHostname() is used to determine the hostname.
storageGroup - the storage group name. If this is null Default is used.
path - the path to query
Returns:
informations about the found file or null
Throws:
IOException - on communication errors
Since:
44
MythTV protocol range: [44,-1)
 VersionDateAdditional Version Info
Added442009-02-12Changelog, SVN-Rev.: 19978
Removed-1 

queryStorageGroupFileList

IStorageGroupFileList queryStorageGroupFileList(String hostName,
                                                String storageGroup,
                                                String path,
                                                boolean fileNamesOnly)
                                                throws IOException
Queries the a list of files from the remote storage group.

Parameters:
hostName - the backend host to query. If this is null queryHostname() is used to determine the hostname.
storageGroup - the storage group name. If this is null Default is used.
path - the path to query
fileNamesOnly - if only the file names should be returned. (since 49)
Returns:
informations about the found file or null
Throws:
IOException - on communication errors
Since:
44
MythTV protocol range: [44,-1)
 VersionDateAdditional Version Info
Added442009-02-12Changelog, SVN-Rev.: 19978
Changed492009-10-01Changelog, SVN-Rev.: 22164
Removed-1 

queryTimeZone

ITimezone queryTimeZone()
                        throws IOException
Queries the timezone of the backend.

Returns:
the timezone of the backend
Throws:
IOException - on communication errors
Since:
42
See Also:
QUERY_TIME_ZONE
MythTV protocol range: [42,-1)
 VersionDateAdditional Version Info
Added422008-10-07Changelog, SVN-Rev.: 18574
Removed-1 

goToSleep

boolean goToSleep()
                  throws IOException
Signals a slave backend to go to sleep.

Returns:
true if the backend went to sleep or false otherwise
Throws:
IOException - on communication errors
Since:
45
See Also:
GO_TO_SLEEP
MythTV protocol range: [45,-1)
 VersionDateAdditional Version Info
Added452009-05-09Changelog, SVN-Rev.: 20523
Removed-1 

queryHostname

String queryHostname()
                     throws IOException
Gets the hostname of the backend.

Protocol Version Hint:

If this function is called prior to version 50, and the current backend connection was established using an IP-address, this function compares the backend IP adress with the addresses of all recorders, to determine the proper host-name.
If the current backend connection was established using a hostname, the result of getHostName() is returned.

Usage example:


    IBackend backend = ...; // an already connected backend
    
    // query the backends host name
    String backendHostName = backend.queryHostname();
    System.out.println("We are connected to backend: " + backendHostName);
 

Returns:
the hostname of the backend.
Throws:
IOException - on communication errors
Since:
50 (fallback-from: 00)
See Also:
QUERY_HOSTNAME
MythTV protocol range: [50,-1)
 VersionDateAdditional Version Info
Fallback00 The function can be can be used with restrictions starting with version 0.
Added502009-10-02Changelog, MythTV-Release: 0.22, SVN-Rev.: 22170
Removed-1 

blockShutdown

Boolean blockShutdown()
                      throws IOException
Prevents a backend from shutting down.

This function prevents a backend from shutting down until a the next call of allowShutdown().

Returns:
true if the backed has accepted the request
Throws:
IOException - on communication errors
Since:
19
See Also:
BLOCK_SHUTDOWN
MythTV protocol range: [19,-1)
 VersionDateAdditional Version Info
Added192005-10-09Changelog, SVN-Rev.: 7427
Removed-1 

allowShutdown

Boolean allowShutdown()
                      throws IOException
Allows a backend to shutdown.

This function allows a backend to shut down again after a previous call of blockShutdown().

Returns:
true if the backed has accepted the request
Throws:
IOException - on communication errors
Since:
19
See Also:
ALLOW_SHUTDOWN
MythTV protocol range: [19,-1)
 VersionDateAdditional Version Info
Added192005-10-09Changelog, SVN-Rev.: 7427
Removed-1 

shutdownNow

void shutdownNow()
                 throws IOException
Forces a slave backend to shutdown now.

Throws:
IOException - on communication errors
Since:
00
See Also:
SHUTDOWN_NOW
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

querySetting

ISetting querySetting(String hostName,
                      String settingName)
                      throws IOException
Queries the remote host for a specific setting.

The backend will look in the MySQL database table 'settings', and attempt to return the value for the given setting. It seems only settings with the hostname set can be retrieved by this call.

Usage Hints:

Use setSetting to change backend settings.

Parameters:
hostName - the name of the host, the setting belongs to. This can not be null.
settingName - the name of the setting to query
Returns:
the found settings-value or null if the setting was not found.
Throws:
IOException - on communication errors
Since:
17
MythTV protocol range: [17,-1)
 VersionDateAdditional Version Info
Added172005-05-24Changelog, SVN-Rev.: 6482
Removed-1 

setSetting

boolean setSetting(String hostName,
                   String settingName,
                   String settingValue)
                   throws IOException
Sets the given setting on the remote host.

Usage Hints:

Use querySetting to read backend settings.
Use clearSettingsCache to notify the backend about changed settings.

Parameters:
hostName - the name of the host, the setting belongs to
settingName - the name of the setting to change
settingValue - the new setting value
Returns:
true if the setting-value was changed successfully.
Throws:
IOException - on communication errors
Since:
17
See Also:
SET_SETTING
MythTV protocol range: [17,-1)
 VersionDateAdditional Version Info
Added172005-05-24Changelog, SVN-Rev.: 6482
Removed-1 

clearSettingsCache

void clearSettingsCache()
                        throws IOException
Forces the backend to clear its settings cache.

This command should be used after changing any backend settings and forces the backend to reload settings from the database (for example, using MythWeb or Mythtv-setup).

Usage Hints:

Use setSetting to change backend settings.
Use querySetting to read backend settings.

Throws:
IOException - on communication errors
Since:
23
See Also:
BACKEND_MESSAGE_CLEAR_SETTINGS_CACHE
MythTV protocol range: [23,-1)
 VersionDateAdditional Version Info
Added232006-01-10Changelog, SVN-Rev.: 8553
Removed-1 

lockTuner

ITunerInfo lockTuner()
                     throws IOException
Asks the backend to lock the next free tuner.

ATTENTION: This only works if your frontend is on the same machine as one of the available tuners.

Usage Hints:

Use freeTuner to unlock a tuner.

Returns:
informations about the locked tuner
Throws:
IOException - on communication errors
Since:
00
See Also:
lockTuner(Integer), LOCK_TUNER
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

lockTuner

ITunerInfo lockTuner(Integer recorderID)
                     throws IOException
Asks the backend to lock the given tuner.

ATTENTION: This only works if your frontend is on the same machine as the tuner you are trying to lock.

Usage Hints:

Use freeTuner to unlock a tuner.

Parameters:
recorderID - the ID of the recorder to lock
Returns:
informations about the locked tuner
Throws:
IOException - on communication errors
Since:
00
See Also:
LOCK_TUNER
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

freeTuner

boolean freeTuner(Integer recorderID)
                  throws IOException
Frees a previously locked tuner.

Usage Hints:

Use lockTuner to lock a tuner.

Parameters:
recorderID - the ID of the recorder to free
Returns:
true if the recorder was freed successfully or false otherwise
Throws:
IOException - on communication errors
Since:
00
See Also:
FREE_TUNER
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

fillProgramInfo

IProgramInfo fillProgramInfo(IProgramInfo programInfo)
                             throws IOException
Fills in the pathname and file size fields of the given recording.

Parameters:
programInfo - the recording, whose information should be updated.
Returns:
the given program with the path-name and file-size filled in
Throws:
IOException - on communication errors
Since:
00
See Also:
FILL_PROGRAM_INFO
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

fillProgramInfo

IProgramInfo fillProgramInfo(IProgramInfo programInfo,
                             String playBackHostname)
                             throws IOException
Fills in the pathname and file size fields of the given recording.

Calling this function converts the path property from e.g. /var/lib/mythtv/livetv/1004_20120113085933.mpg to myth://192.168.10.207:6543/1004_20120113085933.mpg and additionally updates the file size.

Parameters:
programInfo - the recording, whose information should be updated.
playBackHostname - the name of the playback host
Returns:
the given program with the path-name and file-size filled in
Throws:
IOException - on communication errors
Since:
00
See Also:
FILL_PROGRAM_INFO
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

checkRecording

Integer checkRecording(IProgramInfo programInfo)
                       throws IOException
Checks if the given program is currently being recorded.

This function return the number of the recorder or null, if the program is not being recorded.

Usage Note:

If the backend is not configured properly and therefore returns an empty string in IProgramInfo.getHostName(), this function uses QUERY_REMOTEENCODER_MATCHES_RECORDING to determine the recorder that is recording this program.

Usage example:


    IBackend backend = ...; // an already connected backend
 
    // get all currently running recordings
    IProgramInfoList recordings = backend.queryRecordings(ERecordingsType.Recording);
    for(IProgramInfo recording : recordings) {
      // getting the ID of the recorder recording the program
      Integer recorderId = backend.checkRecording(recording);
      System.out.println(String.format(
         "Recording '%s' (%s) is currently recorded by recorder-ID: %d",
         recording.getTitle(),recording.getChannelSign(),
         recorderId
      ));
    }	
 

Parameters:
programInfo - the given program
Returns:
the recorder-ID or null
Throws:
IOException - on communication errors
Since:
00
See Also:
CHECK_RECORDING
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

stopRecording

Integer stopRecording(IProgramInfo programInfo)
                      throws IOException
Stop a currently active recording.

Protocol Version Hint:

Prior to protocol version 19 the file-name of a recording is renamed, if the recording is stopping prior to the originally intended end time! So if you are plaining to delete the recording-file in a next step you need to update the file information.

Usage example:


    IBackend backend = ...; // an already connected backend
    
    // get all currently running recordings
    IProgramInfoList recordings = backend.queryRecordings(ERecordingsType.Recording);
    for(IProgramInfo recording : recordings) {
      // search for a recording called "Wetter-Panorama"
      if(recording.getTitle().equals("Wetter-Panorama")) {
         // stop the recording
         Integer recorderId = backend.stopRecording(recording);
         System.out.println(String.format(
            "Recording of program '%s' (%s) stopped on recorder %d.",
            recording.getTitle(), recording.getChannelSign(),
            recorderId
         ));
      }
    }
 

Parameters:
programInfo - the recording to be stopped.
Returns:
the recorder-ID where the recording was stopped, or -1 if the recording is not found.
Throws:
IOException - on communication errors.
Since:
00
See Also:
STOP_RECORDING
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Changed192005-10-09Changelog, SVN-Rev.: 7427
Removed-1 

getRecorderForProgram

IRecorderInfo getRecorderForProgram(IProgramInfo programInfo)
                                    throws IOException
Checks if the given program is currently being recorded and returns the recorder-info for the recorder or null, if it is not being recorded.

This method combines checkRecording(IProgramInfo) and getRecorderForNum(int).

Usage example:


    IBackend backend = ...; // an already connected backend
    
    // get all currently running recordings
    IProgramInfoList recordings = backend.queryRecordings(ERecordingsType.Recording);
    for(IProgramInfo recording : recordings) {
       // determine the used recorder
       IRecorderInfo recorder = backend.getRecorderForProgram(recording);
       System.out.println(String.format(
          "Recording '%s' (%s) is currently recorded by: %s",
          recording.getTitle(),recording.getChannelSign(),
          recorder.toString()
       ));
    }
  

Parameters:
programInfo - the given program
Returns:
the recorder-info object or null
Throws:
IOException - on communication errors
Since:
00
See Also:
checkRecording(IProgramInfo), getRecorderForNum(int)
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

queryRecording

IProgramInfo queryRecording(String baseName)
                            throws IOException
Get the ProgramInfo for a single recording specified by the recordings base-name.

Usage Hint:

Use queryRecording(Integer, Date) to query a recording by channel id and rec-start-time.

Parameters:
baseName - the base-name of the recorded program-file, e.g. 1057_20100811133747.mpg.
Returns:
the found recording or null if no matching recording was found
Throws:
IOException - on communication errors
Since:
32
See Also:
QUERY_RECORDING
MythTV protocol range: [32,-1)
 VersionDateAdditional Version Info
Added322006-11-30Changelog, SVN-Rev.: 12151
Removed-1 

queryRecording

IProgramInfo queryRecording(IBasicChannelInfo channel,
                            Date recordingStartTime)
                            throws IOException
Get a single recording by its channel and recording start-time.

This function internally uses IBasicChannelInfo.getChannelID() to get the channel-id of the recording and calls queryRecording(Integer, Date) afterwards.

Usage Hint:

Use queryRecording(String) to query a recording by base name.

Parameters:
channel - the channel of the recording
recordingStartTime - the recording starting-time, e.g. 2010-08-11T13:37:47.
Returns:
the found recording or null if no matching recording was found
Throws:
IOException - on communication errors
Since:
32 (fallback-from: 00)
See Also:
queryRecording(Integer, Date), QUERY_RECORDING
MythTV protocol range: [32,-1)
 VersionDateAdditional Version Info
Fallback00 The function can be can be used with restrictions starting with version 0.
Added322006-11-30Changelog, SVN-Rev.: 12151
Removed-1 

queryRecording

IProgramInfo queryRecording(Integer channelID,
                            Date recordingStartTime)
                            throws IOException
Get a single recording by its channel-id and start-time.

Usage Hint:

Use queryRecording(String) to query a recording by base name.

Protocol Version Hint:

If this function is used for versions prior to 32, then queryRecordings() is called to fetch all recordings, and a program-filter is used afterwards to determine the desired recording.

Parameters:
channelID - the channel-ID, e.g. 1057
recordingStartTime - the recording starting-time, e.g. 2010-08-11T13:37:47
Returns:
the found recording or null if no matching recording was found
Throws:
IOException - on communication errors
Since:
32 (fallback-from: 00)
See Also:
queryRecording(IBasicChannelInfo, Date), QUERY_RECORDING
MythTV protocol range: [32,-1)
 VersionDateAdditional Version Info
Fallback00 The function can be can be used with restrictions starting with version 0.
Added322006-11-30Changelog, SVN-Rev.: 12151
Removed-1 

getBasicChannelInfos

<C extends IBasicChannelInfo> List<C> getBasicChannelInfos()
                                                       throws IOException
Get a list of all available channels on all available recorders.

Protocol Version Hint:

If the current protocol-version is less than 28 an IBasicChannelInfo object is returned, otherwise an IRecorderChannelInfo object is returned.

Type Parameters:
C - the return type. is is either a IBasicChannelInfo or an IRecorderChannelInfo
Returns:
the list of all available channels
Throws:
IOException - on communication errors
Since:
00
See Also:
getChannelInfos(), getRecorders(), IRecorder.getBasicChannelInfos()
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

getChannelInfos

List<IRecorderChannelInfo> getChannelInfos()
                                           throws IOException
Get a list of all available channels on all available recorders.

This method internally uses getRecorders() to get a list of all known recorders and calls IRecorder.getChannelInfos() for all recorders.

Usage Hint:

Use IRecorder.getChannelInfo to get the info for a single channel
Use setChannelInfo to change the info for a single channel.

Usage example:


    IBackend backend = ...; // an already connected backend
 
    List<IRecorderChannelInfo> channels = backend.getChannelInfos();
    for(IRecorderChannelInfo channel : channels) {
       System.out.println(String.format(
          "%2s | %-15s | %s",
          channel.getChannelNumber(), channel.getChannelSign(),
          channel.getChannelName()
       ));
    }
  

The above example will output, e.g.

  1 | PRO7            | Pro7
  2 | SAT.1           | SAT.1
  3 | RTL             | RTL
  4 | RTL2            | RTL 2
  5 | ARD             | ARD
  6 | ZDF             | ZDF
  7 | KABE1           | Kabel 1
  ...
 

Returns:
a list of all available channels
Throws:
IOException - on communication errors
Since:
28
See Also:
getRecorders(), IRecorder.getBasicChannelInfos()
MythTV protocol range: [28,-1)
 VersionDateAdditional Version Info
Added282006-03-28Changelog, SVN-Rev.: 9524
Removed-1 

setChannelInfo

boolean setChannelInfo(String oldChannelNumber,
                       IRecorderChannelInfo channelInfo)
                       throws IOException
Changes detailed infos about the given channel.

Usage Hint:

Use getChannelInfos to get infos about all known channels.
Use IRecorder.getChannelInfo to get the info for a single channel

Parameters:
oldChannelNumber - the old channel number
channelInfo - the new channel info
Returns:
true if channel data was changed successfully.
Throws:
IOException - on communication errors
Since:
28
See Also:
SET_CHANNEL_INFO
MythTV protocol range: [28,-1)
 VersionDateAdditional Version Info
Added282006-03-28Changelog, SVN-Rev.: 9524
Removed-1 

getNextProgramInfos

List<IRecorderNextProgramInfo> getNextProgramInfos(Date date)
                                                   throws IOException
Gets the next programs of all known channels.

This method internally uses getRecorders() to get a list of all known recorders and calls IRecorder.getNextProgramInfos(Date) for all recorders.

Usage example:


    IBackend backend = ...; // an already connected backend
    
    Calendar cal = Calendar.getInstance();
    cal.set(Calendar.HOUR_OF_DAY,20);
    cal.set(Calendar.MINUTE,15);
    
    // fetch the programs of all channels today at 8:15 PM
    List<IRecorderNextProgramInfo> nextPrograms = backend.getNextProgramInfos(cal.getTime());
    for(IRecorderNextProgramInfo nextProgram : nextPrograms) {
       if(!nextProgram.isValid()) continue; // if there is no valid program info for a channel
       
       System.out.println(String.format(
          "%tT | %tT | %-15s | %s",
          nextProgram.getStartDateTime(), nextProgram.getEndDateTime(),
          nextProgram.getChannelSign(), nextProgram.getTitle()
       ));
    }
  

The above example will output, e.g.

 20:15:01 | 23:05:01 | RTL             | Harry Potter und der Stein der Weisen
 20:15:01 | 21:15:01 | SAT.1           | Navy CIS
 20:15:01 | 21:45:01 | ARD             | Tatort
 20:15:01 | 21:45:01 | ZDF             | Rosamunde Pilcher: Englischer Wein
 20:15:01 | 21:45:01 | SWBW            | SonntagAbend
 19:45:01 | 21:15:01 | BR3             | Kreuzwege
 18:25:00 | 20:15:00 | PULS4           | American Pie Presents Band Camp
 20:15:01 | 22:20:01 | PRO7            | Wall-E - Der Letzte räumt die Erde auf
 20:15:01 | 22:55:01 | ATV+            | The Missing
 20:15:01 | 22:10:01 | RTL2            | Ungeklärte Morde - Dem Täter auf der Spur
 20:15:01 | 22:45:01 | ARTE            | Fitzcarraldo
 20:15:01 | 21:00:01 | 3SAT            | Neues aus der Anstalt
 20:15:01 | 21:50:01 | ORF2            | Tatort
 20:15:01 | 21:40:01 | ORF1            | WALL-E - Der Letzte räumt die Erde auf
 20:15:01 | 22:45:01 | VOX             | Das perfekte Promi Dinner
 20:15:01 | 21:15:01 | SUPRT           | Abgefahren - Der lange Weg zum Führerschein
 20:15:01 | 20:45:01 | KABE1           | Two and a Half Men
 

Parameters:
date - the start time
Returns:
the next programs
Throws:
IOException - on communication errors
Since:
00
See Also:
getRecorders(), IRecorder.getNextProgramInfos(Date)
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

getChannelLogoMap

Map<String,String> getChannelLogoMap(IRecorderNextProgramInfo.Props keyProp)
                                     throws IOException
Gets a map containing the path to all channel logos.

This method interally uses getNextProgramInfos(Date) to determine the path to all channel logos.

Parameters:
keyProp - the property of the program-info object that should be used as key for the map.
If this is null IRecorderNextProgramInfo.Props#CHANNEL_ID is used.
Returns:
a map containing all channel logos
Throws:
IOException
Since:
00
MythTV protocol range: [00,-1)
 VersionDateAdditional Version Info
Added00 
Removed-1 

scanVideos

boolean scanVideos()
                   throws IOException
Trigger a scan of all video folders.

Returns:
true if the backend respond with OK
Throws:
IOException - on communication errors
Since:
64
See Also:
SCAN_VIDEOS, IVideoList, IVideoListNoChange, IVideoListChange
MythTV protocol range: [64,-1)
 VersionDateAdditional Version Info
Added642010-11-20Changelog, SVN-Rev.: 27308
Removed-1 

downloadFile

URI downloadFile(URI url,
                 String storageGroup,
                 String fileName)
                 throws IOException
Downloads a file to the backend.

The file is downloaded asynchronously. The backend sends IDownloadFileUpdate and IDownloadFileFinished-events to inform the client about the downloading status.

Usage example:


 
    // allow the client to receive events
    backend.annotateMonitor("mythClient",EPlaybackSockEventsMode.NORMAL);
    Semaphore downloadFinished = new Semaphore(0);
    
    // register as event listeners
    backend.addEventListener(IDownloadFileUpdate.class,new IMythEventListener<IDownloadFileUpdate>() {
       public void fireEvent(IDownloadFileUpdate event) {			
          System.out.println(String.format(
             "%s of %s (%f%%) downloaded from '%s'.",
             EncodingUtils.getFormattedFileSize(event.getBytesReceived()),
             EncodingUtils.getFormattedFileSize(event.getBytesTotal()),
             event.getReceivedPercent(),
             event.getRemoteURI()
          ));
       }
    });
    backend.addEventListener(IDownloadFileFinished.class,new IMythEventListener<IDownloadFileFinished>() {
       public void fireEvent(IDownloadFileFinished event) {				
          System.out.println(String.format(
             "Download of '%s' (%s) finished",					
             event.getRemoteURI(),
             EncodingUtils.getFormattedFileSize(event.getBytesTotal())					
          ));
          
          // signal that the download has finished
          downloadFinished.release();
       }
    });
    
    // force the backend to download the file
    URI remoteFileUri = URI.create("http://upload.wikimedia.org/wikipedia/de/7/7c/ORF-Logo.svg");
    String localFileName = "ORF-Logo.svg";
    
    URI localFileUri = backend.downloadFile(
       remoteFileUri, 
       null, 
       localFileName
    );
    		
    // waiting for the download to finish
    downloadFinished.acquire();
    
    // transfer the file to the client
    IFileTransfer transfer = backend.annotateFileTransfer(localFileUri);		
    File localFile = new File(localFileName);
    transfer.transferTo(localFile);
    transfer.close();
  

Parameters:
url - the remote resource to download
storageGroup - the storage group the remote resource should be stored into
fileName - the name of the file to store the remote file into
Returns:
the URI to the downloaded resource
Throws:
IOException - on communication errors
Since:
58
See Also:
DOWNLOAD_FILE
MythTV protocol range: [58,-1)
 VersionDateAdditional Version Info
Added582010-07-17Changelog, Changelog, Changelog, SVN-Rev.: 25362, SVN-Rev.: 25229
Removed-1 

downloadFileNow

URI downloadFileNow(URI url,
                    String storageGroup,
                    String fileName)
                    throws IOException
Downloads a file to the backend.

The remote file is downloaded synchronously by the backend.

Usage example:


    backend.annotateMonitor();
    
    // force the backend to download the file
    URI remoteFileUri = URI.create("http://upload.wikimedia.org/wikipedia/de/7/7c/ORF-Logo.svg");
    String localFileName = "ORF-Logo.svg";
    
    URI localFileUri = backend.downloadFileNow(
       remoteFileUri, 
       null, 
       localFileName
    );
    
    // transfer the file to the client
    IFileTransfer transfer = backend.annotateFileTransfer(localFileUri);		
    File localFile = new File(localFileName);
    transfer.transferTo(localFile);
    transfer.close();
  

Parameters:
url - the remote resource to download
storageGroup - the storage group the remote resource should be stored into
fileName - the name of the file to store the remote file into
Returns:
the URI to the downloaded resource
Throws:
IOException - on communication errors
Since:
58
See Also:
DOWNLOAD_FILE_NOW
MythTV protocol range: [58,-1)
 VersionDateAdditional Version Info
Added582010-07-17Changelog, Changelog, Changelog, SVN-Rev.: 25362, SVN-Rev.: 25229
Removed-1 

deleteFile

boolean deleteFile(URI fileUrl)
                   throws IOException
Delete a remote file.

This method calls URI.getUserInfo() and URI.getPath() to determine the storage-group and file-name and calls deleteFile(String, String) afterwards.

Usage Hint:

Use deleteRecording(IProgramInfo) if a recording should be deleted.

Parameters:
fileUrl - the url to the remote file
Returns:
true if the file was deleted successfully, or false otherwise
Throws:
IOException - on communication errors
Since:
46
See Also:
DELETE_FILE
MythTV protocol range: [46,-1)
 VersionDateAdditional Version Info
Added462009-08-08Changelog, SVN-Rev.: 21158
Removed-1 

deleteFile

boolean deleteFile(String fileName,
                   String storageGroup)
                   throws IOException
Delete a remote file.

Usage Hint:

Use deleteRecording if a recording should be deleted.

Parameters:
fileName - the name of the remote file
storageGroup - the storage-group the remote file is stored in.
Returns:
true if the file was deleted successfully, or false otherwise
Throws:
IOException - on communication errors
Since:
46
See Also:
DELETE_FILE
MythTV protocol range: [46,-1)
 VersionDateAdditional Version Info
Added462009-08-08Changelog, SVN-Rev.: 21158
Removed-1 

queryBookmark

Long queryBookmark(IProgramInfo program)
                   throws IOException
Queries the bookmark position for a given recording.

This function uses IProgramInfo.getChannelID() and IProgramInfo.getRecordingStartTime() to determine the channel-id and recording-start-time and calls queryBookmark(Integer, Date) afterwards.

Usage Hint:

Use setBookmark to set the bookmark of a recording.

Usage example:


   // getting a list of recordings
   IProgramInfoList recordings = backend.queryRecordings();
   
   // print the bookmark position for all recordings with bookmarks
   System.out.println("Rercordings with bookmarks: ");
   for(IProgramInfo recording : recordings) {
      // determine if the recording has a bookmark set
      boolean hasBookmark = recording.getProgramFlags().isSet(Flags.FL_BOOKMARK);
      if(hasBookmark) {
         // query the bookmark position
         Long bookmark = backend.queryBookmark(recording);
         System.out.println(String.format(
            "- %s (bookmark: frame %d)",
            recording.getFullTitle(),
            bookmark
         ));
      }
   }
 

Parameters:
program - the recording
Returns:
the bookmark position in frames
Throws:
IOException - on communication errors
Since:
17
See Also:
QUERY_BOOKMARK
MythTV protocol range: [17,-1)
 VersionDateAdditional Version Info
Added172005-05-24Changelog, SVN-Rev.: 6482
Removed-1 

queryBookmark

Long queryBookmark(Integer channelID,
                   Date recordingStartTime)
                   throws IOException
Queries the bookmark position for a given recording.

Usage Hint:

Use setBookmark to set the bookmark of a recording.

Parameters:
channelID - the channel-ID of the recording
recordingStartTime - the recording-start-time of the recording
Returns:
the bookmark position in frames
Throws:
IOException - on communication errors
Since:
17
See Also:
QUERY_BOOKMARK
MythTV protocol range: [17,-1)
 VersionDateAdditional Version Info
Added172005-05-24Changelog, SVN-Rev.: 6482
Removed-1 

setBookmark

boolean setBookmark(IProgramInfo recording,
                    Long bookmarkPosition)
                    throws IOException
Sets the bookmark position for the given recording.

This function uses IProgramInfo.getChannelID() and IProgramInfo.getRecordingStartTime() to determine the channel-id and recording-start-time of the recording and calls setBookmark(Integer, Date, Long) afterwards.

Usage Hint:

Use queryBookmark to get the bookmark of a recording.

Parameters:
recording - the recording for which the bookmark should be set
bookmarkPosition - the bookmark position in frames
Returns:
true if the bookmark was set or false otherwise
Throws:
IOException - on communication errors
Since:
17
See Also:
SET_BOOKMARK
MythTV protocol range: [17,-1)
 VersionDateAdditional Version Info
Added172005-05-24Changelog, SVN-Rev.: 6482
Removed-1 

setBookmark

boolean setBookmark(Integer channelID,
                    Date recordingStartTime,
                    Long bookmarkPosition)
                    throws IOException
Sets the bookmark position for the given recording.

Usage Hint:

Use queryBookmark to get the bookmark of a recording.

Parameters:
channelID - the channel ID of the recording
recordingStartTime - the recording-start-time
bookmarkPosition - the bookmark position in frames
Returns:
true if the bookmark was set or false otherwise
Throws:
IOException - on communication errors
Since:
17
See Also:
SET_BOOKMARK
MythTV protocol range: [17,-1)
 VersionDateAdditional Version Info
Added172005-05-24Changelog, SVN-Rev.: 6482
Removed-1 

queueTranscode

boolean queueTranscode(IProgramInfo recording)
                       throws IOException
Deprecated. 23

Enqueues the recording for transcoding.

Usage Hint:

Use queueTranscodeStop to stop transcoding of a recording.

Parameters:
recording - the recording to transcode
Returns:
true on success
Throws:
IOException - on communication errors
See Also:
QUEUE_TRANSCODE
MythTV protocol range: [00,23)
 VersionDateAdditional Version Info
Added00 
Removed232006-01-10Changelog, SVN-Rev.: 8553

queueTranscodeCutlist

boolean queueTranscodeCutlist(IProgramInfo recording)
                              throws IOException
Deprecated. 23

Enqueues the recording for transcoding and cutlist processing.

Usage Hint:

Use queueTranscodeStop to stop transcoding of a recording.

Parameters:
recording - the recording to transcode
Returns:
true on success
Throws:
IOException - on communication errors
See Also:
QUEUE_TRANSCODE_CUTLIST
MythTV protocol range: [00,23)
 VersionDateAdditional Version Info
Added00 
Removed232006-01-10Changelog, SVN-Rev.: 8553

queueTranscodeStop

boolean queueTranscodeStop(IProgramInfo recording)
                           throws IOException
Deprecated. 23

Stops transcoding of a recording

Usage Hint:

Use queueTranscode to start transcoding of a recording.
Use queueTranscodeCutlist to start transcoding and cutlist processing of a recording.

Parameters:
recording - the recording for which transcoding should be stopped
Returns:
true on success
Throws:
IOException - on communication errors
See Also:
QUEUE_TRANSCODE_STOP
MythTV protocol range: [00,23)
 VersionDateAdditional Version Info
Added00 
Removed232006-01-10Changelog, SVN-Rev.: 8553

addEventPacketListener

void addEventPacketListener(IMythEventPacketListener listener)
Registers a new event listener.

Parameters:
listener - the event listener

removeEventPacketListener

void removeEventPacketListener(IMythEventPacketListener listener)
Unregisters a event listener.

Parameters:
listener - the event listener

addEventListener

<Event extends IMythEvent<?>> void addEventListener(Class<Event> eventClass,
                                                    IMythEventListener<Event> listener)

removeEventListener

<Event extends IMythEvent<?>> void removeEventListener(Class<Event> eventClass,
                                                       IMythEventListener<Event> listener)


Copyright © 2008-2013. All Rights Reserved.