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

Provides a mechanism for downloading and verifying Compensation Tables to a Synthesiser's Look-Up memory. More...

#include <include\Compensation.h>

Inheritance diagram for iMS::CompensationTableDownload:
Inheritance graph
[legend]
Collaboration diagram for iMS::CompensationTableDownload:
Collaboration graph
[legend]

Public Member Functions

Constructor & Destructor
 CompensationTableDownload (IMSSystem &ims, const CompensationTable &tbl)
 Constructor for CompensationTableDownload Object. More...
 
 ~CompensationTableDownload ()
 Destructor for CompensationTableDownload Object.
 
Bulk Transfer Initiation
bool StartDownload ()
 Initiates a Bulk Transfer download. More...
 
bool StartVerify ()
 Initiates a Bulk Transfer verify. More...
 
Retrieve Error Information
int GetVerifyError ()
 Returns the address of the next verify error or -1 if none. More...
 
Event Notifications
void CompensationTableDownloadEventSubscribe (const int message, IEventHandler *handler)
 Subscribe a callback function handler to a given CompensationEvents entry. More...
 
void CompensationTableDownloadEventUnsubscribe (const int message, const IEventHandler *handler)
 Unsubscribe a callback function handler from a given CompensationEvents entry. More...
 
Store in Synthesiser Non-Volatile Memory
const FileSystemIndex Store (FileDefault def, const std::string &FileName) const
 Store Table contents to non-volatile memory on the synthesiser. More...
 

Detailed Description

Provides a mechanism for downloading and verifying Compensation Tables to a Synthesiser's Look-Up memory.

Author
Dave Cowan
Date
2015-11-11
Since
1.0

Constructor & Destructor Documentation

iMS::CompensationTableDownload::CompensationTableDownload ( IMSSystem ims,
const CompensationTable tbl 
)

Constructor for CompensationTableDownload Object.

The pre-requisites for an CompensationTableDownload object to be created are: (1) - an IMSSystem object, representing the configuration of an iMS target to which the CompensationTable is to be downloaded. (2) - a complete CompensationTable object to download to the iMS target.

CompensationTableDownload stores const references to both. This means that both must exist before the CompensationTableDownload object, and both must remain valid (not destroyed) until the CompensationTableDownload object itself is destroyed. Because they are stored as references, the IMSSystem and CompensationTable objects themselves may be modified after the construction of the CompensationTableDownload object.

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

Parameters
[in]imsA const reference to the iMS System which is the target for downloading the Image
[in]tblA const reference to the CompensationTable which shall be downloaded to the target
Since
1.0

Member Function Documentation

void iMS::CompensationTableDownload::CompensationTableDownloadEventSubscribe ( const int  message,
IEventHandler handler 
)

Subscribe a callback function handler to a given CompensationEvents entry.

CompensationTableDownload can callback user application code when an event occurs in the download process. Supported events are listed under CompensationEvents. The callback function must inherit from the IEventHandler interface and override its EventAction() method.

Use this member function call to subscribe a callback function to an CompensationEvents entry. For the period that a callback is subscribed, each time an event in CompensationTableDownload occurs that would trigger the subscribed CompensationEvents entry, the user function callback will be executed.

Parameters
[in]messageUse the CompensationEvents::Event enum to specify an event to subscribe to
[in]handlerA function pointer to the user callback function to execute on the event trigger.
Since
1.0
void iMS::CompensationTableDownload::CompensationTableDownloadEventUnsubscribe ( const int  message,
const IEventHandler handler 
)

Unsubscribe a callback function handler from a given CompensationEvents entry.

Removes all links to a user callback function from the Event Trigger map so that any events that occur in the CompensationTableDownload object following the Unsubscribe request will no longer execute that function

Parameters
[in]messageUse the CompensationEvents::Event enum to specify an event to unsubscribe from
[in]handlerA function pointer to the user callback function that will no longer execute on an event
Since
1.0
int iMS::CompensationTableDownload::GetVerifyError ( )
virtual

Returns the address of the next verify error or -1 if none.

After the application has been notified of a failed verify, it can probe the BulkTransfer derived object to obtain the approximate address at which the BulkTransfer failed. The address is provided as a byte offset from the start of the BulkTransfer binary object.

Due to the way in which the BulkTransfer mechanism splits the transfer into individual messages, there will be one error recorded for each message that results in a verify fail. Therefore, the address will only be approximate, to the nearest message size boundary and if there are multiple byte fails within the scope of a single message, only one error will be recorded.

Calling this function repeatedly will result in returning the next recorded verify error. If there are no errors left, or the transfer was successful (i.e. there were no verify failures recorded) the function will return -1.

Returns
byte address of transfer failure or -1 if none.
Since
1.0

Implements iMS::IBulkTransfer.

bool iMS::CompensationTableDownload::StartDownload ( )
virtual

Initiates a Bulk Transfer download.

If the user has subscribed to the relevant event notifications, the BulkTransfer derived object will issue a completion event at the end of the download process and will also warn the user anytime a download messaging error occurs.

Returns
Boolean indicating whether Download has started successfully
Since
1.0

Implements iMS::IBulkTransfer.

bool iMS::CompensationTableDownload::StartVerify ( )
virtual

Initiates a Bulk Transfer verify.

If the user has subscribed to the relevant event notifications, the BulkTransfer derived object will raise an event to the application at the end of the verify process to indicate whether the verification was successful or not.

Returns
Boolean indicating whether Verify has started successfully
Since
1.0

Implements iMS::IBulkTransfer.

const FileSystemIndex iMS::CompensationTableDownload::Store ( FileDefault  def,
const std::string &  FileName 
) const

Store Table contents to non-volatile memory on the synthesiser.

The contents of this CompensationTable can be stored to an area of non-volatile memory on the Synthesiser for retrieval at a future time, including after subsequent power cycles. The data stored can be used to select between alternative CompensationTables (e.g. for different AOD crystal materials) without needing to recalculate or download from Software.

The table can be flagged to be used as a default at startup in which case the Synthesiser will use the contents as a default LUT program allowing the Synthesiser to be used with no connection to a host system.

Parameters
[in]defmark the entry as a default and the Synthesiser will attempt to program the data to the Local Tone Buffer on power up.
[in]FileNamea string to tag the download with in the File System Table (limited to 8 chars)
Returns
the index in the File System Table where the data was stored or -1 if the operation failed
Since
1.1

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