Description

Technical Preview:: This interface is a TECHNICAL PREVIEW, it may change. The ToiMediaConsumer can be used to fetch data from a media stream using ToiMediaSession without allocating media decoder or recorder resources.

See also:: ToiMediaService

import "ToiMediaConsumer.idl";

Inheritance diagram for ToiMediaConsumer:

Public Member Functions
TToiState	getState ()
ToiMediaSession::TToiSessionId	getSessionId () raises (TToiSessionViolationException)
string	getUrl () raises (TToiSessionViolationException)
void	open (in string url) raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException)
void	close () raises (TToiSessionViolationException, TToiUnavailableException)
void	consume () raises (TToiSessionViolationException, TToiOperationNotSupportedException, TToiUnavailableException)
void	releaseInstance ()
Public Attributes
Events
const long	ON_STATE_CHANGED = 1300
TToiState
const TToiState	STATE_IDLE = 0
const TToiState	STATE_CONNECTING = 1
const TToiState	STATE_PAUSED = 2
const TToiState	STATE_CONSUMING = 3
const TToiState	STATE_FAILED = 4
Public Types
typedef long	TToiState

Member Typedef Documentation

typedef long ToiMediaConsumer::TToiState

State identifier used to identify the media consumer state.

Member Function Documentation

void ToiMediaConsumer::close ( ) raises (TToiSessionViolationException, TToiUnavailableException)

This function ends the current session by disconnecting from the media source. For example, if the source is a video server it ends the server session and disconnects, or if the source is a multicast channel it leaves that multicast group. If this function returns successfully, the consumer state has changed to ToiMediaConsumer::STATE_IDLE. If an exception is raised, the consumer state is unaffected.

Exceptions:

TToiSessionViolationException	If the consumer is in idle state a session violation exception is raised.
TToiUnavailableException	TToiUnavailableException is raised if the consumer is temporarily unavailable due to platform resource management.

See also:: ToiMediaConsumer::open(), TToiState

void ToiMediaConsumer::consume ( ) raises (TToiSessionViolationException, TToiOperationNotSupportedException, TToiUnavailableException)

This function starts consuming the stream. If this function returns successfully, the consumer state has changed to ToiMediaConsumer::STATE_CONSUMING. If an exception is raised, the consumer state is unaffected.

Exceptions:

TToiSessionViolationException	If the consumer is in ToiMediaConsumer::STATE_IDLE a session violation exception is raised.
TToiOperationNotSupportedException	If the consumer is in a state is which this operation is not supported, an operation not supported exception is raised. This is the case when in ToiMediaConsumer::STATE_FAILED, for example.
TToiUnavailableException	TToiUnavailableException is raised if the consumer is temporarily unavailable due to platform resource management.

See also:: ToiMediaConsumer::open(), TToiState

ToiMediaSession::TToiSessionId ToiMediaConsumer::getSessionId ( ) raises (TToiSessionViolationException)

Returns the session identifier. This identifier can be used to open a session object with ToiMediaService::openSession().

Return values:

id	The session identifier.

Exceptions:

TToiSessionViolationException If the consumer is in ToiMediaConsumer::STATE_IDLE a session violation exception is raised.

TToiState ToiMediaConsumer::getState ( )

Returns the current state of the media consumer instance.

Return values:

state The current consumer state.

string ToiMediaConsumer::getUrl ( ) raises (TToiSessionViolationException)

Returns the URL for the media stream.

Return values:

url	The URL for the media stream.

Exceptions:

TToiSessionViolationException If the consumer is in ToiMediaConsumer::STATE_IDLE a session violation exception is raised.

void ToiMediaConsumer::open ( in string url ) raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException)

This function starts a new stream session by trying to establish a connection to a media source. If this function returns successfully, the consumer state has changed to ToiMediaConsumer::STATE_CONNECTING. If an exception is raised, the consumer state is unaffected.

Depending on the success of the connection attempt to the media source, the consumer will make a second state transition to either ToiMediaConsumer::STATE_PAUSED or ToiMediaConsumer::STATE_FAILED, on success and failure, respectively. In any respect, the application will be notified about this event by a call to its ToiMediaConsumerStateChangedEvent function.

Parameters:

url	The URL identifying the media source. The URL string may contain additional parameter information in accordance to the extended URL format.

Exceptions:

TToiSessionViolationException	If the consumer is not in idle state at the time of the call to ToiMediaConsumer::open(), a session violation exception is raised. OR When query parameter "SessionMode=AttachOnly" is specified in the URL, if no matching session is found with the specified URL in running state (ToiMediaSession::TToiState::STATE_RUNNING), a session violation exception is raised.
TToiInvalidArgumentException	If the URL given as argument does not follow the extended URL format, an invalid argument exception is raised.
TToiUnavailableException	TToiUnavailableException is raised if the consumer is temporarily unavailable due to platform resource management.

See also:: ToiMediaConsumer::close(), TToiState

void ToiMediaConsumer::releaseInstance ( )

This function releases the resources used by this instance. When this function returns all observers has also been released.

Member Data Documentation

const long ToiMediaConsumer::ON_STATE_CHANGED = 1300

This is an Event identifier for ToiMediaConsumerStateChangedEvent.

This constant can also be accessed from toi.consts.ToiMediaConsumer.ON_STATE_CHANGED.

const TToiState ToiMediaConsumer::STATE_CONNECTING = 1

In ToiMediaConsumer::STATE_CONNECTING the media consumer has an active session and is in the process of establishing a connection to a media stream source. The media consumer will leave this state automatically and enter ToiMediaConsumer::STATE_PAUSED when it has successfully established the connection to the stream source. If the media consumer decides it cannot connect, it will enter ToiMediaConsumer::STATE_FAILED instead. If the application is not interrested in knowing when the consumer has connected, it may call ToiMediaConsumer::consume() to set the player in ToiMediaConsumer::STATE_CONSUMING directly. The application may end the session by calling ToiMediaConsumer::close(), which makes the consumer go to ToiMediaConsumer::STATE_IDLE.

This constant can also be accessed from toi.consts.ToiMediaConsumer.STATE_CONNECTING.

const TToiState ToiMediaConsumer::STATE_CONSUMING = 3

In ToiMediaConsumer::STATE_CONSUMING the media consumer has a connection to a media source and consumes the stream from that source. The application may end the session by calling ToiMediaConsumer::close(), which makes the consumer go to ToiMediaConsumer::STATE_IDLE. If an error occurs with the stream severe enough for the consumer to determine it cannot continue, the consumer will go to ToiMediaConsumer::STATE_FAILED.

This constant can also be accessed from toi.consts.ToiMediaConsumer.STATE_CONSUMING.

const TToiState ToiMediaConsumer::STATE_FAILED = 4

In ToiMediaConsumer::STATE_FAILED the media consumer may or may not have a connection to a media source but the process of getting the stream from that source has failed in some fatal way. The media consumer will only leave ToiMediaConsumer::STATE_FAILED on a call by the application to ToiMediaConsumer::close().

This constant can also be accessed from toi.consts.ToiMediaConsumer.STATE_FAILED.

const TToiState ToiMediaConsumer::STATE_IDLE = 0

In ToiMediaConsumer::STATE_IDLE there is no active session. The media consumer does not handle a stream, and consequently has no connection to a media stream source. All functions requiring a session will raise a TToiSessionViolationException in ToiMediaConsumer::STATE_IDLE. The media consumer will only leave ToiMediaConsumer::STATE_IDLE on a successful call to ToiMediaConsumer::open().

This constant can also be accessed from toi.consts.ToiMediaConsumer.STATE_IDLE.

const TToiState ToiMediaConsumer::STATE_PAUSED = 2

In ToiMediaConsumer::STATE_PAUSED the media consumer has a connection to a media source but will not start consuming until ToiMediaConsumer::consume() is called, which changes the state to ToiMediaConsumer::STATE_CONSUMING. The application may also end the session by calling ToiMediaConsumer::close(), which makes the consumer go to ToiMediaConsumer::STATE_IDLE. If an error occurs with the stream severe enough for the consumer to determine it cannot continue, the consumer will go to ToiMediaConsumer::STATE_FAILED.

This constant can also be accessed from toi.consts.ToiMediaConsumer.STATE_PAUSED.

Description

Public Member Functions

Public Attributes

Public Types

Member Typedef Documentation

Member Function Documentation

Member Data Documentation