ToiMediaRecorder Interface Reference

Description

The ToiMediaRecorder interface is the access point for a media recorder. Access to this interface is acquired through the ToiMediaService::createRecorderInstance() function. It is possible to create multiple private media recorder instances. Each application gets its own private instance of this interface for each of its media recorder instances.

See also:
ToiMediaRecorderBase
ToiMediaService

import "ToiMediaRecorder.idl";

List of all members.

Public Member Functions

void open (in string url, in string assetId) raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiBusyException, TToiUnavailableException, TToiInvalidPreconditionException)
void close () raises (TToiSessionViolationException)
void record () raises (TToiSessionViolationException, TToiOperationNotSupportedException)
void recordAt (in unsigned long offset) raises (TToiSessionViolationException, TToiOperationNotSupportedException)
void setParameter (in string name, in string value) raises (TToiInvalidArgumentException, TToiPermissionDeniedException)
void unsetParameter (in string name) raises (TToiInvalidArgumentException, TToiPermissionDeniedException)
TToiMediaRecorderState getState ()
ToiMediaSession::TToiSessionId getSessionId () raises (TToiSessionViolationException)
string getUrl () raises (TToiSessionViolationException)
string getAssetId () raises (TToiSessionViolationException)
string getParameter (in string name) raises (TToiInvalidArgumentException)
void subscribeParameter (in ToiEventListener eventListener, in string name) raises (TToiInvalidArgumentException)
void unsubscribeParameter (in ToiEventListener eventListener, in string name) raises (TToiInvalidArgumentException)
void releaseInstance ()
void addEventListener (in long type, in ToiEventListener listener) raises (TToiInvalidArgumentException)
void removeEventListener (in long type, in ToiEventListener listener) raises (TToiInvalidArgumentException)

Public Attributes

Events

const long ON_STATE_CHANGED = 1800
const long ON_PARAMETER_CHANGED = 1801
TToiMediaRecorderState

const TToiMediaRecorderState STATE_IDLE = 0
const TToiMediaRecorderState STATE_CONNECTING = 1
const TToiMediaRecorderState STATE_PAUSED = 2
const TToiMediaRecorderState STATE_RECORDING = 3
const TToiMediaRecorderState STATE_FAILED = 4

Public Types

typedef long TToiMediaRecorderState

Member Typedef Documentation

typedef long ToiMediaRecorderBase::TToiMediaRecorderState [inherited]

State identifier used to identify the media recorder state.

Member Function Documentation

void ToiEventTarget::addEventListener ( in long  type,
in ToiEventListener  listener 
) raises (TToiInvalidArgumentException) [inherited]

This method registers an event listener for a specific event. Multiple listeners can be added for the same event. Events are broadcast to all registered listeners.

Parameters:
type The event type of the event to subscribe to.
listener The JavaScript function that will receive events.
Exceptions:
TInvalidArgumentException Raised if the event type is not supported by this object or if the listener is not a valid JavaScript function. This exception is also raised if the application calls addEventListener with the same combination of type and listener twice.
void ToiMediaRecorder::close (  )  raises (TToiSessionViolationException)

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

Note:
The only way to leave the STATE_FAILED state is a call to ToiMediaRecorder::close().
Exceptions:
TToiSessionViolationException If the recorder is in STATE_IDLE a session violation exception is raised.
See also:
ToiMediaRecorder::open()
ToiMediaRecorder::recordAt()
ToiMediaRecorder::record()
TToiMediaRecorderState
string ToiMediaRecorderBase::getAssetId (  )  raises (TToiSessionViolationException) [inherited]

Returns the asset used for recording.

Return values:
assetId The asset identifier.
Exceptions:
TToiSessionViolationException If the recorder is in idle state a session violation exception is raised.
string ToiMediaRecorderBase::getParameter ( in string  name  )  raises (TToiInvalidArgumentException) [inherited]

Get the current value of a parameter.

Parameters:
name Name of the requested parameter.
Return values:
value The current value of the parameter.
Exceptions:
TToiInvalidArgumentException The parameter name is invalid or not recognized.
See also:
ToiMediaRecorder::setParameter()
ToiMediaRecorder::unsetParameter()
ToiMediaRecorderBase::subscribeParameter()
ToiMediaSession::TToiSessionId ToiMediaRecorderBase::getSessionId (  )  raises (TToiSessionViolationException) [inherited]

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

Return values:
id The session identifier.
Exceptions:
TToiSessionViolationException If the player is in STATE_IDLE a session violation exception is raised.
See also:
ToiMediaService::openSession()
TToiMediaRecorderState ToiMediaRecorderBase::getState (  )  [inherited]

Returns the current state of the media recorder instance.

Return values:
state The current recorder state.
string ToiMediaRecorderBase::getUrl (  )  raises (TToiSessionViolationException) [inherited]

Returns the URL for the media stream.

Return values:
url The URL for the media stream.
Exceptions:
TToiSessionViolationException If the recorder is in idle state a session violation exception is raised.
void ToiMediaRecorder::open ( in string  url,
in string  assetId 
) raises (TToiSessionViolationException, TToiInvalidArgumentException, TToiBusyException, TToiUnavailableException, TToiInvalidPreconditionException)

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

Depending on the success of the connection attempt to the media source, the recorder 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 ToiMediaRecorderStateChangedEvent function.

The application ends the session by calling ToiMediaRecorder::close(), which makes the recorder change state to STATE_IDLE.

Parameters:
url The URL identifying the media source. The URL string may contain additional parameter information in accordance to the extended URL format.
assetId Identifies the asset to record to.
Exceptions:
TToiSessionViolationException If the recorder is not in STATE_IDLE at the time of the call to ToiMediaRecorder::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.
TToiBusyException If the asset is locked and used by another recorder.
TToiUnavailableException Raised if the recorder is temporarily unavailable due to platform resource management.
TToiInvalidPreconditionException Raised if the asset used for recording already exists and is not empty (has already been recorded to).
See also:
ToiMediaRecorder::close()
TToiMediaRecorderState
void ToiMediaRecorder::record (  )  raises (TToiSessionViolationException, TToiOperationNotSupportedException)

This function starts a recording of the stream. If this function returns successfully, the recorder state has changed to STATE_RECORDING. If an exception is raised, the recorder state is unaffected.

Exceptions:
TToiSessionViolationException If the recorder is in STATE_IDLE a session violation exception is raised.
TToiOperationNotSupportedException Raised if the recorder is in a state in which this operation is not supported. 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.
See also:
TToiMediaRecorderState
void ToiMediaRecorder::recordAt ( in unsigned long  offset  )  raises (TToiSessionViolationException, TToiOperationNotSupportedException)
Technical Preview:
This method is a TECHNICAL PREVIEW, it may change. This function starts a new recording session and may reuse existing recorded content from another ongoing recording session, including a possible timeshift session, sharing the same source.

Depending on the success of the connection attempt to the media source, the recorder will change state to STATE_RECORDING. If something goes wrong it will end up in state STATE_FAILED. In any respect, the application will be notified about those state transistions by calls to its ToiMediaRecorderStateChangedEvent function.

Parameters:
offset The offset (in milliseconds) relative to the current position, i.e. a value of 1000 means that one second back in time will be reused. If the specified offset time is not available less data than requested will be given.
Exceptions:
TToiSessionViolationException If the recorder is in STATE_IDLE a session violation exception is raised.
TToiOperationNotSupportedException Raised if the recorder is in a state in which this operation is not supported. 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.
See also:
ToiMediaRecorder::close()
TToiMediaRecorderState
void ToiMediaRecorderBase::releaseInstance (  )  [inherited]

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

void ToiEventTarget::removeEventListener ( in long  type,
in ToiEventListener  listener 
) raises (TToiInvalidArgumentException) [inherited]

This method removes an event listener for a specific event.

Parameters:
type The event type of the event to remove the listener from.
listener The JavaScript function that was previously added as an event listener.
Exceptions:
TInvalidArgumentException Raised if the event type is not supported by this object or if the listener is not a valid JavaScript function. This exception is also raised if the listener had not previously been added.
void ToiMediaRecorder::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 parameter name is invalid or not recognized.
TToiPermissionDeniedException The application does not have permission to change the value of the parameter.
See also:
ToiMediaRecorder::unsetParameter()
ToiMediaRecorder::getParameter()
void ToiMediaRecorderBase::subscribeParameter ( in ToiEventListener  eventListener,
in string  name 
) raises (TToiInvalidArgumentException) [inherited]

This function makes the application subscribe to updates of a specific named parameter. When the subscription is made there will be an immediate call to (C++) ToiMediaRecorderObserver::OnParameterChanged() if there is a value available.

Parameters:
eventListener ToiEventListener
name The name of the parameter for which changes the application wants to subscribe to.
Exceptions:
TToiInvalidArgumentException The parameter name is invalid or not recognized.
See also:
ToiMediaRecorderBase::unsubscribeParameter()
void ToiMediaRecorder::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 parameter name is invalid or not recognized.
TToiPermissionDeniedException The application does not have permission to change the value of the parameter.
See also:
ToiMediaRecorder::setParameter()
ToiMediaRecorder::getParameter()
void ToiMediaRecorderBase::unsubscribeParameter ( in ToiEventListener  eventListener,
in string  name 
) raises (TToiInvalidArgumentException) [inherited]

This function undoes the effect of a previous call to ToiMediaRecorderBase::subscribeParameter().

Parameters:
eventListener ToiEventListener
name The name of the parameter that the application is no longer interested in.
Exceptions:
TToiInvalidArgumentException The parameter name is invalid or not recognized.
See also:
ToiMediaRecorderBase::subscribeParameter()

Member Data Documentation

const long ToiMediaRecorderBase::ON_PARAMETER_CHANGED = 1801 [inherited]

This is an Event identifier for ToiMediaRecorderParameterChangedEvent.

This constant can also be accessed from toi.consts.ToiMediaRecorderBase.ON_PARAMETER_CHANGED.

const long ToiMediaRecorderBase::ON_STATE_CHANGED = 1800 [inherited]

This is an Event identifier for ToiMediaRecorderStateChangedEvent.

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

const TToiMediaRecorderState ToiMediaRecorderBase::STATE_CONNECTING = 1 [inherited]

In STATE_CONNECTING the media recorder has an active session and is in the process of establishing a connection to a media stream source.

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

const TToiMediaRecorderState ToiMediaRecorderBase::STATE_FAILED = 4 [inherited]

In STATE_FAILED the media recorder 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.

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

const TToiMediaRecorderState ToiMediaRecorderBase::STATE_IDLE = 0 [inherited]

In STATE_IDLE there is no active session. The media recorder 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.

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

const TToiMediaRecorderState ToiMediaRecorderBase::STATE_PAUSED = 2 [inherited]

In STATE_PAUSED the media recorder has a connection to a media source but is not yet recording the stream.

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

const TToiMediaRecorderState ToiMediaRecorderBase::STATE_RECORDING = 3 [inherited]

In STATE_RECORDING the media recorder has a connection to a media source and records the stream.

This constant can also be accessed from toi.consts.ToiMediaRecorderBase.STATE_RECORDING.