Container of output devices. More...

#include <MpOutputDeviceManager.h>

Public Member Functions

Creators

MpOutputDeviceManager (unsigned defaultSamplesPerFrame, unsigned defaultSamplesPerSecond, MpFrameTime defaultMixerBufferLength)

Default constructor. More...

virtual ~MpOutputDeviceManager ()

Destructor. More...

Manipulators

MpOutputDeviceHandle addDevice (MpOutputDeviceDriver *newDevice)

Add a new input device for use. More...

MpOutputDeviceDriver * removeDevice (MpOutputDeviceHandle deviceId)

Remove an existing input device. More...

int removeAllDevices ()

OsStatus enableDevice (MpOutputDeviceHandle deviceId, MpFrameTime mixerBufferLength=0, uint32_t samplesPerFrame=0, uint32_t samplesPerSec=0)

Helper to enable device driver. More...

OsStatus disableDevice (MpOutputDeviceHandle deviceId)

Helper to disable device driver. More...

OsStatus disableAllDevicesExcept (int exceptCount=0, MpOutputDeviceHandle exceptIdArray[]=NULL)

Helper to disable all device drivers except the optional list of devices. More...

OsStatus pushFrameFirst (MpOutputDeviceHandle deviceId, MpFrameTime &frameTime, const MpBufPtr &frame, UtlBoolean initFrameTime=FALSE)

Method for sending frame of data to output device. More...

OsStatus pushFrame (MpOutputDeviceHandle deviceId, MpFrameTime frameTime, const MpBufPtr &frame)

Method for sending frame of data to output device with initialized frame time. More...

OsStatus setFlowgraphTickerSource (MpOutputDeviceHandle deviceId, OsNotification *pFlowgraphTicker)

Set device that will be used to send frame start message to media task. More...

Accessors

OsStatus getDeviceName (MpOutputDeviceHandle deviceId, UtlString &deviceName) const

Get the device driver name for the given device ID. More...

OsStatus getDeviceId (const UtlString &deviceName, MpOutputDeviceHandle &deviceId) const

Get the device id for the given device driver name. More...

OsStatus getMixerBufferLength (MpOutputDeviceHandle deviceId, MpFrameTime &length) const

Get mixer buffer length (in milliseconds) for given device. More...

MpFrameTime getCurrentFrameTime (MpOutputDeviceHandle deviceId) const

Get current frame timestamp. More...

OsStatus getDeviceSamplesPerSec (MpOutputDeviceHandle deviceId, uint32_t &samplesPerSec) const

Get the sample rate that a particular device is running at. More...

OsStatus getDeviceSamplesPerFrame (MpOutputDeviceHandle deviceId, uint32_t &samplesPerFrame) const

Get the number of samples per frame that a particular device is running at. More...

OsMsgDispatcher * getNotificationDispatcher ()

Get notifier to enable posting of notification messages. More...

OsStatus addNotificationDispatcher (OsMsgDispatcher *notifyDispatcher)

Add notifier to enable posting of notification messages. More...

OsStatus removeNotificationDispatcher (OsMsgDispatcher *notifyDispatcher)

remove given notifier to disable posting of notification messages to the notifier More...

OsStatus postNotification (const MpResNotificationMsg &msg)

Most a message to the notifer to interested parties. More...

Inquiry

Parameters

msg	- notification message to pass on to interested parties

UtlBoolean isDeviceEnabled (MpOutputDeviceHandle deviceId) const

Inquire if device is enabled (e.g. consuming media data). More...

Protected Member Functions
MpAudioOutputConnection *	findConnectionBlocking (MpOutputDeviceHandle deviceId, int tries=10) const

Private Member Functions
	MpOutputDeviceManager (const MpOutputDeviceManager &rMpOutputDeviceManager)
	Copy constructor (not implemented for this class) More...

MpOutputDeviceManager &	operator= (const MpOutputDeviceManager &rhs)
	Assignment operator (not implemented for this class) More...

Private Attributes
OsRWMutex	mRwMutex

MpOutputDeviceHandle	mLastDeviceId

unsigned	mDefaultSamplesPerFrame

unsigned	mDefaultSamplesPerSecond

MpFrameTime	mDefaultBufferLength

UtlHashMap	mConnectionsByDeviceName

UtlHashBag	mConnectionsByDeviceId

OsTime	mTimeZero

MpOutputDeviceHandle	mCurrentTickerDevice

UtlSList	mNotifiers

Detailed Description

Container of output devices.

The MpOutputDeviceManager is a container of output device drivers, serving as sink for MprToOuputDevice resources. MpOutputDeviceDriver instances are added to the MpOutputDeviceManager and removed from it by external entities, using addDevice() and removeDevice(). The specific device driver is accessed by the device ID (handle). The MpOutputDeviceManager maintains a device ID to device name mapping. All device IDs and device names are unique within the scope of this MpOutputDeviceManager. The device ID provides a level of indirection that allows the MpOutputDeviceManager to protect against access of transient devices.

MpOutputDeviceManager allows multiple MprToOutputDevice resources to send a frame of media via the pushFrame() method.

The MpOutputDeviceManager uses MpAudioOutputConnection internally to map the association between MpOutputDeviceDriver and device ID. The MpAudioInputConnection also maintains the mixer buffer.

This class is intensionally NOT a singleton so that multiple instances can be created in support of multiple instances of the media subsystem being created. Multiple instances may be useful for taking advantage of multi-processors, testing and other interesting applications.

Constructor & Destructor Documentation

MpOutputDeviceManager	(	unsigned	defaultSamplesPerFrame,
		unsigned	defaultSamplesPerSecond,
		MpFrameTime	defaultMixerBufferLength
	)

Default constructor.

Parameters

[in]	defaultSamplesPerFrame	- the default number of samples in media frame. Will be used when enabling devices.
[in]	defaultSamplesPerSecond	- default sample rate for media frame in samples per second. Will be used when enabling devices.
[in]	defaultMixerBufferLength	- default length of mixer buffer in milliseconds. Will be used when enabling devices. Mixer buffer is used to mix multiple media streams. Stream sources (callers of pushFrame()) should produce data with difference in time less, then mixer buffer length, delayed stream data would be rejected.

~MpOutputDeviceManager ( )

virtual

Destructor.

This is NOT thread safe. The invoker of this destructor MUST be sure that no connections or resources are referencing this device manager.

MpOutputDeviceManager ( const MpOutputDeviceManager & rMpOutputDeviceManager )

private

Copy constructor (not implemented for this class)

Member Function Documentation

int addDevice ( MpOutputDeviceDriver * newDevice )

Add a new input device for use.

Returns device ID which is unique within this device manager. This method locks the device manager for exclusive use.

Parameters

newDevice[in] - A new input device to add to this manager. The device should only be added to one manager.

Returns: A handle to reference the device by in other manager calls.

Multi-thread safe.

MpOutputDeviceDriver * removeDevice ( MpOutputDeviceHandle deviceId )

Remove an existing input device.

This method locks the device manager for exclusive use.

Parameters

deviceId[in] - The device to disable.

Returns: A pointer to the input device driver that was removed.; NULL if the device could not be found or device is busy.

Multi-thread safe.

int removeAllDevices ( )

Remove all the device drivers, disable them if they are not already

OsStatus enableDevice	(	MpOutputDeviceHandle	deviceId,
		MpFrameTime	mixerBufferLength = `0`,
		uint32_t	samplesPerFrame = `0`,
		uint32_t	samplesPerSec = `0`
	)

Helper to enable device driver.

This method enables the device driver indicated by the device id.

Parameters

[in]	deviceId	- The device to enable.
[in]	mixerBufferLength	(optional) - length of mixer buffer in milliseconds. Mixer buffer is used to mix multiple media streams coming to this device. Stream sources (callers of pushFrame()) should produce data with difference in time less, then mixer buffer length, because delayed stream data would be rejected. Set `mixerBufferLength` to 0 to use manager's default.
[in]	samplesPerFrame	(optional) - The samples per frame that this device should operate with. If not specified, the manager's default will be used.
[in]	samplesPerSec	(optional) - The sample rate that this device should operate at. If not specified, the manager's default will be used.

Returns: OS_NOT_FOUND if the device could not be found.; OS_INVALID_STATE if device already enabled.

This SHOULD NOT be used to mute/unmute a device. Disabling and enabling a device results in state and buffer queues being cleared.

Multi-thread safe.

OsStatus disableDevice ( MpOutputDeviceHandle deviceId )

Helper to disable device driver.

This method disables the device driver indicated by the device id.

Parameters

deviceId[in] - The device to disable.

Returns: OS_NOT_FOUND if the device could not be found.; OS_BUSY if the device is currently being removed or disabled.

This SHOULD NOT be used to mute/unmute a device. Disabling and enabling a device results in state and buffer queues being cleared.

Multi-thread safe.

OsStatus disableAllDevicesExcept	(	int	exceptCount = `0`,
		MpOutputDeviceHandle	exceptIdArray[] = `NULL`
	)

Helper to disable all device drivers except the optional list of devices.

This method diables all the devices except the given array of devices

Parameters

exceptCount[in]	number of device Ids in exceptIdArray
exceptIdArray[in]	array of devices which are not to be disabled (i.e. exceptions)

OsStatus pushFrameFirst	(	MpOutputDeviceHandle	deviceId,
		MpFrameTime &	frameTime,
		const MpBufPtr &	frame,
		UtlBoolean	initFrameTime = `FALSE`
	)

Method for sending frame of data to output device.

This method is used to push a frame to the MpOutputDeviceManager to be buffered for a short window of time and mixed with data from other contributors.

If initFrameTime is TRUE, value of frameTime is ignored and frame is pushed to the very beginning of the mixer buffer. frameTime is set to correct frame time and should be used as a base for later pushes. If initFrameTime is FALSE, frameTime should point to correct frame time.

This method is typically invoked by MprToOutputDevice resources.

Parameters

deviceId[in]	- Device id to identify device to which this frame will be sent.
frameTime[in,out]	- Time in milliseconds for beginning of frame relative to the MpOutputDeviceManager reference time.
frame[in]	- Frame of media to be sent to output device.
initFrameTime[in]	- If TRUE, frame will be pushed to the beginning of mixer buffer and `frameTime` will be set to correct frame time. If FALSE, `frameTime` will be used to determine where to push the frame.

Returns: OS_NOT_FOUND if the device could not be found.; OS_LIMIT_REACHED if mixer buffer is full, i.e. frame come too early.; OS_INVALID_STATE if frame come too late and was rejected. Frame considered late if whole frame does not fit into buffer, i.e. it would be rejected even if part of frame fit into buffer.

Multi-thread safe.

OsStatus pushFrame	(	MpOutputDeviceHandle	deviceId,
		MpFrameTime	frameTime,
		const MpBufPtr &	frame
	)

Method for sending frame of data to output device with initialized frame time.

This method may be used instead of pushFrameFirst() when frame time is initialized. Thus is does not take initFrameTime parameter and is not able to return frame time with frameTime parameter. In other aspects it is identical to pushFrameFirst().

See also: pushFrameFirst()

OsStatus setFlowgraphTickerSource	(	MpOutputDeviceHandle	deviceId,
		OsNotification *	pFlowgraphTicker
	)

Set device that will be used to send frame start message to media task.

Selected device will call MpMediaTask::signalFrameStart() method after every frame period to signal start of next frame processing interval.

Note: Note, that ticker work only when device is enabled. So do not forget to enable device after call to this function.

Parameters

[in]	deviceId	- Device id for device that will be used as ticker source. Pass MP_INVALID_OUTPUT_DEVICE_HANDLE to totally disable flowgraph ticker.
[in]	pFlowgraphTicker	- Notification to signal. Value is ignored if `deviceId` equals to MP_INVALID_OUTPUT_DEVICE_HANDLE.

Returns: OS_SUCCESS if device accepted set ticker request.; OS_NOT_FOUND if the device could not be found.; OS_FAILED if device rejected set ticker request.; OS_INVALID_STATE if current ticker source is no more available. New notification source is not set in this case.; OS_NOT_SUPPORTED if device could not provide ticker.

Multi-thread safe.

OsStatus getDeviceName	(	MpOutputDeviceHandle	deviceId,
		UtlString &	deviceName
	)		const

Get the device driver name for the given device ID.

Get the name for the given deviceId.

Parameters

deviceId[in]	- The device to fetch the name of.
deviceName[out]	- A string that will hold the device name.

Returns: OS_SUCCESS if device found and deviceName filled with the name of the device.; OS_NOT_FOUND if specified device could not be found.

Multi-thread safe.

OsStatus getDeviceId	(	const UtlString &	deviceName,
		MpOutputDeviceHandle &	deviceId
	)		const

Get the device id for the given device driver name.

The MpOutputDeviceManager maintains a device ID to device name mapping. All device IDs and device names are unique within the scope of this MpOutputDeviceManager.

Parameters

deviceName[in]	- The name of a device to get the ID of.
deviceId[out]	- A handle to reference the device by in other manager calls.

Returns: OS_SUCCESS if device found and deviceId filled in.; OS_NOT_FOUND if specified device could not be found.

Multi-thread safe.

OsStatus getMixerBufferLength	(	MpOutputDeviceHandle	deviceId,
		MpFrameTime &	length
	)		const

Get mixer buffer length (in milliseconds) for given device.

Returns: OS_SUCCESS if device found and length filled in.; OS_NOT_FOUND if specified device could not be found.

Multi-thread safe.

MpFrameTime getCurrentFrameTime ( MpOutputDeviceHandle deviceId ) const

Get current frame timestamp.

The timestamp is in milliseconds from the initial reference point in time for this device.

This number will wrap roughly every 49.7 days.

Multi-thread safe.

OsStatus getDeviceSamplesPerSec	(	MpOutputDeviceHandle	deviceId,
		uint32_t &	samplesPerSec
	)		const

Get the sample rate that a particular device is running at.

Parameters

[in]	deviceId	- The ID of the device to query.
[out]	samplesPerSec	- Filled with the indicated device's sample rate if OS_SUCCESS is returned.

Return values

OS_NOT_FOUND	if device was not able to be found.
OS_SUCCESS	if device was able to be found and sample rate was looked up.

OsStatus getDeviceSamplesPerFrame	(	MpOutputDeviceHandle	deviceId,
		uint32_t &	samplesPerFrame
	)		const

Get the number of samples per frame that a particular device is running at.

Parameters

[in]	deviceId	- The ID of the device to query.
[out]	samplesPerFrame	- Filled with the indicated device's number of samples per frame if OS_SUCCESS is returned.

Return values

OS_NOT_FOUND	if device was not able to be found.
OS_SUCCESS	if device was able to be found and number of samples per frame was looked up.

OsMsgDispatcher * getNotificationDispatcher ( void )

Get notifier to enable posting of notification messages.

OsStatus addNotificationDispatcher ( OsMsgDispatcher * notifyDispatcher )

Add notifier to enable posting of notification messages.

Returns: notify dispatcher if set

OsStatus removeNotificationDispatcher ( OsMsgDispatcher * notifyDispatcher )

remove given notifier to disable posting of notification messages to the notifier

Parameters

notifyDispatcher - handler and dispather of messages (e.g. audio device events)

OsStatus postNotification ( const MpResNotificationMsg & msg )

Most a message to the notifer to interested parties.

Parameters

notifyDispatcher - handler and dispather of messages (e.g. audio device events)

UtlBoolean isDeviceEnabled ( MpOutputDeviceHandle deviceId ) const

Inquire if device is enabled (e.g. consuming media data).

Inquire if specified device is enabled (e.g. consuming media data).

Parameters

deviceId[in] - The device to determine enabled status of.

MpAudioOutputConnection * findConnectionBlocking	(	MpOutputDeviceHandle	deviceId,
		int	tries = `10`
	)		const

protected

MpOutputDeviceManager& operator= ( const MpOutputDeviceManager & rhs )

private

Assignment operator (not implemented for this class)

Member Data Documentation

OsRWMutex mRwMutex

mutableprivate

Mutex to serialize access to connections. It is mutable, as we lock it in const methods too.

MpOutputDeviceHandle mLastDeviceId

private

unsigned mDefaultSamplesPerFrame

private

unsigned mDefaultSamplesPerSecond

private

MpFrameTime mDefaultBufferLength

private

UtlHashMap mConnectionsByDeviceName

private

UtlHashBag mConnectionsByDeviceId

private

OsTime mTimeZero

private

MpOutputDeviceHandle mCurrentTickerDevice

private

UtlSList mNotifiers

private

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation