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
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:
-
- See also:
- Open(), TMediaDistributorState
Get the current value of a parameter.
- Parameters:
-
| name | Name of the requested parameter. |
- Return values:
-
| value | The parameter's current value. |
- Exceptions:
-
Returns the URL for the source stream.
- Return values:
-
| url | The URL for the source stream. |
- Exceptions:
-
Returns the current state of the media distributor instance.
- Return values:
-
| state | The current distributor state. |
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:
-
- See also:
- Close(), TMediaDistributorState
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.
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:
-
- See also:
- UnsetParameter(), GetParameter()
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:
-
- See also:
- UnsubscribeParameter()
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:
-
- See also:
- SetParameter(), GetParameter()
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:
-
- See also:
- SubscribeParameter()