Container of input devices for input drivers and resources. More...

#include <MpInputDeviceManager.h>

Collaboration diagram for MpInputDeviceManager:

Public Member Functions

Creators

MpInputDeviceManager (unsigned defaultSamplesPerFrame, unsigned defaultSamplesPerSecond, unsigned defaultNumBufferedFrames, MpBufPool &bufferPool)

Default constructor. More...

virtual ~MpInputDeviceManager ()

Destructor. More...

Manipulators

MpInputDeviceHandle addDevice (MpInputDeviceDriver &newDevice)

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

MpInputDeviceDriver * removeDevice (MpInputDeviceHandle deviceId)

Remove an existing input device. More...

int removeAllDevices ()

OsStatus setupDevice (MpInputDeviceHandle deviceId, uint32_t samplesPerFrame=0, uint32_t samplesPerSec=0)

Set device parameters before enabling it. More...

OsStatus enableDevice (MpInputDeviceHandle deviceId)

Helper to enable device driver. More...

OsStatus disableDevice (MpInputDeviceHandle deviceId)

Helper to disable device driver. More...

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

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

OsStatus pushFrame (MpInputDeviceHandle deviceId, unsigned numSamples, MpAudioSample *samples, MpFrameTime frameTime)

Method for MpInputDeviceDriver to push a frame of media for a given time. More...

OsStatus getFrame (MpInputDeviceHandle deviceId, MpFrameTime &frameTime, MpBufPtr &buffer, unsigned &numFramesBefore, unsigned &numFramesAfter)

Method for obtaining the buffer for a given frame and device ID. More...

Accessors

OsStatus getDeviceName (MpInputDeviceHandle deviceId, UtlString &deviceName) const

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

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

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

MpFrameTime getCurrentFrameTime (MpInputDeviceHandle deviceId) const

Get current frame timestamp. More...

OsStatus getDeviceSamplesPerSec (MpInputDeviceHandle deviceId, uint32_t &samplesPerSec) const

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

OsStatus getDeviceSamplesPerFrame (MpInputDeviceHandle deviceId, uint32_t &samplesPerFrame) const

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

OsStatus getTimeDerivatives (MpInputDeviceHandle deviceId, unsigned &nDerivatives, double *&derivativeBuf) const

Method for obtaining the time derivatives for sequential frames. More...

OsMsgDispatcher * getNotificationDispatcher ()

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

OsStatus addNotificationDispatcher (OsMsgDispatcher *notifyDispatcher)

Add a 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 (MpInputDeviceHandle deviceId) const

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

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

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

Private Attributes
OsRWMutex	mRwMutex

MpInputDeviceHandle	mLastDeviceId

unsigned	mDefaultSamplesPerFrame

unsigned	mDefaultSamplesPerSecond

unsigned	mDefaultNumBufferedFrames

MpBufPool *	mpBufferPool

UtlSList	mNotifiers

UtlHashMap	mConnectionsByDeviceName

UtlHashBag	mConnectionsByDeviceId

OsTime	mTimeZero

Detailed Description

Container of input devices for input drivers and resources.

The MpInputDeviceManager is a container of input device drivers and provides the media frame collector and accessor for MprFromInputDevice resources. MpInputDeviceDriver instances are added to the MpInputDeviceManager and removed from it by external entities, using addDevice() and removeDevice(). Enabled MpInputDeviceDrivers push frames of media on to the connection indicated by the device ID. The MpInputDeviceManager queues the media frames to be accessible by MprFromInputDevice resources via the getFrame method. The specific device driver is accessed by the device ID or handle. The MpInputDeviceManager maintains a device ID to device name mapping. All device IDs and device names are unique within the scope of this MpInputDeviceManager. The device ID provides a level of indirection that allows the MpInputDeviceManager to protect against access of transient devices.

MpInputDeviceManager allows multiple MprFromInputDevice resources to read a frame of media via the getFrame method. Each resource gets its own copy of an MpBuf.

MpInputDeviceDrivers invoke the pushFrame method to provide frames of media for a specific device ID. The MpInputDeviceManager maintains a simple queue of frames for a short window of time. It is the MprFromInputDevice resource's (or other consumer invoking getFrame) responsibility to decide how far behind (buffer latency) the current frame to maintain within the configured window of frames buffered.

The MpInputDeviceManager uses MpAudioInputConnection internally to map the association between MpInputDeviceDrivers and device ID. The MpAudioInputConnection also maintains the buffered media frames for a device for a configured window of time.

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

MpInputDeviceManager	(	unsigned	defaultSamplesPerFrame,
		unsigned	defaultSamplesPerSecond,
		unsigned	defaultNumBufferedFrames,
		MpBufPool &	bufferPool
	)

Default constructor.

Parameters

defaultSamplesPerFrame	- (in) the default number of samples in a frame of media to be used when enabling devices.
defaultSamplesPerSecond	- (in) default sample rate for media frame in samples per second to be used when enabling devices.
defaultNumBufferedFrames	- (in) default number of frames to buffer for a device before releasing the frame. Consumers of frames (callers of getFrame) have the window of time to retrieve any of the frames buffered.
bufferPool	- pool from which buffers are obtained for media data space

~MpInputDeviceManager ( )

virtual

Destructor.

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

MpInputDeviceManager ( const MpInputDeviceManager & rMpInputDeviceManager )

private

Copy constructor (not implemented for this class)

Member Function Documentation

int addDevice ( MpInputDeviceDriver & 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.

MpInputDeviceDriver * removeDevice ( MpInputDeviceHandle 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 setupDevice	(	MpInputDeviceHandle	deviceId,
		uint32_t	samplesPerFrame = `0`,
		uint32_t	samplesPerSec = `0`
	)

Set device parameters before enabling it.

Use this method if you want to set parameters different from the manager defaults. If you're happy with the manager defaults, you may omit this.

Parameters

[in]	deviceId	- (in) The device to setup.
[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.

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 enableDevice ( MpInputDeviceHandle deviceId )

Helper to enable device driver.

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

Parameters

[in] deviceId - The device to enable.

Returns: OS_NOT_FOUND if the device could not be found.

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 ( MpInputDeviceHandle deviceId )

Helper to disable device driver.

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

Parameters

[in] deviceId - 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`,
		MpInputDeviceHandle	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 pushFrame	(	MpInputDeviceHandle	deviceId,
		unsigned	numSamples,
		MpAudioSample *	samples,
		MpFrameTime	frameTime
	)

Method for MpInputDeviceDriver to push a frame of media for a given time.

This method is used to push a frame to the MpInputDeviceManager to be buffered for a short window of time during which consumers such as MpFromInputDevice can retrieve the frame via the getFrame method.

Parameters

deviceId	- (in) device id to identify from which device the frame is from.
numSamples	- (in) number of samples in the frame of media from the device. This must be the frame size number of samples that the device is configure to provide.
samples	- (in) the actual media for the frame.
frameTime	- (in) time in milliseconds for beginning of frame relative to the MpInputDeviceManager reference time.

Returns: OS_NOT_FOUND if the device could not be found.

Multi-thread safe.

OsStatus getFrame	(	MpInputDeviceHandle	deviceId,
		MpFrameTime &	frameTime,
		MpBufPtr &	buffer,
		unsigned &	numFramesBefore,
		unsigned &	numFramesAfter
	)

Method for obtaining the buffer for a given frame and device ID.

Method for obtaining the buffer for a given frame and device ID This method is typically invoked by MprFromInputDevice resources.

Parameters

deviceId	- (in) device id to identify from which device a frame is to be retrieved.
frameTime	- (in/out) time in milliseconds for beginning of frame relative to the MpInputDeviceManager reference time. If frame successfully pulled, this param would be set to frame time of this frame. You may use this value to synchronize to device driver.
buffer	- (out) frame of media to be retrieved (copied for callers context).
numFramesBefore	- (out) number of frames buffered which are newer than the frame for the requested time.
numFramesAfter	- (out) number of frames buffered which are older than the frame for the requested time.

Returns: OS_INVALID_ARGUMENT if the device id does not exist.; OS_INVALID_STATE if the frame for the requested time is not available yet and the device is not enabled.; OS_NOT_FOUND if the frame for the requested time is not available yet.

Multi-thread safe.

OsStatus getDeviceName	(	MpInputDeviceHandle	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 UtlString that will hold the deviceName

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

Multi-thread safe.

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

Get the device id for the given device driver name.

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

Parameters

deviceName	- (in) The name of a device to get the ID of.
deviceId	- (out) A place to store the ID of the device.

Returns: OS_SUCCESS and deviceId set with the ID of the device, if the device was found.; OS_NOT_FOUND and deviceId set with MP_INVALID_INPUT_DEVICE_HANDLE if the device could not be found.

Multi-thread safe.

MpFrameTime getCurrentFrameTime ( MpInputDeviceHandle deviceId ) const

Get current frame timestamp.

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

Parameters

[in] deviceId - A place to store the ID of the device.

This number will wrap roughly every 49.7 days.

Multi-thread safe.

OsStatus getDeviceSamplesPerSec	(	MpInputDeviceHandle	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	(	MpInputDeviceHandle	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.

OsStatus getTimeDerivatives	(	MpInputDeviceHandle	deviceId,
		unsigned &	nDerivatives,
		double *&	derivativeBuf
	)		const

Method for obtaining the time derivatives for sequential frames.

as relates to reference time. Calculates the derivative: (t2-t1)/(reference frame period) for sequential t1,t2 for each set of times buffered, starting from the most recent in the buffer.

Parameters

deviceId	- (in) device to get statistics for.
nDerivatives	- (in/out) number of derivatives to attempt to obtain.
derivativeBuf	- (out) an allocated buffer of at least size which will be filled with the derivatives.

Returns: contains the number of derivatives calculated and returned. If there are less than frames buffered, then the number of derivatives calculated and returned is the number of frames buffered.; OS_INVALID_ARGUMENT if the device id does not exist.

Multi-thread safe.

OsMsgDispatcher * getNotificationDispatcher ( void )

Get notifier to enable posting of notification messages.

OsStatus addNotificationDispatcher ( OsMsgDispatcher * notifyDispatcher )

Add a 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 ( MpInputDeviceHandle deviceId ) const

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

Parameters

deviceId - (in) The device to determine enabled status of.

MpInputDeviceManager& operator= ( const MpInputDeviceManager & rhs )

private

Assignment operator (not implemented for this class)

Member Data Documentation

OsRWMutex mRwMutex

mutableprivate

MpInputDeviceHandle mLastDeviceId

private

unsigned mDefaultSamplesPerFrame

private

unsigned mDefaultSamplesPerSecond

private

unsigned mDefaultNumBufferedFrames

private

MpBufPool* mpBufferPool

private

UtlSList mNotifiers

private

UtlHashMap mConnectionsByDeviceName

private

UtlHashBag mConnectionsByDeviceId

private

OsTime mTimeZero

private

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation