Isomet Modular Synthesiser (iMS) API  v1.4.2
iMS API
List of all members
iMS::FileSystemManager Class Reference

Provides user management operations for working with Synthesiser FileSystems. More...

#include <include\FileSystem.h>

Public Member Functions

Constructor & Destructor
 FileSystemManager (IMSSystem &ims)
 Constructor for FileSystemManager Object. More...
 
 ~FileSystemManager ()
 Destructor for FileSystemManager object.
 
File System Operations
bool Delete (FileSystemIndex index)
 Removes the Entry indicated by the provided index from the FileSystemTable. More...
 
bool Delete (const std::string &FileName)
 
bool SetDefault (FileSystemIndex index)
 Tags a File for execution at Synthesiser startup. More...
 
bool SetDefault (const std::string &FileName)
 
bool ClearDefault (FileSystemIndex index)
 Removes the Default Flag assigned to a FileSystemTableEntry. More...
 
bool ClearDefault (const std::string &FileName)
 
bool Sanitize ()
 Reorganises the FileSystemTable and ensures it contains valid contents. More...
 
Miscellaneous Functions
bool FindSpace (std::uint32_t &addr, const std::vector< std::uint8_t > &data) const
 Locates an area in the FileSystem memory large enough to store the provided contents. More...
 
bool Execute (FileSystemIndex index)
 Causes the Synthesiser to access the FileSystem data represented by the index and execute it. More...
 
bool Execute (const std::string &FileName)
 

Detailed Description

Provides user management operations for working with Synthesiser FileSystems.

Author
Dave Cowan
Date
2016-01-21
Since
1.1

Constructor & Destructor Documentation

iMS::FileSystemManager::FileSystemManager ( IMSSystem ims)

Constructor for FileSystemManager Object.

The FileSystemManager object requires an IMSSystem object, which will have had its FileSystemTable read back during initialisation. It must therefore exist before the FileSystemManager object, and must remain valid (not destroyed) until the FileSystemManager object itself is destroyed.

Once constructed, the object can neither be copied or assigned to another instance.

Parameters
[in]imsA const reference to the iMS System whose FileSystemTable is to be operated upon.
Since
1.1

Member Function Documentation

bool iMS::FileSystemManager::ClearDefault ( FileSystemIndex  index)

Removes the Default Flag assigned to a FileSystemTableEntry.

Parameters
[in]indexthe Entry in the FST to unset as default (from 0 to MAX_FST_ENTRIES-1).
Returns
true if the default flag was unset successfully
Since
1.1
bool iMS::FileSystemManager::ClearDefault ( const std::string &  FileName)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Removes the tag indicating a file should be executed at startup referencing it by its allocated filename

Parameters
[in]FileNamea string representing the name of the file to unset as default
Returns
true if the filename was recognised and the default flag was unset successfully
Since
1.1
bool iMS::FileSystemManager::Delete ( FileSystemIndex  index)

Removes the Entry indicated by the provided index from the FileSystemTable.

The Entry is removed from the FST. The file data itself is not overwritten but once the entry has been deleted, it is impractival to recover the FileSystem data subsequently. The space 'freed up' by the deletion will become available for future file downloads and the release FST entry may be reused.

Bug:
Prior to v1.2.4 it was possible to attempt to delete an entry >= MAX_FST_ENTRIES. Doing so would have generated an exception. The condition is now checked for and the function will fail (return false) if attempted.
Parameters
[in]indexthe Entry in the FST to delete (from 0 to MAX_FST_ENTRIES-1).
Returns
true if the deletion process was carried out successfully
Since
1.1
bool iMS::FileSystemManager::Delete ( const std::string &  FileName)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Deletes a file from the FileSystemTable referencing it by its allocated filename

Parameters
[in]FileNamea string representing the name of the file to delete
Returns
true if the filename was recognised and the deletion process was carried out successfully
Since
1.1
bool iMS::FileSystemManager::Execute ( FileSystemIndex  index)

Causes the Synthesiser to access the FileSystem data represented by the index and execute it.

The execution of the FileSystem contents is defined in a FileSystemTypes specific way:

  • COMPENSATION_TABLE data is loaded into the Compensation Look-Up Table
  • TONE_BUFFER data is loaded into the Local Tone Buffer memory
  • DDS_SCRIPT data is written register at a time to the DDS IC (the User must ensure that no Image Data is currently being played back to prevent unexpected behaviour)
  • USER_DATA no action is performed
    Parameters
    [in]indexthe Entry in the FileSystemTable to operate on
    Returns
    if the Execution was started successfully.
    Since
    1.1
bool iMS::FileSystemManager::Execute ( const std::string &  FileName)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
[in]FileNamea string representing the name of the file to operate on
Since
1.1
bool iMS::FileSystemManager::FindSpace ( std::uint32_t &  addr,
const std::vector< std::uint8_t > &  data 
) const

Locates an area in the FileSystem memory large enough to store the provided contents.

Given a const reference to a byte array containing the data which the caller wants to place in FileSystem memory, this function operates an algorithm that will search through the FileSystemTable iteratively searching for the lowest possible address in memory that will fit the data in a contiguous block (since the FileSystem does not support distributed storage).

Parameters
[out]addrThe location in memory where the data may be safely stored
[in]dataa reference to a byte array representing the data which is to be stored
Returns
true if the algorithm was successful, false if no space could be found
Since
1.1
bool iMS::FileSystemManager::Sanitize ( )

Reorganises the FileSystemTable and ensures it contains valid contents.

The Sanitize process will do the following:

  • ensure only one default flag is set per filetype, clearing the flag set on any subsequent entries
  • check that valid filesystem contents is present for each entry
  • look for any filesystem contents that may overlap, removing entries that are aliased
  • Reorders the FST according to FileSystemTypes with any default marked entries placed at the front
    Returns
    true if the process completed successfully
    Since
    1.1
bool iMS::FileSystemManager::SetDefault ( FileSystemIndex  index)

Tags a File for execution at Synthesiser startup.

A single file of each file type may be marked as being the 'default' of its type. If tagged as such, the Synthesiser will attempt to execute the file during its initialisation process. All file types except USER_DATA may have a default entry.

If multiple files are marked as default, the entry with the lowest index number will take precedence. Any subsequent files marked as default will have their flags cleared during initialisation.

Parameters
[in]indexthe Entry in the FST to mark as default (from 0 to MAX_FST_ENTRIES-1).
Returns
true if the default flag was set successfully
Since
1.1
bool iMS::FileSystemManager::SetDefault ( const std::string &  FileName)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Tags a File for execution at Synthesiser startup referencing it by its allocated filename

Parameters
[in]FileNamea string representing the name of the file to mark default
Returns
true if the filename was recognised and the default flag was set successfully
Since
1.1

The documentation for this class was generated from the following file: