### 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.

~IMMPlayableDevice

      public:
      virtual ~IMMPlayableDevice()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

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.

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

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.

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

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

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.

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.

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

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.

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

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

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

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

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.

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

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

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

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

  -     virtual ~IMMDevice()

  -     virtual IMMDevice&
          acquire( ShareMode acquire = shareable,
                   bool queuedForResources = false,
                   CallType call = wait )

  -     IString aliasName() const

  -     virtual IMMDevice& close(CallType call = wait)

  -     unsigned long
          connectedDeviceId( ConnectorType type,
                             CallType call = wait ) const

  -     virtual IMMDevice&
          deletePendingEvents( EventType event = allEvents )

  -     IString description(CallType call = wait) const

  -     unsigned long deviceId() const

  -     IString deviceName() const

  -     unsigned long deviceType(CallType call = wait) const

  -     virtual IMMDevice&
          disableAudio( AudioChannel channel = all,
                        const IMMMillisecondTime& over = IMMMillisecondTime ( ),
                        CallType call = wait )

  -     virtual IMMDevice&
          disableConnector( ConnectorType type,
                            CallType call = wait )

  -     virtual IMMDevice&
          enableAudio( bool enable = true,
                       AudioChannel channel = all,
                       const IMMMillisecondTime& over = IMMMillisecondTime ( ),
                       CallType call = wait )

  -     virtual IMMDevice&
          enableConnector( ConnectorType type,
                           bool enable = true,
                           CallType call = wait )

  -     virtual IMMDevice& enableNotification(bool enabled = true)

  -     bool isAcquired(CallType call = wait) const

  -     bool
          isAudioEnabled( AudioChannel channel = all,
                          CallType call = wait )

  -     bool isCloseOnDestroy() const

  -     bool
          isConnectionSupported( ConnectorType type,
                                 CallType call = wait ) const

  -     bool
          isConnectorEnabled( ConnectorType type,
                              CallType call = wait ) const

  -     bool isOpen() const

  -     virtual Mode mode(CallType call = wait) const

  -     virtual IMMDevice&
          open( const IString& fileOrDevice = IString ( ),
                bool shareable = true,
                CallType call = wait )

  -     virtual IMMDevice&
          openOnThread( const IString& fileOrDevice = IString ( ),
                        bool shareable = true,
                        CallType call = wait )

  -     IMMTime prerollTime(CallType call = wait) const

  -     PrerollType prerollType(CallType call = wait) const

  -     virtual IMMDevice& release(CallType call = wait)

  -     bool requiresFiles(CallType call = wait) const

  -     IMMDevice& setCloseOnDestroy(bool close = true)

  -     virtual IMMDevice&
          setSpeedFormat( IMMSpeed::Format format,
                          CallType call = wait )

  -     virtual IMMDevice&
          setTimeFormat( IMMTime::Format format,
                         CallType call = wait )

  -     virtual IMMDevice&
          setVolume( unsigned long volume,
                     AudioChannel channel = all,
                     const IMMMillisecondTime& over = IMMMillisecondTime ( ),
                     CallType call = wait )

  -     IMMSpeed::Format speedFormat(CallType call = wait) const

  -     bool supportsAudio(CallType call = wait) const

  -     bool
          supportsCommand( IMMNotifyEvent::Command command,
                           CallType call = wait ) const

  -     bool supportsDigitalTransfer(CallType call = wait) const

  -     bool supportsDisableEject(CallType call = wait) const

  -     bool supportsEject(CallType call = wait) const

  -     bool supportsPlay(CallType call = wait) const

  -     bool supportsRecord(CallType call = wait) const

  -     bool supportsRecordInsertion(CallType call = wait) const

  -     bool supportsSave(CallType call = wait) const

  -     bool supportsStreaming(CallType call = wait) const

  -     bool supportsVideo(CallType call = wait) const

  -     bool supportsVolumeAdjustment(CallType call = wait) const

  -     IMMTime::Format timeFormat(CallType call = wait) const

  -     virtual unsigned long
          volume( AudioChannel channel = left,
                  CallType call = wait ) const

  INotifier

  -     virtual ~INotifier()

  -     virtual INotifier& disableNotification() = 0

  -     virtual INotifier&
          enableNotification( bool enable = true ) = 0

  -     INotifier()

  -     virtual bool isEnabledForNotification() const = 0

  -     virtual INotifier&
          notifyObservers( const INotificationEvent& event ) = 0

  -     virtual INotifier&
          notifyObserversAsync( const INotificationEvent& event )

  -     const IThreadId& threadId() const

  IStandardNotifier

  -     virtual ~IStandardNotifier()

  -     virtual IStandardNotifier& disableNotification()

  -     virtual IStandardNotifier&
          enableNotification( bool enable = true )

  -     virtual bool isEnabledForNotification() const

  -     IStandardNotifier(const IStandardNotifier& copy)

  -     IStandardNotifier()

  -     virtual INotifierAddress notifierAddress() const

  -     virtual IStandardNotifier&
          notifyObservers( const INotificationEvent& anEvent )

  -     virtual IStandardNotifier&
          notifyObserversAsync( const INotificationEvent& anEvent )

  -     IStandardNotifier&
          operator =( const IStandardNotifier& aStandardNotifier )

#### Inherited Public Data

  INotifier

  -     static INotificationId const allChangesId

  -     static INotificationId const deleteId

  IMMDevice

  -     static const unsigned long allDevices

  -     static const unsigned long ampMixer

  -     static const unsigned long animation

  -     static const unsigned long audioCD

  -     static const unsigned long audioTape

  -     static const unsigned long cdxa

  -     static INotificationId const commandNotifyId

  -     static INotificationId const cuePointId

  -     static const unsigned long dat

  -     static INotificationId const deviceEventId

  -     static const unsigned long digitalVideo

  -     static const unsigned long headphone

  -     static const unsigned long microphone

  -     static const unsigned long monitor

  -     static const unsigned long other

  -     static const unsigned long overlay

  -     static INotificationId const passDeviceId

  -     static INotificationId const positionChangeId

  -     static const unsigned long sequencer

  -     static const unsigned long speaker

  -     static const unsigned long videoDisc

  -     static const unsigned long videoTape

  -     static const unsigned long waveAudio

#### Inherited Protected Functions

  IStandardNotifier

  -     virtual IStandardNotifier&
          addObserver( IObserver& observer,
                       const IInterest& interest )

  -     virtual IStandardNotifier&
          notifyObservers( const INotificationId& nId )

  -     virtual IObserverList&
          observerList( const IInterest* anInterest = 0 ) const

  -     virtual IStandardNotifier& removeAllObservers()

  -     virtual IStandardNotifier&
          removeObserver( IObserver& observer )

  -     virtual IStandardNotifier&
          removeObserver( IObserver& observer,
                          const IInterest& interest )

  INotifier

  -     virtual INotifier&
          addObserver( IObserver& observer,
                       const IInterest& interest )

  -     virtual INotifier&
          notifyObservers( const INotificationId& id ) = 0

  -     virtual IObserverList&
          observerList( const IInterest* anInterest = 0 ) const = 0

  -     virtual INotifier& removeAllObservers() = 0

  -     virtual INotifier&
          removeObserver( IObserver& observer,
                          const IInterest& interest )

  -     virtual INotifier& removeObserver(IObserver& observer) = 0

  IMMDevice

  -     IMMMessageWindow& deviceWindow() const

  -     IMMDevice( unsigned long deviceIdentifier,
                   const IString& newAlias = IString ( ) )

  -     IMMDevice(const IString& fileOrDevice)

  -     virtual bool
          isOpenStringValid( const IString& deviceName ) const

  -     unsigned long
          itemCapability( unsigned long item,
                          CallType call ) const

  -     unsigned long
          itemStatus( unsigned long item,
                      unsigned long value = 0,
                      CallType call = wait ) const

  -     unsigned long lastError() const

  -     virtual bool
          mixerControlValues( unsigned long dwComponentType,
                              unsigned long dwControlType,
                              unsigned short* usDetails,
                              bool uniform = true,
                              unsigned long multipleItems = 0,
                              unsigned long hmx = NULL )

  -     virtual bool
          mixerControlValues( unsigned long dwComponentType,
                              unsigned long dwControlType,
                              unsigned long* ulDetails,
                              bool uniform = true,
                              unsigned long multipleItems = 0,
                              unsigned long hmx = NULL )

  -     IMMDeviceNotifyHandler* notificationHandler() const

  -     virtual IMMDevice&
          open( unsigned long instanceNumber,
                bool shareable = true,
                CallType call = nowait )

  -     virtual IMMDevice&
          openOnThread( unsigned long instanceNumber,
                        bool shareable = true )

  -     OpenStatus openStatus() const

  -     virtual IMMDevice&
          restoreDeviceSettings( bool newRecordMode = false )

  -     virtual IMMDevice& saveDeviceSettings()

  -     IString sendCommand(const IString& command)

  -     IMMDevice&
          sendCommand( unsigned short message,
                       unsigned long param1,
                       void* param2,
                       unsigned short userParm )

  -     IMMDevice&
          sendCommand( unsigned short message,
                       unsigned long param1,
                       void* param2 )

  -     IString
          sendCommand( const IString& command,
                       unsigned short userParm )

  -     IMMDevice& setLastError(unsigned long errorId)

  -     virtual bool
          setMixerControlValues( unsigned long dwComponentType,
                                 unsigned long dwControlType,
                                 unsigned short* usDetails,
                                 bool uniform = true,
                                 unsigned long multipleItems = 0,
                                 unsigned long hmx = NULL )

  -     virtual bool
          setMixerControlValues( unsigned long dwComponentType,
                                 unsigned long dwControlType,
                                 unsigned long* ulDetails,
                                 bool uniform = true,
                                 unsigned long multipleItems = 0,
                                 unsigned long hmx = NULL )

  -     IMMDevice&
          setNotificationHandler( IMMDeviceNotifyHandler* notifyHandler )

  -     IMMDevice& setOpenStatus(OpenStatus status)

  -     IMMDevice& setPassDeviceRequested(bool sawPassDevice)

  -     IMMDevice& setSystemMixerHandle(unsigned long hmx)

  -     IMMDevice& setUserParameter(unsigned short userParm = 0)

  -     unsigned long systemMixerHandle() const

  -     unsigned short userParameter() const

  -     bool wasPassDeviceRequested() const

#### Inherited Protected Data

  - None