ToiMediaRecorder

Method Summary

close ( )	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.
open ( url , contentId )	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.
record ( )	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.
recordAt ( offset )	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.
setParameter ( name , value )	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.
setParameters ( parameters )	This function sets the values of multiple parameters at once. Depending on the current state, the new values are used differently. If the function is called when in idle state, the new values are used for all sessions started after the parameters are set. If the function is called in any other state but the idle state, the new values are applied to that session only and are discarded automatically when the session ends. If an exception is raised, no parameters will be set.
unsetParameter ( name )	This function is used to remove a parameter. If the function is called when in idle state, the parameter is removed for all sessions which start after the parameter is removed. If the function is called in any other state but the idle state, the parameter is removed for that session only.
unsetParameters ( names )	This function is used to remove multiple parameters at once. If the function is called when in idle state, the parameters are removed for all sessions which start after the parameters are removed. If the function is called in any other state but the idle state, the parameters are removed for that session only. If an exception is raised, no parameters will be removed.

Inherited Methods

addEventListener ( type , listener )	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.
getContentId ( ) → contentId	Returns the unique content identifier for the recorded content. This identifier is recognized by the ToiContentService.
getParameter ( name ) → value	Get the current value of a parameter.
getParameters ( names ) → Array.<ToiMediaSession.ToiParameterInfo>	Get the values of several parameters.
getSessionId ( ) → id	Returns the session identifier. This identifier can be used to open a session object with ToiMediaService#openSession.
getState ( ) → state	Returns the current state of the media recorder instance.
getUrl ( ) → url	Returns the URL for the media stream.
releaseInstance ( )	This function releases the resources used by this instance. When this function returns all observers has also been released.
removeEventListener ( type , listener )	This method removes an event listener for a specific event.
subscribeParameter ( eventListener , name )	This function makes the application subscribe to updates of a specific named parameter. The first time an application subscribes to a specific parameter there will be an immediate ToiMediaRecorderParameterChangedEvent notification if the parameter already has a value.
subscribeParameters ( eventListener , names )	This function makes the application subscribe to updates of the given list of parameters. The first time an application subscribes to a specific parameter there will be an immediate ToiMediaRecorderParameterChangedEvent notification if the parameter already has a value.
unsubscribeParameter ( eventListener , name )	This function undoes the effect of a previous call to ToiMediaRecorderBase#subscribeParameter. Any parameter that has not been subscribed to will simply be ignored.
unsubscribeParameters ( eventListener , names )	This function undoes the effect of a previous call to ToiMediaRecorderBase#subscribeParameters. Any parameters that has not been subscribed to will simply be ignored.

Methods

addEventListener ( type , listener )

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.

Inherited From:

ToiEventTarget#addEventListener

Parameters:

Name	Type	Description
`type`	number	The event type of the event to subscribe to.
`listener`	ToiEventListener	The JavaScript function that will receive events.

Throws:

ToiInvalidArgumentException 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.

close ( )

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.

See also:

Note:

The only way to leave the STATE_FAILED state is a call to ToiMediaRecorder#close.

Throws:

ToiSessionViolationException

Raised if the recorder is in STATE_IDLE.

getContentId ( ) → contentId

Returns the unique content identifier for the recorded content. This identifier is recognized by the ToiContentService.

Inherited From:

ToiMediaRecorderBase#getContentId

Throws:

ToiSessionViolationException

Raised if the recorder is in ToiMediaRecorderBase.STATE_IDLE.

Returns:

The content identifier.

Type: ToiMediaRecorderBase.ToiContentId

getParameter ( name ) → value

Get the current value of a parameter.

Inherited From:

ToiMediaRecorderBase#getParameter

See also:

Parameters:

Name	Type	Description
`name`	string	Name of the requested parameter.

Throws:

ToiInvalidArgumentException

Raised if the parameter name is invalid or not recognized.

Returns:

The current value of the parameter.

Type: string

getParameters ( names ) → Array.<ToiMediaSession.ToiParameterInfo>

Get the values of several parameters.

Inherited From:

ToiMediaRecorderBase#getParameters

See also:

Parameters:

Name	Type	Description
`names`	Array.<ToiMediaSession.ToiParameterName> (Or a single ToiMediaSession.ToiParameterName.)	A list of parameter names. A single element can be passed directly and does not need to be passed in an array.

Returns:

A list of the returned parameters. If a parameter does not exist (is not set), the status of the corresponding parameter is set to ToiMediaSession.STATUS_NO_PARAMETER.

Type: Array.<ToiMediaSession.ToiParameterInfo>

getSessionId ( ) → id

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

Inherited From:

ToiMediaRecorderBase#getSessionId

See also:

ToiMediaService#openSession

Throws:

ToiSessionViolationException

Raised if the recorder is in ToiMediaRecorderBase.STATE_IDLE.

Returns:

The session identifier.

Type: ToiMediaSession.ToiSessionId

getState ( ) → state

Returns the current state of the media recorder instance.

Inherited From:

ToiMediaRecorderBase#getState

Returns:: The current recorder state.

Type: ToiMediaRecorderBase.ToiMediaRecorderState

getUrl ( ) → url

Returns the URL for the media stream.

Inherited From:

ToiMediaRecorderBase#getUrl

Throws:

ToiSessionViolationException

Raised if the recorder is in ToiMediaRecorderBase.STATE_IDLE.

Returns:

The URL for the media stream.

Type: string

open ( url , contentId )

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.

See also:

Parameters:

Name	Type	Description
`url`	string	The URL identifying the media source. The URL string may contain additional parameter information in accordance to the extended URL format.
`contentId`	ToiMediaRecorderBase.ToiContentId	Identifies the content to record to. This identifier is provided by ToiRecordedContentSource.

Throws:

ToiSessionViolationException	Raised if the recorder is not in STATE_IDLE. the query parameter "SessionMode=AttachOnly" is specified in the URL and no matching session is found for this URL which is in running state (ToiMediaSession.ToiState.STATE_RUNNING).
ToiInvalidArgumentException	Raised if the URL given as argument does not follow the extended URL format or if the content identifier is invalid.
ToiBusyException	Raised if the content is locked and used by another recorder.
ToiUnavailableException	Raised if the recorder is unavailable due to platform resource management or license limitations.
ToiInvalidPreconditionException	Raised if appending is not supported and the content used for recording already exists and is not empty (has already been recorded to).

record ( )

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.

See also:

ToiMediaRecorderBase.ToiMediaRecorderState

Throws:

ToiSessionViolationException	Raised if the recorder is in STATE_IDLE.
ToiOperationNotSupportedException	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.

recordAt ( offset )

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 {@link STATE_FAILED}. In any respect, the application will be notified about those state transistions by calls to its ToiMediaRecorderStateChangedEvent function.

See also:

Parameters:

Name	Type	Description
`offset`	number	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.

Throws:

ToiSessionViolationException	Raised if the recorder is in STATE_IDLE.
ToiOperationNotSupportedException	Raised if the recorder is in a state in which this operation is not supported. This is the case when in {@link STATE_FAILED}, for example. What is supported in which state may in other cases vary depending on which media source is used.

releaseInstance ( )

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

Inherited From:

ToiMediaRecorderBase#releaseInstance

removeEventListener ( type , listener )

This method removes an event listener for a specific event.

Inherited From:

ToiEventTarget#removeEventListener

Parameters:

Name	Type	Description
`type`	number	The event type of the event to remove the listener from.
`listener`	ToiEventListener	The JavaScript function that was previously added as an event listener.

Throws:

ToiInvalidArgumentException 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 has not previously been added.

setParameter ( name , value )

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.

See also:

Parameters:

Name	Type	Description
`name`	string	The name of the parameter to set.
`value`	string	The value to set the parameter to.

Throws:

ToiInvalidArgumentException	Raised if an empty string is used as parameter name or a parameter value exceeds the maximum size.
ToiPermissionDeniedException	Raised if attempting to set an internal parameter.

setParameters ( parameters )

This function sets the values of multiple parameters at once. Depending on the current state, the new values are used differently. If the function is called when in idle state, the new values are used for all sessions started after the parameters are set. If the function is called in any other state but the idle state, the new values are applied to that session only and are discarded automatically when the session ends. If an exception is raised, no parameters will be set.

See also:

Parameters:

Name	Type	Description
`parameters`	Array.<ToiMediaSession.ToiParameter> (Or a single ToiMediaSession.ToiParameter.)	A list of parameters with name and value. A single element can be passed directly and does not need to be passed in an array.

Throws:

ToiInvalidArgumentException	Raised if an empty string is used as parameter name or a parameter value exceeds the maximum size.
ToiPermissionDeniedException	Raised if attempting to set an internal parameter.

subscribeParameter ( eventListener , name )

This function makes the application subscribe to updates of a specific named parameter. The first time an application subscribes to a specific parameter there will be an immediate ToiMediaRecorderParameterChangedEvent notification if the parameter already has a value.

Inherited From:

ToiMediaRecorderBase#subscribeParameter

See also:

Parameters:

Name	Type	Description
`eventListener`	ToiEventListener	The eventListener that has been registered.
`name`	string	The name of the parameter for which changes the application wants to subscribe to.

Throws:

ToiInvalidArgumentException

Raised if the address name is invalid or not registered.

subscribeParameters ( eventListener , names )

This function makes the application subscribe to updates of the given list of parameters. The first time an application subscribes to a specific parameter there will be an immediate ToiMediaRecorderParameterChangedEvent notification if the parameter already has a value.

Inherited From:

ToiMediaRecorderBase#subscribeParameters

See also:

Parameters:

Name	Type	Description
`eventListener`	ToiEventListener	The eventListener that has been registered.
`names`	Array.<ToiMediaSession.ToiParameterName> (Or a single ToiMediaSession.ToiParameterName.)	The list of names of parameters. A single element can be passed directly and does not need to be passed in an array.

Throws:

ToiInvalidArgumentException	Raised if the address name is invalid or not registered.
ToiUnavailableException	Raised if the recoder is temporarily unavailable due to platform resource management.

unsetParameter ( name )

This function is used to remove a parameter. If the function is called when in idle state, the parameter is removed for all sessions which start after the parameter is removed. If the function is called in any other state but the idle state, the parameter is removed for that session only.

See also:

Parameters:

Name	Type	Description
`name`	string	The name of the parameter to be removed.

Throws:

ToiInvalidArgumentException	Raised if an empty string is used as parameter name.
ToiPermissionDeniedException	Raised if attempting to unset an internal parameter.

unsetParameters ( names )

This function is used to remove multiple parameters at once. If the function is called when in idle state, the parameters are removed for all sessions which start after the parameters are removed. If the function is called in any other state but the idle state, the parameters are removed for that session only. If an exception is raised, no parameters will be removed.

See also:

Parameters:

Name	Type	Description
`names`	Array.<ToiMediaSession.ToiParameterName> (Or a single ToiMediaSession.ToiParameterName.)	A list of names of parameters to be removed. A single element can be passed directly and does not need to be passed in an array.

Throws:

ToiInvalidArgumentException	Raised if an empty string is used as parameter name.
ToiPermissionDeniedException	Raised if attempting to unset an internal parameter.

unsubscribeParameter ( eventListener , name )

This function undoes the effect of a previous call to ToiMediaRecorderBase#subscribeParameter. Any parameter that has not been subscribed to will simply be ignored.

Inherited From:

ToiMediaRecorderBase#unsubscribeParameter

See also:

Parameters:

Name	Type	Description
`eventListener`	ToiEventListener	The eventListener that has been registered.
`name`	string	The name of the parameter that the application is no longer interested in.

Throws:

ToiInvalidArgumentException

Raised if the address name is invalid or not registered.

unsubscribeParameters ( eventListener , names )

This function undoes the effect of a previous call to ToiMediaRecorderBase#subscribeParameters. Any parameters that has not been subscribed to will simply be ignored.

Inherited From:

ToiMediaRecorderBase#unsubscribeParameters

See also:

Parameters:

Name	Type	Description
`eventListener`	ToiEventListener	The eventListener that has been registered.
`names`	Array.<ToiMediaSession.ToiParameterName> (Or a single ToiMediaSession.ToiParameterName.)	The list of parameter names. A single element can be passed directly and does not need to be passed in an array.

Throws:

ToiInvalidArgumentException	Raised if the address name is invalid or not registered.
ToiUnavailableException	Raised if the recorder is temporarily unavailable due to platform resource management.