IMMFileMedia

The IMMFileMedia is the base class for devices that use files, and it provides functions for loading data from a file.


IMMFileMedia - Member Functions and Data by Group

Constructors & Destructor

Derived classes can use these members to create objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
IMMFileMedia


Overload 1
protected:
IMMFileMedia( const IString& deviceName, bool openNow, unsigned long instance, bool openShareable )

A derived class can construct an IMMFileMedia from the following:

deviceName
You must specify what 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 IMMFileMedia 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:
IMMFileMedia( unsigned long deviceIdentifier, const IString& newAlias = IString ( ) )

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


File Loading

Use these members to load a file into the device and to query information about the currently loaded file, for example, the file name and if the file was loaded as read-only.


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

Returns the currently loaded file name.

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 was not found; possibly there is no loaded file.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
isWriteable
public:
virtual bool isWriteable() const

Returns false if the file was loaded as read-only; otherwise, true is returned. If the file was loaded as read-only, then the system prevents any changes to the file. The audio driver might also be able to improve load and runtime performance as no changes are allowed. Save and record functions throw an exception if the file was loaded as read-only.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
load
public:
virtual IMMFileMedia& load( const IString& filename, bool readOnly = false, CallType call = wait )

Loads the given file into memory. If the file does not exist, a temporary file is created. Note, if call is wait , then the windowing system is tied up until the file is loaded. If you do not want to tie up of the windowing system and you do not want the load function to return until the file is loaded, use the loadOnThread function. Otherwise, you could set call to nowait, which causes this function to return immediately. When the load finishes, an INotificationEvent is sent to any observers that are attached to this device, notifying them that the load has finished.

If the file is loaded as read-only, the system prevents any changes being made to the file. The audio driver might also be able to improve load and runtime performance as no changes are allowed. Save and record functions throw an exception if the file was loaded as read-only.

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.
IAccessError Invalid media type or invalid data format.
IAccessError A hardware error occurred.
IAccessError A file attribute error occurred.
IAccessError This format is unsupported; possibly the hardware does not support the samples-per-second, the bits-per-sample, the number of channels, or the audio format.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
loadOnThread
public:
virtual IMMFileMedia& loadOnThread( const IString& filename, bool readOnly = false )

Loads the given file into memory by creating a thread to do the actual loading. By doing the loading this way, it does not tie up the windowing system. This function does not return until the file is loaded. If the file does not exist, a temporary file is created.

If the file is loaded as read-only, the system prevents any changes being made to the file. The audio driver might also be able to improve load and runtime performance as no changes are allowed. Save and record functions throw an exception if the file was loaded as read-only.

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.
IAccessError Invalid media type or invalid data format.
IAccessError A hardware error occurred.
IAccessError A file attribute error occurred.
IAccessError This format is unsupported; possibly the hardware does not support the samples-per-second, the bits-per-sample, the number of channels, or the audio format.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Windows Considerations

The Win32 MCI does not support threads, so this function behaves like load() in this environment.


[view class]
open

Opens the device.


Overload 1
public:
virtual IMMFileMedia& open( const IString& fileOrDevice = IString ( ), bool shareable = true, CallType call = wait )

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Portability Considerations

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


Overload 2
protected:
virtual IMMFileMedia& open( unsigned long instanceNumber, bool shareable = true, CallType call = nowait )

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]
openOnThread

Opens the device.


Overload 1
public:
virtual IMMFileMedia& openOnThread( const IString& fileOrDevice = IString ( ), bool shareable = true, CallType call = wait )

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Portability Considerations

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


Overload 2
protected:
virtual IMMFileMedia& openOnThread( unsigned long instanceNumber, bool shareable = true )

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Portability Considerations

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


Implementation

These members change the read-only state of the flag for the loaded file.


[view class]
enableDataUpdate
protected:
virtual IMMFileMedia& enableDataUpdate(bool update = true)

Allows the device to track read-only status of the loaded file.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
restoreDeviceSettings
protected:
virtual IMMFileMedia& 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 IMMFileMedia& 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


IMMFileMedia - Inherited Member Functions and Data

Inherited Public Functions

IMMDevice
IMMPlayableDevice
INotifier
IStandardNotifier

Inherited Public Data

INotifier
IMMDevice

Inherited Protected Functions

IStandardNotifier
INotifier
IMMDevice
IMMPlayableDevice

Inherited Protected Data