IToiMediaRecorder Interface Reference


Description

The IToiMediaRecorder interface is the access point for a media recorder. Access to this interface is acquired through the IToiMediaService::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:
IToiMediaRecorderBase
IToiMediaService

import "IToiMediaRecorder.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)
void GetState (out TToiMediaRecorderState state)
void GetSessionId (out IToiMediaSession::TToiSessionId id) raises (TToiSessionViolationException)
void GetUrl (out string url) raises (TToiSessionViolationException)
void GetAssetId (out string assetId) raises (TToiSessionViolationException)
void GetParameter (in string name, out string value) raises (TToiInvalidArgumentException)
void SubscribeParameter (in string address, in string name) raises (TToiInvalidArgumentException)
void UnsubscribeParameter (in string address, in string name) raises (TToiInvalidArgumentException)
void ReleaseInstance ()
void RegisterObserver (in IToiApplicationService::TToiApplicationId applicationId, in string address) raises (TToiInvalidArgumentException)
void ReleaseObserver (in string address) raises (TToiInvalidArgumentException)

Public Types

enum  TToiMediaRecorderState {
  STATE_IDLE, STATE_CONNECTING, STATE_PAUSED, STATE_RECORDING,
  STATE_FAILED
}
typedef TToiMediaRecorderState TState

Member Enumeration Documentation

State identifier used to identify the media recorder state.

Enumerator:
STATE_IDLE 

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.

STATE_CONNECTING 

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

STATE_PAUSED 

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

STATE_RECORDING 

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

STATE_FAILED 

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.


Member Function Documentation

void IToiMediaRecorder::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 Close().
Exceptions:
TToiSessionViolationException If the recorder is in STATE_IDLE a session violation exception is raised.
See also:
Open()
RecordAt()
Record()
TToiMediaRecorderState
void IToiMediaRecorderBase::GetAssetId ( out string  assetId  )  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.
void IToiMediaRecorderBase::GetParameter ( in string  name,
out string  value 
) 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:
IToiMediaRecorder::SetParameter()
IToiMediaRecorder::UnsetParameter()
SubscribeParameter()
void IToiMediaRecorderBase::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 player is in STATE_IDLE a session violation exception is raised.
See also:
IToiMediaService::OpenSession()
void IToiMediaRecorderBase::GetState ( out TToiMediaRecorderState  state  )  [inherited]

Returns the current state of the media recorder instance.

Return values:
state The current recorder state.
void IToiMediaRecorderBase::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 recorder is in idle state a session violation exception is raised.
void IToiMediaRecorder::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 IToiMediaRecorderObserver::OnStateChanged() function.

The application ends the session by calling 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 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:
Close()
TToiMediaRecorderState
void IToiMediaRecorder::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 IToiMediaRecorder::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 IToiMediaRecorderObserver::OnStateChanged() 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:
Close()
TToiMediaRecorderState
void IToiMediaRecorderBase::RegisterObserver ( in IToiApplicationService::TToiApplicationId  applicationId,
in string  address 
) raises (TToiInvalidArgumentException) [inherited]

Register an observer of type IToiMediaRecorderObserver. The observer will receive events sent by this IToiMediaRecorderBase instance.

Parameters:
applicationId The identifier of the observing application.
address The address where the IToiMediaRecorderBase can find an IToiMediaRecorderObserver 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:
IToiMediaRecorderObserver
void IToiMediaRecorderBase::ReleaseInstance (  )  [inherited]

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

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

Release an observer previously registered with RegisterObserver.

Parameters:
address The address where the IToiMediaRecorderBase can find the registered IToiMediaRecorderObserver interface.
Exceptions:
TToiInvalidArgumentException Raised if the specified address is invalid.
See also:
IToiMediaRecorderObserver
void IToiMediaRecorder::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:
UnsetParameter()
GetParameter()
void IToiMediaRecorderBase::SubscribeParameter ( in string  address,
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 IToiMediaRecorderObserver::OnParameterChanged() if there is a value available.

Parameters:
address The observer address of the parameter that is subscribed.
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:
UnsubscribeParameter()
void IToiMediaRecorder::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:
SetParameter()
GetParameter()
void IToiMediaRecorderBase::UnsubscribeParameter ( in string  address,
in string  name 
) raises (TToiInvalidArgumentException) [inherited]

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

Parameters:
address The observer address of the parameter that is unsubscribed.
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:
SubscribeParameter()