org.jmythapi.protocol.response
Interface IFileTransfer

All Superinterfaces:

Cloneable, Closeable, IPropertyAware<IFileTransfer.Props>, ITransferable<IFileTransfer.Props>, IVersionable

All Known Implementing Classes:

FileTransfer

public interface IFileTransfer
extends ITransferable<IFileTransfer.Props>

An interface to transfer files from and to a backend.

This interface represents the response to a IBackend.annotateFileTransfer request.
This interface is property-aware. See the properties-list for all properties of this interface.

Request 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();
 

Response example:

Protocol version less than 66:

<0>STATUS: OK | <1>SOCKET_ID: 38 | <2>FILESIZE1: 0 | <3>FILESIZE2: 86681

Protocol version 66 example:

<0>STATUS: OK | <1>SOCKET_ID: 38 | <2>FILESIZE: 86681

See Also:

IBackend.annotateFileTransfer(IProgramInfo), ANN_FILE_TRANSFER

Nested Class Summary

static class

IFileTransfer.Props The properties of an IFileTransfer response.

Nested classes/interfaces inherited from interface org.jmythapi.protocol.response.ITransferable

ITransferable.Seek

Method Summary

boolean	done() Closes the file transfer connection.
long	getFileSize() Gets the current file size.
InputStream	getInputStream() Gets an input stream to read the file data.
InputStream	getInputStream(int chunkSize) Gets an input stream to read the file data.
int	getSocketID() Gets the file transfer socket id.
String	getStatus() Gets the file transfer status.
boolean	isOpen() Queries whether a file socket is currently open.
int	readBlock(byte[] buffer, int requestedSize) Requests a new block from backend and reads the block.
int	readData(byte[] buffer, int reportedLength) Reads the given amount of data from the backend.
boolean	reopen(String filename) Reopens the remote file.
int	requestBlock(int size) Requests data from the backend.
long	seek(long currentPos, long newPos, ITransferable.Seek whence) This command wraps the file "seek" function.
boolean	setTimeout(boolean fast) Sets the timout mode.
void	transferTo(File target) Copies the remote file into the local file.
void	transferTo(OutputStream target) Copies the remote file into the given output stream.
boolean	updateFileSize() Updates the file information of the file-transfer object.

Methods inherited from interface org.jmythapi.protocol.response.ITransferable

close

Methods inherited from interface org.jmythapi.IVersionable

getVersionNr

Methods inherited from interface org.jmythapi.IPropertyAware

getProperties, getProperty, getPropertyClass, getPropertyCount, getPropertyIndex, getPropertyMap, getPropertyValue, getPropertyValue, getPropertyValueObject, getPropertyValues, setPropertyValue, setPropertyValue, setPropertyValueObject

Method Detail

getStatus

String getStatus()

Gets the file transfer status.

Returns:

OK or ERROR

getSocketID

int getSocketID()

Gets the file transfer socket id.

Returns:

the socket id

getFileSize

long getFileSize()

Gets the current file size.

For a in progress recording this file size may increase.
Use updateFileSize() to update the file size.

Returns:

the current file size

updateFileSize

boolean updateFileSize()
                       throws IOException

Updates the file information of the file-transfer object.

If the transfer object was initiated from an IProgramInfo object (see IBackend.annotateFileTransfer(IProgramInfo)), then this function uses IMythCommand.FILL_PROGRAM_INFO to determine the new file size.

If the transfer object was initialized using a file name, and the current protocol version is greater or equal 44, then IMythCommand.QUERY_SG_FILEQUERY is used to determine the new file size. But this method may fail if the requested file is not stored in a file group, e.g. a channel icon.

Returns:

true on success.

Throws:

IOException - on communication errors

readBlock

int readBlock(byte[] buffer,
              int requestedSize)
              throws IOException

Requests a new block from backend and reads the block.

This method combines requestBlock(int) and readData(byte[], int).

Specified by:

readBlock in interface ITransferable<IFileTransfer.Props>

Parameters:

buffer - the byte buffer to fill with data

requestedSize - the amount of bytes to read

Returns:

the read byte count

Throws:

IOException - on communication errors

requestBlock

int requestBlock(int size)
                 throws IOException

Requests data from the backend.

Parameters:

size - the amount of bytes to request.

Returns:

the amount of returned bytes. this may be less than the requested size.

Throws:

IOException - on communication errors

readData

int readData(byte[] buffer,
             int reportedLength)
             throws IOException

Reads the given amount of data from the backend.

Parameters:

buffer - the buffer to fill with data

reportedLength - the amount of data to read

Returns:

the actually amount of read data

Throws:

IOException - on communication errors

seek

long seek(long currentPos,
          long newPos,
          ITransferable.Seek whence)
          throws IOException

This command wraps the file "seek" function.

The pos and curpos fields are combined into a larger "long long" data type. This returns two values, a split "long long" value for the result.

Specified by:

seek in interface ITransferable<IFileTransfer.Props>

Parameters:

currentPos - the current position

newPos - the new position

whence - the seek mode

Returns:

the new position

Throws:

IOException - on communication errors

See Also:

QUERY_FILETRANSFER_SEEK

isOpen

boolean isOpen()
               throws IOException

Queries whether a file socket is currently open.

Specified by:

isOpen in interface ITransferable<IFileTransfer.Props>

Returns:

true if the socket is open.

Throws:

IOException - on communication errors

setTimeout

boolean setTimeout(boolean fast)
                   throws IOException

Sets the timout mode.

This command sets whether reading from a file should have a fast or slow timeout.
Slow timeouts are used for live TV ring buffers, and is three seconds. Fast timeouts are used for static files, and are 0.12 seconds.

Throws:

IOException

Since:

28

See Also:

QUERY_FILETRANSFER_SET_TIMEOUT

done

boolean done()
             throws IOException

Closes the file transfer connection.

Specified by:

done in interface ITransferable<IFileTransfer.Props>

Returns:

true on success.

Throws:

IOException - on communication errors

See Also:

QUERY_FILETRANSFER_DONE

reopen

boolean reopen(String filename)
               throws IOException

Reopens the remote file.

Throws:

IOException

Since:

70

See Also:

QUERY_FILETRANSFER_REOPEN

transferTo

void transferTo(File target)
                throws IOException

Copies the remote file into the local file.

This function transfers the full remote file into the specified target file.

Parameters:

target - the file to write data to.

Throws:

IOException - on communication errors

transferTo

void transferTo(OutputStream target)
                throws IOException

Copies the remote file into the given output stream.

This function transfers the full remote file into the specified target stream.

Parameters:

target - the output stream

Throws:

IOException - on communication errors

getInputStream

InputStream getInputStream()
                           throws IOException

Gets an input stream to read the file data.

This function creates an input-stream that can be used to read the data of this file-transfer object.

Returns:

an input stream to read the file

Throws:

IOException - on communication errors

getInputStream

InputStream getInputStream(int chunkSize)
                           throws IOException

Gets an input stream to read the file data.

This function creates an input-stream that can be used to read the data of this file-transfer object.
* The maximum size of the data chunks that should be fetched by the stream can be spezified.

Parameters:

chunkSize - the maximum size of the data chunks to fetch

Returns:

an input stream to read data

Throws:

IOException - on communication errors