IMediaSession Interface Reference


Description

Extends IToiMediaSession with functions accessible only from other platform services.

See also:
IToiMediaSession

import "IMediaSession.idl";

List of all members.

Public Member Functions

void Cancel (in long type, in string reason) raises (TToiOperationNotSupportedException, TToiSessionViolationException)
void Suspend (in long type, in string reason) raises (TToiOperationNotSupportedException, TToiSessionViolationException)
void Resume (in long type, in string reason) raises (TToiOperationNotSupportedException, TToiSessionViolationException)
void SetEncryptionData (in binary keyMaterial, in long keyMaterialLength, in binary markerToken, in long markerTokenLength, in TCipherKeyParity keyParity) raises (TToiSessionViolationException)
void GetAssetPath (out string assetPath) raises (TToiOperationNotSupportedException, TToiSessionViolationException)
void RegisterObserverInternal (in string address) raises (TToiInvalidArgumentException)
void GetFrontendInfo (out TFrontendInfo info) raises (TToiNoDataException, TToiOperationNotSupportedException, TToiSessionViolationException)
void GetId (out TToiSessionId id)
void GetType (out TToiSessionType type) raises (TToiSessionViolationException)
void GetUrl (out string url) raises (TToiSessionViolationException)
void GetState (out TToiState state)
void GetStreamInfo (out TToiStreamInfo info) raises (TToiNoDataException, TToiSessionViolationException)
void GetAssetId (out string assetId) raises (TToiOperationNotSupportedException, TToiSessionViolationException)
void AddSectionDataRelay (in long pid, in TToiDataRelayData data, in TToiDataRelayData include, in TToiDataRelayData exclude, in long length, in string socketName, out long dataRelayId) raises (TToiInvalidArgumentException, TToiNotEnoughResourcesException, TToiSessionViolationException)
void AddPacketDataRelay (in long pid, in string socketName, out long dataRelayId) raises (TToiInvalidArgumentException, TToiNotEnoughResourcesException, TToiSessionViolationException)
void RemoveDataRelay (in long dataRelayId) raises (TToiInvalidArgumentException, TToiSessionViolationException)
void GetParameter (in string name, out string value) raises (TToiInvalidArgumentException, TToiSessionViolationException)
void SetParameter (in string name, in string value) raises (TToiInvalidArgumentException, TToiSessionViolationException)
void SubscribeParameter (in string address, in string name) raises (TToiInvalidArgumentException, TToiSessionViolationException)
void UnsubscribeParameter (in string address, in string name) raises (TToiInvalidArgumentException, TToiSessionViolationException)
void SetDecryptionCipher (in TToiStreamIdSequence streamIds, in TToiCipher cipher, in TToiCipherBlockMode blockMode, in TToiCipherResidueMode residueMode) raises (TToiOperationNotSupportedException, TToiSessionViolationException)
void SetDecryptionKeys (in TToiStreamIdSequence streamIds, in boolean isEncrypted, in TToiCipherData evenKey, in TToiCipherData evenIv, in TToiCipherData oddKey, in TToiCipherData oddIv, in long length) raises (TToiOperationNotSupportedException, TToiSessionViolationException)
void ReleaseInstance ()
void RegisterObserver (in IToiApplicationService::TToiApplicationId applicationId, in string address) raises (TToiInvalidArgumentException)
void ReleaseObserver (in string address) raises (TToiInvalidArgumentException)

Public Attributes

const TToiSessionType TYPE_PLAYER = 1
const TToiSessionType TYPE_RECORDER = 2
const TToiSessionType TYPE_CONSUMER = 4
const TToiSessionType TYPE_DISTRIBUTOR = 8

Public Types

enum  TCipherKeyParity { CIPHER_KEY_PARITY_NONE, CIPHER_KEY_PARITY_ODD, CIPHER_KEY_PARITY_EVEN }
typedef sequence< octet > binary
enum  TToiState { STATE_CONNECTING, STATE_RUNNING, STATE_FAILED, STATE_CLOSED }
enum  TToiCipher {
  CIPHER_NONE, CIPHER_DVB_CSA, CIPHER_ARIB_MULTI2, CIPHER_AES_128,
  CIPHER_TRIPLE_DES
}
enum  TToiCipherBlockMode {
  CIPHER_BLOCK_MODE_NONE, CIPHER_BLOCK_MODE_ECB, CIPHER_BLOCK_MODE_CBC, CIPHER_BLOCK_MODE_CFB,
  CIPHER_BLOCK_MODE_OFB, CIPHER_BLOCK_MODE_CTR
}
enum  TToiCipherResidueMode {
  CIPHER_RESIDUE_MODE_NONE, CIPHER_RESIDUE_MODE_FRONT, CIPHER_RESIDUE_MODE_BACK, CIPHER_RESIDUE_MODE_CTS,
  CIPHER_RESIDUE_MODE_OFB
}
typedef sequence< octet > TToiDataRelayData
typedef long TToiStreamId
typedef sequence< TToiStreamIdTToiStreamIdSequence
typedef sequence< octet > TToiCipherData
typedef long TToiSessionId
typedef long TToiSessionType

Member Typedef Documentation

typedef sequence< octet > IToiMediaSession::TToiCipherData [inherited]

Data type used for cipher keys and initialization vectors. These are stored as a sequence of bytes.

typedef sequence< octet > IToiMediaSession::TToiDataRelayData [inherited]

Data type used for data relay filter vectors. These are stored as a sequence of bytes.

typedef long IToiMediaSession::TToiSessionId [inherited]

The media session identifier type.

typedef long IToiMediaSession::TToiSessionType [inherited]

Data type used for identifying media session types. The type is used as a bitmask.

typedef long IToiMediaSession::TToiStreamId [inherited]

Data type used to identify a stream.

typedef sequence< TToiStreamId > IToiMediaSession::TToiStreamIdSequence [inherited]

Data type used for TToiStreamId vectors. These are stored as a sequence of TToiStreamId values.


Member Enumeration Documentation

Parity of cipher key.

Enumerator:
CIPHER_KEY_PARITY_NONE 

No parity

CIPHER_KEY_PARITY_ODD 

Odd parity

CIPHER_KEY_PARITY_EVEN 

Even parity

enum IToiMediaSession::TToiCipher [inherited]

List of ciphers.

Enumerator:
CIPHER_NONE 

Disable decryption, key length should be zero.

CIPHER_DVB_CSA 

DVB Common Scrambling Algorithm, 64 bit key length.

CIPHER_ARIB_MULTI2 

ARIB Multi-2, 64 bit key length.

CIPHER_AES_128 

Advanced Encryption Standard (FIPS 197), 128 bit key length.

CIPHER_TRIPLE_DES 

Triple Data Encryption Standard

List of cipher block modes.

Enumerator:
CIPHER_BLOCK_MODE_NONE 

Not applicable.

CIPHER_BLOCK_MODE_ECB 

Electronic Codebook Mode

CIPHER_BLOCK_MODE_CBC 

Cipher block chaining.

CIPHER_BLOCK_MODE_CFB 

Cipher feedback mode.

CIPHER_BLOCK_MODE_OFB 

Output feedback mode.

CIPHER_BLOCK_MODE_CTR 

Counter mode.

Cipher residue mode.

Enumerator:
CIPHER_RESIDUE_MODE_NONE 

Not applicable.

CIPHER_RESIDUE_MODE_FRONT 

Clear residue in the front.

CIPHER_RESIDUE_MODE_BACK 

Clear residue in the back.

CIPHER_RESIDUE_MODE_CTS 

Cipher Text Stealing according to OpenCable CCCP 2.0.

CIPHER_RESIDUE_MODE_OFB 

Output feedback mode according to ANSI/SCTE52.

enum IToiMediaSession::TToiState [inherited]

State identifier used to identify the media session state.

Enumerator:
STATE_CONNECTING 

In STATE_CONNECTING the media session is trying to connect to a media source. The session will not leave this state until it has recieved enough data to start playback or recording. It is possible for a session to later return to this state if the source becomes temporarily unavailable, for instance due to network congestion.

STATE_RUNNING 

In STATE_RUNNING the media session is fully connected and has received enough data. Note that this state does not reveal any information about the playback position or pace.

STATE_FAILED 

In STATE_FAILED the media session has permanently failed.

STATE_CLOSED 

In STATE_CLOSED the media session has been closed and will not be opened again.


Member Function Documentation

void IToiMediaSession::AddPacketDataRelay ( in long  pid,
in string  socketName,
out long  dataRelayId 
) raises (TToiInvalidArgumentException, TToiNotEnoughResourcesException, TToiSessionViolationException) [inherited]

Extract packet data from the stream and send to a Unix domain datagram socket. The data to extract is identified by the pid.

Parameters:
pid The transport stream packet identifier.
socketName The name of a Unix domain datagram socket to which filtered data should be sent.
Return values:
dataRelayId The identifier of the created data relay.
Exceptions:
TInvalidArgumentException If the pid is out of range or if it the filter does not apply to the current stream format an invalid argument exception is raised. It is also raised if an identical relay already has been setup for the same socket.
TNotEnoughResourcesException If too many relays have been setup an not enough resources exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
See also:
RemoveDataRelay()
void IToiMediaSession::AddSectionDataRelay ( in long  pid,
in TToiDataRelayData  data,
in TToiDataRelayData  include,
in TToiDataRelayData  exclude,
in long  length,
in string  socketName,
out long  dataRelayId 
) raises (TToiInvalidArgumentException, TToiNotEnoughResourcesException, TToiSessionViolationException) [inherited]

Extract section data from the stream and send to a Unix domain datagram socket. The data to extract is identified by the pid and the filter.

The first byte in the filter correspond to the first byte in the section. The second filter byte correspond to the fourth byte in the section, as the second and third section bytes contain the section length and the filtering mechanism skips these.

Inclusion mask: For all inclusion mask bits that are set to 1 all of the corresponding bits in the section must match the bits specified in the data coefficient in order to be included.

Exclusion mask: For all exclusion mask bits that are set to 1 at least one of the corresponding bits in the section must not match the bits specified by the data coefficient in order to be included.

Results from both comparisons are AND'ed together to form the final pass decision.

Parameters:
pid The transport stream packet identifier.
data This is the data for which the section data will be compared against. Note that the include and exclude masks are part of the filter.
include This is the include mask. Can be left empty to include all filter data. If not empty the length must match the data length.
exclude This is the exclude mask. Can be left empty for no exclusion. If not empty the length must match the data length.
length The length of the data, include and exclude vectors.
socketName The name of a Unix domain datagram socket to which filtered data should be sent.
Return values:
dataRelayId The identifier of the created data relay.
Exceptions:
TToiInvalidArgumentException If the pid is out of range, if the filter does not apply to the current stream format, or if the length is too large an invalid argument exception is raised. It is also raised if an identical relay already has been setup for the same socket.
TToiNotEnoughResourcesException If too many relays have been setup an not enough resources exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
See also:
RemoveDataRelay()
void IMediaSession::Cancel ( in long  type,
in string  reason 
) raises (TToiOperationNotSupportedException, TToiSessionViolationException)

Cancels one or more roles of a session.

Parameters:
type Bit mask indicating which role(s) that shall be cancelled, i.e.player, recorder, consumer, etc.
reason The reason for cancelling. Should be a value from ToiMediaReasonNames.h
Exceptions:
TToiOperationNotSupportedException If the session cannot cancel the requested types an operation not supported exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IToiMediaSession::GetAssetId ( out string  assetId  )  raises (TToiOperationNotSupportedException, TToiSessionViolationException) [inherited]

Returns the asset identifier used for recording.

Deprecated:
This method is not reliable since several assets may be used simultaneously in the same session.
Return values:
assetId The asset identifier.
Exceptions:
TToiOperationNotSupportedException If the stream is not being recorded an operation is not supported exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IMediaSession::GetAssetPath ( out string  assetPath  )  raises (TToiOperationNotSupportedException, TToiSessionViolationException)

Returns the path to the asset used for recording.

Return values:
assetPath The path to the asset.
Exceptions:
TToiOperationNotSupportedException If the stream is not being recorded an operation not supported exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IMediaSession::GetFrontendInfo ( out TFrontendInfo  info  )  raises (TToiNoDataException, TToiOperationNotSupportedException, TToiSessionViolationException)

Get status information about the frontend, i.e. tuner and demodulator.

Return values:
info The frontend status information.
Exceptions:
TToiNoDataException Raised if the frontend information is not available.
TToiOperationNotSupportedException If there is no frontend available an operation is not supported exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IToiMediaSession::GetId ( out TToiSessionId  id  )  [inherited]

Get the session identifier.

Return values:
id The session identifier.
void IToiMediaSession::GetParameter ( in string  name,
out string  value 
) raises (TToiInvalidArgumentException, TToiSessionViolationException) [inherited]

Get the current value of a parameter.

Parameters:
name Name of the requested parameter.
Return values:
value The value of the parameter.
Exceptions:
TToiInvalidArgumentException If no parameter with this name can be found an invalid argument exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IToiMediaSession::GetState ( out TToiState  state  )  [inherited]

Returns the current state of the media session.

Return values:
state The current session state.
Exceptions:
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IToiMediaSession::GetStreamInfo ( out TToiStreamInfo  info  )  raises (TToiNoDataException, TToiSessionViolationException) [inherited]

Returns information about the stream handled by the session.

Return values:
info Information about the stream.
Exceptions:
TToiNoDataException If no information is yet available an no data exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IToiMediaSession::GetType ( out TToiSessionType  type  )  raises (TToiSessionViolationException) [inherited]

Get the session type bitmask. Note that a session can combine the different type constants.

Return values:
type The type of the session, e.g. TYPE_PLAYER. This field is a bitmask.
Exceptions:
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IToiMediaSession::GetUrl ( out string  url  )  raises (TToiSessionViolationException) [inherited]

Get the source URL of the session.

Return values:
url The source URL of the session.
Exceptions:
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IToiMediaSession::RegisterObserver ( in IToiApplicationService::TToiApplicationId  applicationId,
in string  address 
) raises (TToiInvalidArgumentException) [inherited]

Register an observer of type IToiMediaSessionObserver. The observer will receive events sent by this IToiMediaSession instance.

Parameters:
applicationId The identifier of the observing application.
address The address where the IToiMediaSession can find an IToiMediaSessionObserver 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:
IToiMediaSessionObserver
void IMediaSession::RegisterObserverInternal ( in string  address  )  raises (TToiInvalidArgumentException)

Adds a media service observer. Observers are notified about session-related events.

Parameters:
address IPC address to an observer that implements the IToiMediaSessionObserver interface.
Exceptions:
TToiInvalidArgumentException Raised if the specified address is not a legal IPC address.
See also:
ReleaseObserver(), IToiMediaSessionObserver
void IToiMediaSession::ReleaseInstance (  )  [inherited]

This method releases the resources used by this object and removes all registered observers. Upon return this object will no longer be available and must not be called.

Note that this method does not close the associated session. This can only be done by calling IToiMediaPlayer::Close() or IToiMediaRecorder::Close().

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

Release an observer previously registered with RegisterObserver.

Parameters:
address The address where the IToiMediaSession can find the registered IToiMediaSessionObserver interface.
Exceptions:
TToiInvalidArgumentException Raised if the specified address is invalid.
See also:
IToiMediaSessionObserver
void IToiMediaSession::RemoveDataRelay ( in long  dataRelayId  )  raises (TToiInvalidArgumentException, TToiSessionViolationException) [inherited]

Remove a previously added data relay.

Parameters:
dataRelayId The identifier of the data relay to be removed.
Exceptions:
TToiInvalidArgumentException If the data relay identifier does not exist an invalid argument exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
See also:
AddPacketDataRelay()
AddSectionDataRelay()
void IMediaSession::Resume ( in long  type,
in string  reason 
) raises (TToiOperationNotSupportedException, TToiSessionViolationException)

Resumes one or more roles of a session.

Parameters:
type Bit mask indicating which role(s) that shall be resumed, only valid for recorder.
reason The reason for resuming. Should be a value from ToiMediaReasonNames.h
Exceptions:
TToiOperationNotSupportedException If the session cannot cancel the requested types an operation not supported exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IToiMediaSession::SetDecryptionCipher ( in TToiStreamIdSequence  streamIds,
in TToiCipher  cipher,
in TToiCipherBlockMode  blockMode,
in TToiCipherResidueMode  residueMode 
) raises (TToiOperationNotSupportedException, TToiSessionViolationException) [inherited]

Set cipher mode on stream identifiers to prepare them for use of SetDecryptionKeys().

If a license is no longer valid it is possible to immediately disable decryption by setting the cipher to CIPHER_NONE.

Parameters:
streamIds The identifiers of the stream to be decrypted with the specified cipher.
cipher The cipher to use.
blockMode The cipher block mode to use.
residueMode The cipher residue mode to use.
Exceptions:
TToiOperationNotSupportedException If the requested cipher is not supported by the implementation an operation not supported exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
See also:
SetDecryptionKeys()
void IToiMediaSession::SetDecryptionKeys ( in TToiStreamIdSequence  streamIds,
in boolean  isEncrypted,
in TToiCipherData  evenKey,
in TToiCipherData  evenIv,
in TToiCipherData  oddKey,
in TToiCipherData  oddIv,
in long  length 
) raises (TToiOperationNotSupportedException, TToiSessionViolationException) [inherited]

Set keys to be used for stream decryption. Before calling this method the cipher mode must be set with SetDecryptionCipher().

Parameters:
streamIds The identifiers of the stream to be decrypted.
isEncrypted Flag indicating whether the keys passed to this function are encrypted.
evenKey The even key. Leave empty if only odd key is set.
evenIv The even initialization vector. Leave empty to use an IV with just zeroes, also leave empty if IV is not applicable.
oddKey The odd key. Leave empty if only even key is set.
oddIv The odd initialization vector. Leave empty to use an IV with just zeroes, also leave empty if IV is not applicable.
length The length of the key and IV.
Exceptions:
TToiOperationNotSupportedException If the length of the keys are not consistent with the selected cipher mode an operation is not supported exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
See also:
SetDecryptionCipher()
void IMediaSession::SetEncryptionData ( in binary  keyMaterial,
in long  keyMaterialLength,
in binary  markerToken,
in long  markerTokenLength,
in TCipherKeyParity  keyParity 
) raises (TToiSessionViolationException)

Set keys IPRM keys material and marker token that is used for local encryption.

Parameters:
keyMaterial Data used to derive a key for encryption. The format is defined by IPRM.
keyMaterialLength Length of keyMaterial
markerToken Data indicating which CCI to be used at a certain position in the stream. The format is defined by IPRM.
markerTokenLength Length of markerToken
keyParity Indicates key parity, odd or even.
Exceptions:
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IToiMediaSession::SetParameter ( in string  name,
in string  value 
) raises (TToiInvalidArgumentException, TToiSessionViolationException) [inherited]

Set the current value of a parameter.

Parameters:
name Name of the parameter.
Return values:
value The value to be set to parameter.
Exceptions:
TToiInvalidArgumentException If no parameter with this name can be found an invalid argument exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IToiMediaSession::SubscribeParameter ( in string  address,
in string  name 
) raises (TToiInvalidArgumentException, TToiSessionViolationException) [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 IToiMediaSessionObserver::OnParameterChanged() if there is a value available.

Parameters:
address The observer address of the parameter that is subscribed.
name The name of the subscribed parameter.
Exceptions:
TToiInvalidArgumentException If the parameter name is invalid or not recognized an invalid argument exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
See also:
UnsubscribeParameter()
void IMediaSession::Suspend ( in long  type,
in string  reason 
) raises (TToiOperationNotSupportedException, TToiSessionViolationException)

Suspends one or more roles of a session.

Parameters:
type Bit mask indicating which role(s) that shall be suspended, only valid for recorder.
reason The reason for suspending. Should be a value from ToiMediaReasonNames.h
Exceptions:
TToiOperationNotSupportedException If the session cannot cancel the requested types an operation not supported exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
void IToiMediaSession::UnsubscribeParameter ( in string  address,
in string  name 
) raises (TToiInvalidArgumentException, TToiSessionViolationException) [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 unsubscribed parameter.
Exceptions:
TToiInvalidArgumentException If the parameter name is invalid or not recognized an invalid argument exception is raised.
TToiSessionViolationException If the session no longer exist an session violation exception is raised.
See also:
SubscribeParameter()

Member Data Documentation

Session is used for consuming a stream.

This constant can also be accessed from toi.consts.IToiMediaSession.TYPE_CONSUMER.

Session is used for distributing a stream to other network devices.

This constant can also be accessed from toi.consts.IToiMediaSession.TYPE_DISTRIBUTOR.

Session is used for playing a stream.

This constant can also be accessed from toi.consts.IToiMediaSession.TYPE_PLAYER.

Session is used for recording a stream.

This constant can also be accessed from toi.consts.IToiMediaSession.TYPE_RECORDER.