IMMPlayableDevice

The IMMPlayableDevice is the base class for playable devices. It provides all of the common base functions for play, pause, stop, and similar functions. There are functions for querying and moving the current position and for turning on notification to observers of position changes.


IMMPlayableDevice - Member Functions and Data by Group

Constructors & Destructor

Derived classes can use these functions to create objects of the IMMPlayableDevice class.


[view class]
~IMMPlayableDevice
public:
virtual ~IMMPlayableDevice()

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
IMMPlayableDevice


Overload 1
protected:
IMMPlayableDevice( const IString& deviceOrFileName, bool openNow = true, unsigned long instance = 0, bool openShareable = true )

A derived class can construct an IMMPlayableDevice from the following:

deviceOrFileName
You must specify what type of playable device you want to construct.
openNow
If true, it causes the device to automatically open the device before returning from the constructor; otherwise, you would have to call one of the open functions to open the device yourself.
instance
You can provide your own instance number instead of letting IMMPlayableDevice generate one.
openShareable
If true, it allows the hardware device to be shared by different programs; otherwise, the hardware cannot be shared.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
protected:
IMMPlayableDevice( unsigned long deviceIdentifier, const IString& newAlias = IString ( ) )

A derived class can construct an IMMPlayableDevice from the following:

deviceIdentifier
The value the system uses to identify the device.
newAlias
The name you can use to associate a string to the device. Optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Cue Points

Use these members to add and remove cue points.


[view class]
addCuePoint
public:
virtual IMMPlayableDevice& addCuePoint( const IMMTime& time, CallType call = wait )

Sets a cue point at the given location. A cue point is a location or time position in a media device. When a device encounters (by playing or recording) a time position associated with a cue point, a IMMCuePointEvent is generated.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The time is an invalid time value.

Supported Platforms

Windows OS/2 AIX
No Yes No


[view class]
removeCuePoint
public:
virtual IMMPlayableDevice& removeCuePoint( const IMMTime& time, CallType call = wait )

Removes the given cue point. A cue point is a location or time position in a media device. When a device encounters (by playing or recording) a time position associated with a cue point, a IMMCuePointEvent is generated.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The time is an invalid value; possibly the time value does not have a cue point set at its location.

Supported Platforms

Windows OS/2 AIX
No Yes No


Notifications

Use start and stop position tracking members to cause position change events to be generated. Use the length function to determine the amount of data and the position function to find out where you are in the data.


[view class]
length
public:
unsigned long length(CallType call = wait) const

Returns the total length in the current time format as an unsigned long. Use this value to create a time object in the current time format.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
position
public:
unsigned long position(CallType call = wait) const

Returns the current position in the current time format as an unsigned long. Use this value to create a time object in the current time format.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
startPositionTracking
public:
virtual IMMPlayableDevice& startPositionTracking( const IMMTime& timeInterval, CallType call = wait )

Starts position tracking. Position tracking causes a position change event to be generated every time the position of the media changes the passed in timeInterval.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The file is not found; possibly no file is currently loaded.
IAccessError The timeInterval is out of range; possibly the time value is past the length of the data.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Windows Considerations

Once you start position tracking for a device, you will continue to receive positionChangeEvents for that device even if it is stopped. To end position tracking, use stopPositionTracking.


[view class]
stopPositionTracking
public:
virtual IMMPlayableDevice& stopPositionTracking( CallType call = wait )

Stops position tracking. Position tracking causes a position change event to be generated every time the position of the media changes a given time amount.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Pause and Resume

Use these members to pause and resume playback.


[view class]
pause
public:
virtual IMMPlayableDevice& pause(CallType call = wait)

If the device is playing, then it pauses the device.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
resume
public:
virtual IMMPlayableDevice& resume( bool resume = true, CallType call = wait )

Resumes playback of the device from a paused state if resume is true. The previous specified to parameter in the play function remains in effect.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Play and Stop

Use these members to play or stop playback of the device. Use cueForPlayback to notify the device that you are going to start to play the device.


[view class]
cueForPlayback
public:
virtual IMMPlayableDevice& cueForPlayback( CallType call = wait )

Cues the device for playback. This function does not have to be issued before playback; however, depending on the device, it might reduce the delay associated with the play function. For example, you might have a compact disc player that stops the spinning of the CD, when it isn't playing. This function might cause the CD to start spinning, thereby reducing the time before the CD starts the playback.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IInvalidRequest There is no data present; possibly no file is loaded or no media is in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
play
public:
virtual IMMPlayableDevice& play( const IMMTime& from = IMMTime ( ), const IMMTime& to = IMMTime ( ), bool resumeIfPaused = true, CallType call = nowait )

Starts playing the device from the passed-in start position to the passed-in end position. If from is omitted, the device starts playing at the current position; if to is omitted, play stops at the end of the data. If resumeIfPaused is true and the device is paused, it resumes playback of the device; otherwise, it starts playback from the passed in start position.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IInvalidRequest There is no data present; possibly no file is loaded or no media is in the device.
IAccessError Invalid from position; possibly the from position is greater than the end position or the from position is greater than the to position.
IAccessError Invalid to position; possibly the to position is greater than the length of the data.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
stop
public:
virtual IMMPlayableDevice& stop(CallType call = wait)

Stops playback of the device.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
restoreDeviceSettings
protected:
virtual IMMPlayableDevice& restoreDeviceSettings( bool newRecordMode = false )

Restores settings for the current device. Derived classes should override this function, handle class-specific settings, and call the corresponding inherited function.

Supported Platforms

Windows OS/2 AIX
Yes No No


[view class]
saveDeviceSettings
protected:
virtual IMMPlayableDevice& saveDeviceSettings()

Saves settings for the current device. Derived classes should override this function, handle class-specific settings, and call the corresponding inherited function.

Supported Platforms

Windows OS/2 AIX
Yes No No


Seek

Use these members to seek (move the current position) to either the beginning or the ending of the data or to a particular location in the data. Also, you can use the step frame member to move a single frame forward or backward.


[view class]
seek
public:
virtual IMMPlayableDevice& seek( const IMMTime& to, CallType call = wait )

Sets the current position of the device to the passed in position.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The file is not found; possibly no file is currently loaded.
IAccessError The current device does not support the ability to seek.
IAccessError The to position is out of range; possibly it is beyond the end of the media.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
seekToEnd
public:
virtual IMMPlayableDevice& seekToEnd(CallType call = wait)

Moves the current position to the end of the data in the device.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The file is not found; possibly no file is currently loaded.
IAccessError The current device does not support the ability to seek.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
seekToStart
public:
virtual IMMPlayableDevice& seekToStart( CallType call = wait )

Moves the current position to the start of the data in the device.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError The file is not found; possibly no file is currently loaded.
IAccessError The current device does not support the ability to seek.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
stepFrame
public:
virtual IMMPlayableDevice& stepFrame( unsigned long frames = 1, bool forward = true, CallType call = wait )

Steps the play one or more time units forward or backward.

Exception

IAccessError The device identifier is not valid; possibly the device is closed.
IAccessError The device cannot acquire access to the hardware device; possibly another device of this same type was acquired for exclusive use in this or another process.
IAccessError An internal driver error occurred.
IInvalidRequest The device must be in the open state before calling this function.
IAccessError This is an unsupported function; possibly the device does not support the ability to step the player.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


IMMPlayableDevice - Inherited Member Functions and Data

Inherited Public Functions

IMMDevice
INotifier
IStandardNotifier

Inherited Public Data

INotifier
IMMDevice

Inherited Protected Functions

IStandardNotifier
INotifier
IMMDevice

Inherited Protected Data