IMMAudioCD

The IMMAudioCD class is the audio compact disc (CD) class and provides behavior for CD audio players. Most people are familiar with a home or car CD player. So, just as for a normal CD player, there are functions for play, pause, stop, trackForward, trackBackward, scanning, and so on. Plus, there are some additional features, for example, rearranging the playback order for tracks and storing track and disc titles.


IMMAudioCD - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
IMMAudioCD


Overload 1
public:
IMMAudioCD( IProfile* profile = 0, bool openNow = true, unsigned long instance = 0, bool openShareable = true )

You can construct an IMMAudioCD from the following:

profile
You can provide your own profile where information can be retrieved and stored from. Some of the information stored in a profile is disc titles and the IMMAudioCDContents for different CDs. If you pass in 0, then the device uses the system profile for storing and retrieving information.
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 IMMAudioCD 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:
IMMAudioCD( unsigned long deviceIdentifier, const IString& newAlias = IString ( ) )

A derived class can construct an IMMAudioCD 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


Compact Disc Information

Use these members to query information and states for the CD audio device and the loaded compact disc. For example, you can query and set autoPlay and continuousPlay, and you can query the number of tracks, the disc title, the disc identifier, and the universal product code (upc).


[view class]
currentTrack
public:
unsigned long currentTrack() const

Returns the current track.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
disableAutoPlay
public:
IMMAudioCD& disableAutoPlay()

Sets autoplay off. Autoplay causes the CD audio device to start playing whenever a CD is loaded.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
disableContinuousPlay
public:
IMMAudioCD& disableContinuousPlay()

Sets continuous play off. If the continuous play is set, then the current track is repeated continuously on playback.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
discId
public:
IString discId(CallType call = wait) const

Returns the identifier of the current disc. If there is no identifier on the CD, then it returns a null IString.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
discTitle
public:
IString discTitle() const

Returns the disc title. A null IString is returned if you have not set a title.

Exception

IInvalidRequest There must be media present in the device.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
enableAutoPlay
public:
IMMAudioCD& enableAutoPlay(bool autoPlay = true)

Turns autoplay on or off. Autoplay causes the audio CD device to start playing whenever a CD is loaded.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
enableContinuousPlay
public:
IMMAudioCD& enableContinuousPlay( bool continuousPlay = true )

Turns continuous play on or off. If the continuous play is set, then the current track is repeated continuously on playback.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
isAutoPlayEnabled
public:
bool isAutoPlayEnabled() const

Returns true, if autoplay is turned on. Autoplay causes the audio CD device to start playing whenever a CD is loaded.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
isContinuousPlayEnabled
public:
bool isContinuousPlayEnabled() const

Returns true, if continuous play is turned on. If the continuous play is set, then the current track is repeated continuously on playback.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

Returns the number of tracks.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setDiscTitle
public:
IMMAudioCD& setDiscTitle(const IString& title)

Sets the disc's title. The disc title is stored in the currently set profile. See setProfile for more information on profiles.

Exception

IInvalidRequest There must be media present in the device.
IInvalidRequest The device must be in the open state before calling this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setTrackTitle
public:
IMMAudioCD& setTrackTitle( const IString& title, unsigned long track )

Sets the track's title. The track title is stored in the currently set profile. See setProfile for more information on profiles.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
trackTitle
public:
IString trackTitle(unsigned long track) const

Returns the track's title. A null IString is returned if you have not set a title for the passed-in track.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
upc
public:
IString upc(CallType call = wait) const

Returns the disc's universal product code (serial number). If the disc does not contain a upc, then a null IString is returned.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
discProgramKey
public:
static const IString discProgramKey

Contains the text string "IMMAudioCDProgramTitle". This string is used as a key to query and retrieve information from a profile.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
discTitleKey
public:
static const IString discTitleKey

This is set to the text string "IMMAudioCDDiscTitle". This string is used as a key to query and retrieve information from a profile.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Implementation

These members are overridden to provide additional processing.


[view class]
setVolume
public:
virtual IMMAudioCD& setVolume( unsigned long volume, AudioChannel channel = all, const IMMMillisecondTime& over = IMMMillisecondTime ( ), CallType call = wait )

Sets the volume of the audio channel for the device, where 0 is the least amount of volume and 100 is the most amount of volume.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Portability Considerations

This member is overridden in this derived class for specific operating system behavior.


[view class]
volume
public:
virtual unsigned long volume( AudioChannel channel = left, CallType call = wait ) const

Returns the volume of the audio channel for the device, where 0 is the least amount of volume and 100 is the most amount of volume.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Portability Considerations

This member is overridden in this derived class for specific operating system behavior.


[view class]
isOpenStringValid
protected:
virtual bool isOpenStringValid( const IString& deviceName ) const

Returns true if the passed-in open string is valid for this device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
uniqueDiscIdentifier
protected:
virtual IString uniqueDiscIdentifier() const

Returns the unique disc identifier. This value is the name of this class plus the identifier of the disc. This can be useful to use in addition to the upc, because not all manufacturers put a upc on their CDs.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Notification Event Descriptions

These INotificationId strings are used for all notifications that IMMAudioCD provides to its observers.


[view class]
positionTimerId
public:
static INotificationId const positionTimerId

Notification identifier provided to observers as the position changes. IMMAudioCD provides a pointer to an IMMTrackMinSecFrameTime in the INotificationEvent::eventData field of the INotificationEvent. This value represents the current position of the CD.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
trackStartedId
public:
static INotificationId const trackStartedId

Notification identifier provided to observers when the a new track is started. IMMAudioCD provides a pointer to an IMMTrackMinSecFrameTime in the eventData field of the INotificationEvent. This value represents the current position of the CD.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Play, Stop, and Scan

Use these members to stop playing or scanning, start scanning or playing, resume or pause the playback, or move the current position to a new location.


[view class]
goToEntry

Moves the current position to the passed in location. This location is a track number and the time into the track.


Overload 1
public:
virtual IMMAudioCD& goToEntry(unsigned long index)

Moves to the track stored in the current program at the passed-in index. If you passed in 3, it looks up the track number in the current program at that location. If you have not set your own program then the default program is used. This program is a straight mapping of the tracks; for example, at index 3, track number 3 is stored. You can set your own program. For example, you could have the following: at index 1, track 5; at index 2, track 4; and at index 3, track 6. If you passed in index 3, this function moves the current position to track number 6.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Overload 2
public:
virtual IMMAudioCD& goToEntry( IMMAudioCDContents::Cursor cursor )

Moves to the track stored in the current program at the passed-in cursor. If you passed in a cursor that points to index 3, it looks up the track number in the current program at that location. If you have not set your own program then the default program is used. This program is a straight mapping of the tracks; for example, at index 3, track number 3 is stored. You can set your own program. For example, you could have the following: at index 1, track 5; at index 2, track 4; and at index 3, track 6. If you passed in a cursor that points to index 3, this function moves the current position to track number 6.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

Pauses the audio CD device if the audio CD device is playing.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

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

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 must be media present 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 contents of the CD.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

Resumes playback of the compact disc from a paused state. 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.
IInvalidRequest There must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
startScanningBackward
public:
IMMAudioCD& startScanningBackward()

Causes the audio CD device to search backward at high speed. If the device is currently scanning backward, this function has no effect, but, if the device is currently scanning forward, this causes the scanning to stop and to start scanning backward. You can stop the scanning by calling the stop function, or, if the CD was playing when scanning started, the play function stops the scanning and resumes playback at the new location. The scanning wraps to the end when it reaches the beginning of the compact disc.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
startScanningForward
public:
IMMAudioCD& startScanningForward()

Causes the audio CD device to search forward at high speed. If the device is currently scanning forward, this function has no effect, but, if the device is currently scanning backward, this causes the scanning to stop and to start scanning forward. You can stop the scanning by calling the stop function, or, if the CD was playing when scanning started, the play function stops the scanning and resumes playback at the new location. The scanning wraps to the beginning when it reaches the end of the compact disc.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


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

Stops playback and backward or forward scanning of the compact disc.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
trackBackward
public:
IMMAudioCD& trackBackward(unsigned long decrement = 1)

Moves the current position backwards the passed-in number of tracks. If the device was playing, it starts playing at the new 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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
trackForward
public:
IMMAudioCD& trackForward(unsigned long increment = 1)

Moves the current position forwards the passed-in number of tracks. If the device was playing, it starts playing at the new 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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Profile and Program

Use these members to change and query the profile and program.


[view class]
contents
public:
IMMAudioCDContents contents() const

Returns a copy of the CD's table of contents.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
currentContentsEntry
public:
unsigned long currentContentsEntry() const

Returns the position number of the current contents.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
profile
public:
IProfile profile() const

Returns the current profile. The profile contains one or more compact disc titles and their IMMAudioCDContents. This can be useful if you want to retain a table of contents for one or more compact discs. For example, you might have a demo CD that you want to play the third track first, followed by the second, and so on. You would not want to have to rearrange the tracks every time you loaded that CD. By storing the information in a profile, the IMMAudioCD class can load that disc's information from the profile so you do not have to reenter anything.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setProfile
public:
IMMAudioCD& setProfile(IProfile& profile)

Sets a new profile. The profile contains one or more compact disc titles and their IMMAudioCDContents. This can be useful if you want to retain a table of contents for one or more compact discs. For example, you might have a demo CD that you want to play the third track first, followed by the second, and so on. You would not want to have to rearrange the tracks every time you loaded that CD. By storing the information in a profile, the IMMAudioCD class can load that disc's information from the profile so you do not have to reenter anything.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setProgram
public:
IMMAudioCD& setProgram(const IMMAudioCDContents& program)

Sets a new table of contents. The table of contents is stored in the currently set profile. The IMMAudioCD class plays and scans the compact disc according to the current table of contents. This allows you create your own table of contents for the current disc. For instance, you might want to store your compact discs (title and table of contents) in a database. Then, when you insert a CD, you could query its ID and see if it is in your database. If so, then you could retrieve your table of contents and set it into the device so that it always plays back the same way.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


Table

Use these members to query the hard-coded table of contents stored on the compact disc.


[view class]
getTableFromDisc
protected:
IMMAudioCDContents getTableFromDisc()

Generates a table of contents based on the hard-coded values stored on the compact disc. The only data stored on the compact disc are the tracks and their lengths.

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 must be media present in the device.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


IMMAudioCD - Inherited Member Functions and Data

Inherited Public Functions

IMMDevice
IMMPlayableDevice
IMMRemovableMedia
INotifier
IStandardNotifier

Inherited Public Data

INotifier
IMMDevice
IMMRemovableMedia

Inherited Protected Functions

IStandardNotifier
INotifier
IMMDevice
IMMPlayableDevice
IMMRemovableMedia

Inherited Protected Data