io.humble.video.customio

Interface IURLProtocolHandler

All Known Implementing Classes:

DataInputOutputHandler, FileProtocolHandler, InputOutputStreamHandler, NullProtocolHandler, ReadableWritableChannelHandler

public interface IURLProtocolHandler

Interface that Humble Video native code calls back to for each URL. It is assumed a new Protocol object is made per URL being read or written to.

You must implement this interface if you want to register a new type of URLProtocolHandler with the URLProtocolManager.

If you throw an exception in your implementation of this handler during a callback from within Humble Video, we will assume your method returned -1 while still in native code. Once the stack unwinds back into Java we will re-raise your exception.

Author:

aclarke

See Also:

FileProtocolHandler, NullProtocolHandler

Field Summary

Fields

Modifier and Type	Field and Description
static int	SEEK_CUR A flag for seek(long, int).
static int	SEEK_END A flag for seek(long, int).
static int	SEEK_SET A flag for seek(long, int).
static int	SEEK_SIZE A flag for seek(long, int).
static int	URL_RDONLY_MODE Open the file in Read Only mode.
static int	URL_RDWR Implement the file in Read/Write mode.
static int	URL_WRONLY_MODE Open the file in Write Only mode.

Method Summary

Modifier and Type	Method and Description
int	close() A request to close() from FFMPEG
boolean	isStreamed(String url, int flags) Special callback made by Humble Video in order to determine if your stream supports streaming.
int	open(String url, int flags) This method gets called by FFMPEG when it opens a file.
int	read(byte[] buf, int size) This method gets called by FFMPEG when it tries to read data.
long	seek(long offset, int whence) A request from FFMPEG to seek to a position in the stream.
int	write(byte[] buf, int size) This method gets called by FFMPEG when it tries to write data.

Field Detail

SEEK_SET

static final int SEEK_SET

A flag for seek(long, int). Denotes positions relative to start of file.

See Also:

Constant Field Values

SEEK_CUR

static final int SEEK_CUR

A flag for seek(long, int). Denotes positions relative to where the current file pointer is.

See Also:

Constant Field Values

SEEK_END

static final int SEEK_END

A flag for seek(long, int). Denotes positions relative to the end of file.

See Also:

Constant Field Values

SEEK_SIZE

static final int SEEK_SIZE

A flag for seek(long, int). A special hack of FFMPEG, denotes you want to find the total size of the file.

See Also:

Constant Field Values

URL_RDONLY_MODE

static final int URL_RDONLY_MODE

Open the file in Read Only mode.

See Also:

Constant Field Values

URL_WRONLY_MODE

static final int URL_WRONLY_MODE

Open the file in Write Only mode.

See Also:

Constant Field Values

URL_RDWR

static final int URL_RDWR

Implement the file in Read/Write mode.

See Also:

Constant Field Values

Method Detail

open

int open(String url,
         int flags)

This method gets called by FFMPEG when it opens a file.

Parameters:

url - The URL to open

flags - The flags (e.g. URL_RDONLY_MODE)

Returns:

>= 0 for success; -1 for error.

read

int read(byte[] buf,
         int size)

This method gets called by FFMPEG when it tries to read data.

For non-blocking IO, return: io.humble.video.Error#typeToErrorNumber(io.humble.video.Error.Type) pass in io.humble.video.Error.Type#ERROR_AGAIN for the error type. This returns the platform specific number for EAGAIN on your platform signaling that callers should try again later.

Alternately implementors may block until data is returning, but they should then respect the Thread.isInterrupted() setting.

Parameters:

buf - The buffer to write your data to.

size - The number of bytes in buf data available for you to write the data that FFMPEG will read.

Returns:

0 for end of file, else number of bytes you wrote to the buffer, or -1 if error.

write

int write(byte[] buf,
          int size)

This method gets called by FFMPEG when it tries to write data.

For non-blocking IO, return: io.humble.video.Error#typeToErrorNumber(io.humble.video.Error.Type) pass in io.humble.video.Error.Type#ERROR_AGAIN for the error type. This returns the platform specific number for EAGAIN on your platform signaling that callers should try again later.

Alternately implementators may block until data is returning, but they should then respect the Thread.isInterrupted() setting.

Parameters:

buf - The data you should write.

size - The number of bytes in buf.

Returns:

0 for end of file, else number of bytes you read from buf, or -1 if error.

seek

long seek(long offset,
          int whence)

A request from FFMPEG to seek to a position in the stream.

Parameters:

offset - The offset in bytes.

whence - Where that offset is relative to. Follow the C stdlib fseek() conventions EXCEPT SEEK_SIZE should return back the size of the stream in bytes if known without adjusting the seek pointer.

Returns:

-1 if not supported, else the position relative to whence

close

int close()

A request to close() from FFMPEG

Returns:

-1 on error; else >= 0

isStreamed

boolean isStreamed(String url,
                   int flags)

Special callback made by Humble Video in order to determine if your stream supports streaming.

If this method returns true, Humble Video will assume it cannot seek backwards in this container.

This has one main practical consequence. When writing it means certain container formats (e.g. the MOV container) will not be usable as it requires seeking back to the start of a file to write MOV required header information once the entire file has been encoded.

But if your medium is streaming, you'll want to return true for this, and then FFMPEG will not attempt to seek back in time.

Parameters:

url - The URL that would be passed to open(String, int)

flags - The flags that would be passed to open(String, int)

Returns:

true if you can stream that URL; false if not.