IMediaDistributor Interface Reference


Description

TECHNICAL PREVIEW - this interface may change. The IMediaDistributor interface is the access point for a media distributor. Access to this interface is acquired through the IMediaService::CreateDistributorInstanceInternal().

See also:
IMediaService

import "IMediaDistributor.idl";

List of all members.

Public Member Functions

void Open (in string sourceUrl, in string destinationUrl) raises (TToiSessionViolationException, TToiInvalidArgumentException)
void Close () raises (TToiSessionViolationException)
void Play (in long pace) raises (TToiSessionViolationException, TToiOperationNotSupportedException, TToiInvalidArgumentException)
void GetState (out TMediaDistributorState state)
void GetSessionId (out IToiMediaSession::TToiSessionId id) raises (TToiSessionViolationException)
void GetSourceUrl (out string url) raises (TToiSessionViolationException)
void SetParameter (in string name, in string value) raises (TToiInvalidArgumentException, TToiPermissionDeniedException)
void UnsetParameter (in string name) raises (TToiInvalidArgumentException, TToiPermissionDeniedException)
void GetParameter (in string name, out string value) raises (TToiInvalidArgumentException)
void SubscribeParameter (in string name) raises (TToiInvalidArgumentException)
void UnsubscribeParameter (in string name) raises (TToiInvalidArgumentException)
void ReleaseInstance ()
void RegisterObserverInternal (in string address) raises (TToiInvalidArgumentException)
void ReleaseObserverInternal (in string address) raises (TToiInvalidArgumentException)

Public Types

enum  TMediaDistributorState {
  STATE_IDLE, STATE_CONNECTING, STATE_PAUSED, STATE_PLAYING,
  STATE_FASTFORWARDING, STATE_REWINDING, STATE_FAILED
}

Member Enumeration Documentation

State identifier used to identify the media distributor state.

Enumerator:
STATE_IDLE 

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

STATE_CONNECTING 

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

STATE_PAUSED 

In STATE_PAUSED the media distributor has a connection to a media source but playback is halted. On a command from the application, the distributor will leave this state for one of the other distributor states STATE_PLAYING, STATE_FASTFORWARDING, or STATE_REWINDING. The application may also end the session by calling Close(), which makes the distributor go to STATE_IDLE. If an error occurs with the stream severe enough for the distributor to determine it cannot continue distribution, the player will go to STATE_FAILED.

STATE_PLAYING 

In STATE_PLAYING the media distributor has a connection to a media source and distributes the stream from that source in normal pace. On a command from the application, the distributor will leave this state for one of the other playback states STATE_PAUSED, STATE_FASTFORWARDING, or STATE_REWINDING. The application may also end the session by calling Close(), which makes the distributor go to STATE_IDLE. If an error occurs with the stream severe enough for the distributor to determine it cannot continue distribution, the distributor will go to STATE_FAILED.

STATE_FASTFORWARDING 

In STATE_FASTFORWARDING the media distributor has a connection to a media source and distributes the stream from that source in forward direction at a pace above normal playback. For streams on which this operation cannot be performed, this state is not available. On a command from the application, the distributor will leave this state for one of the other distribution states STATE_PLAYING, STATE_PAUSED, or STATE_REWINDING. The application may also end the session by calling Close(), which makes the distributor go to STATE_IDLE. If an error occurs with the stream severe enough for the distributor to determine it cannot continue distribution, the distributor will go to STATE_FAILED.

STATE_REWINDING 

In STATE_REWINDING the media distributor has a connection to a media source and distributes the stream from that source in backward direction at a pace above normal playback. For streams on which this operation cannot be performed, this state is not available. On a command from the application, the distributor will leave this state for one of the other distribution states STATE_PLAYING, STATE_PAUSED, or STATE_FASTFORWARDING. The application may also end the session by calling Close(), which makes the distributor go to STATE_IDLE. If an error occurs with the stream severe enough for the distributor to determine it cannot continue distribution, the distributor will go to STATE_FAILED.

STATE_FAILED 

In STATE_FAILED the media distributor 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 distributor goes to this state is a remote client has disconnected. The media distributor will only leave STATE_FAILED on a call by the application to Close().


Member Function Documentation

void IMediaDistributor::Close (  )  raises (TToiSessionViolationException)

This function ends the current session by stopping any distribution and 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 distributor state has changed to STATE_IDLE. If an exception is raised, the distributor state is unaffected.

Exceptions:
TToiSessionViolationException If the distributor is in idle state a session violation exception is raised.
See also:
Open(), TMediaDistributorState
void IMediaDistributor::GetParameter ( in string  name,
out string  value 
) raises (TToiInvalidArgumentException)

Get the current value of a parameter.

Parameters:
name Name of the requested parameter.
Return values:
value The parameter's current value.
Exceptions:
TToiInvalidArgumentException If the name given as argument does not identify a parameter, an invalid argument exception is raised.
void IMediaDistributor::GetSessionId ( out IToiMediaSession::TToiSessionId  id  )  raises (TToiSessionViolationException)

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 player is in STATE_IDLE a session violation exception is raised.
See also:
IToiMediaService::OpenSession()
void IMediaDistributor::GetSourceUrl ( out string  url  )  raises (TToiSessionViolationException)

Returns the URL for the source stream.

Return values:
url The URL for the source stream.
Exceptions:
TToiSessionViolationException If the distributor is in idle state a session violation exception is raised.
void IMediaDistributor::GetState ( out TMediaDistributorState  state  ) 

Returns the current state of the media distributor instance.

Return values:
state The current distributor state.
void IMediaDistributor::Open ( in string  sourceUrl,
in string  destinationUrl 
) raises (TToiSessionViolationException, TToiInvalidArgumentException)

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

Depending on the success of the connection attempt to the media source, the distributor 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 IMediaDistributorObserver::OnStateChanged() function.

Parameters:
sourceUrl The URL identifying the media source. The URL string may contain additional parameter information in accordance to the extended URL format.
destinationUrl The URL identifying the remote client.
Exceptions:
TToiSessionViolationException If the distributor 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.
See also:
Close(), TMediaDistributorState
void IMediaDistributor::Play ( in long  pace  )  raises (TToiSessionViolationException, TToiOperationNotSupportedException, TToiInvalidArgumentException)

This function resumes playback of the stream. If this function returns successfully, the player state has changed to STATE_PLAYING, STATE_FASTFORWARDING or STATE_REWIND depending on the pace value. If an exception is raised, the player state is unaffected.

Parameters:
pace The requested pace for playback, given as a multiplier of normal playback times 1000. A pace greater than 1000 fast forwards the stream, and a value less than -1000 rewinds the stream. A pace value of 0 pauses the stream.
Exceptions:
TToiSessionViolationException If the player is in STATE_IDLE a session violation exception is raised.
TToiOperationNotSupportedException If the player 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. What is supported in which state may in other cases vary depending on which media source is used.
TToiInvalidArgumentException If the operation is supported but the position argument is outside the range of positions accepted for the current stream, an invalid argument exception is raised.
See also:
TMediaDistributorState
void IMediaDistributor::ReleaseInstance (  ) 

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

void IMediaDistributor::SetParameter ( in string  name,
in string  value 
) raises (TToiInvalidArgumentException, TToiPermissionDeniedException)

This function sets the value of a parameter. Depending on the current state, the new value is used differently. If the function is called when in idle state, the new value is used for all sessions started after the parameter is set. If the function is called in any other state but the idle state, the new value is applied to that session only and is discarded automatically when the session ends.

Parameters:
name The name of the parameter to set.
value The value to set the parameter to.
Exceptions:
TToiInvalidArgumentException The paramter name is illegal.
TToiPermissionDeniedException The application does not have permission to change the value of the parameter.
See also:
UnsetParameter(), GetParameter()
void IMediaDistributor::SubscribeParameter ( in string  name  )  raises (TToiInvalidArgumentException)

This function makes the application subscribe to updates of a specific named paramter.

Parameters:
name The name of the parameter for which changes the application wants to subscribe to.
Exceptions:
TToiInvalidArgumentException The parameter name is illegal.
See also:
UnsubscribeParameter()
void IMediaDistributor::UnsetParameter ( in string  name  )  raises (TToiInvalidArgumentException, TToiPermissionDeniedException)

This function restores the value of a parameter to the default. Depending on the current state, the new value is used differently. If the function is called when in idle state, all sessions started after the parameter is restored will use the default value. If the function is called in any other state but the idle state, the value is changed for that session only.

Parameters:
name The name of the parameter for which the value is to be restored to the default.
Exceptions:
TToiInvalidArgumentException The paramter name is illegal.
TToiPermissionDeniedException The application does not have permission to change the value of the parameter.
See also:
SetParameter(), GetParameter()
void IMediaDistributor::UnsubscribeParameter ( in string  name  )  raises (TToiInvalidArgumentException)

This function undoes the effect of a previous call to SubscribeParameter().

Parameters:
name The name of the parameter that the application is no longer interested in.
Exceptions:
TToiInvalidArgumentException The parameter name is illegal.
See also:
SubscribeParameter()