IMediaConsumer Interface Reference


Description

This internal interface provides methods for platform services that don't have an application id.

import "IMediaConsumer.idl";

List of all members.

Public Member Functions

void RegisterObserverInternal (in string address) raises (TToiInvalidArgumentException)
void GetState (out TToiState state)
void GetSessionId (out IToiMediaSession::TToiSessionId id) raises (TToiSessionViolationException)
void GetUrl (out string url) raises (TToiSessionViolationException)
void Open (in string url) raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException)
void Close () raises (TToiSessionViolationException, TToiUnavailableException)
void Consume () raises (TToiSessionViolationException, TToiOperationNotSupportedException, TToiUnavailableException)
void ReleaseInstance ()
void RegisterObserver (in IToiApplicationService::TToiApplicationId applicationId, in string address) raises (TToiInvalidArgumentException)
void ReleaseObserver (in string address) raises (TToiInvalidArgumentException)

Public Types

enum  TToiState {
  STATE_IDLE, STATE_CONNECTING, STATE_PAUSED, STATE_CONSUMING,
  STATE_FAILED
}

Member Enumeration Documentation

enum IToiMediaConsumer::TToiState [inherited]

State identifier used to identify the media consumer state.

Enumerator:
STATE_IDLE 

In 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 STATE_IDLE. The media consumer will only leave STATE_IDLE on a successful call to Open().

STATE_CONNECTING 

In 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 STATE_PAUSED when it has successfully established the connection to the stream source. If the media consumer decides it cannot connect, it will enter STATE_FAILED instead. If the application is not interrested in knowing when the consumer has connected, it may call Consume() to set the player in STATE_CONSUMING directly. The application may end the session by calling Close(), which makes the consumer go to STATE_IDLE.

STATE_PAUSED 

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

STATE_CONSUMING 

In 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 Close(), which makes the consumer go to STATE_IDLE. If an error occurs with the stream severe enough for the consumer to determine it cannot continue, the consumer will go to STATE_FAILED.

STATE_FAILED 

In 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 STATE_FAILED on a call by the application to Close().


Member Function Documentation

void IToiMediaConsumer::Close (  )  raises (TToiSessionViolationException, TToiUnavailableException) [inherited]

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 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:
Open(), TToiState
void IToiMediaConsumer::Consume (  )  raises (TToiSessionViolationException, TToiOperationNotSupportedException, TToiUnavailableException) [inherited]

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

Exceptions:
TToiSessionViolationException If the consumer is in 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 STATE_FAILED, for example.
TToiUnavailableException TToiUnavailableException is raised if the consumer is temporarily unavailable due to platform resource management.
See also:
Open(), TToiState
void IToiMediaConsumer::GetSessionId ( out IToiMediaSession::TToiSessionId  id  )  raises (TToiSessionViolationException) [inherited]

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

Return values:
id The session identifier.
Exceptions:
TToiSessionViolationException If the consumer is in STATE_IDLE a session violation exception is raised.
void IToiMediaConsumer::GetState ( out TToiState  state  )  [inherited]

Returns the current state of the media consumer instance.

Return values:
state The current consumer state.
void IToiMediaConsumer::GetUrl ( out string  url  )  raises (TToiSessionViolationException) [inherited]

Returns the URL for the media stream.

Return values:
url The URL for the media stream.
Exceptions:
TToiSessionViolationException If the consumer is in STATE_IDLE a session violation exception is raised.
void IToiMediaConsumer::Open ( in string  url  )  raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiUnavailableException) [inherited]

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 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 STATE_PAUSED or STATE_FAILED, on success and failure, respectively. In any respect, the application will be notified about this event by a call to its IToiMediaConsumerObserver::OnStateChanged() 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 Open(), 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:
Close(), TToiState
void IToiMediaConsumer::RegisterObserver ( in IToiApplicationService::TToiApplicationId  applicationId,
in string  address 
) raises (TToiInvalidArgumentException) [inherited]

Register an observer of type IToiMediaConsumerObserver. The observer will receive events sent by this IToiMediaConsumer instance.

Parameters:
applicationId The identifier of the observing application.
address The address where the IToiMediaConsumer can find an IToiMediaConsumerObserver interface.
Exceptions:
TToiInvalidArgumentException Raised if the specified address is invalid or if the application has already registered itself as an observer with the same address.
See also:
IToiMediaConsumerObserver
void IMediaConsumer::RegisterObserverInternal ( in string  address  )  raises (TToiInvalidArgumentException)

Add a media consumer observer. Observers are notified about consumer-related events.

Parameters:
address IPC address to an observer that implements the IToiMediaConsumerObserver interface.
Exceptions:
TToiInvalidArgumentException Raised if the specified address is not a legal IPC address.
See also:
ReleaseObserver(), IToiMediaConsumerObserver
void IToiMediaConsumer::ReleaseInstance (  )  [inherited]

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

void IToiMediaConsumer::ReleaseObserver ( in string  address  )  raises (TToiInvalidArgumentException) [inherited]

Release an observer previously registered with RegisterObserver.

Parameters:
address The address where the IToiMediaConsumer can find the registered IToiMediaConsumerObserver interface.
Exceptions:
TToiInvalidArgumentException Raised if the specified address is invalid.
See also:
IToiMediaConsumerObserver