Isomet Modular Synthesiser (iMS) API
v1.4.2
iMS API
|
Provides a mechanism for downloading and verifying Images to a Controller's memory. More...
#include <include\ImageOps.h>
Public Member Functions | |
Constructor & Destructor | |
ImageDownload (IMSSystem &ims, const Image &img) | |
Constructor for ImageDownload Object. More... | |
~ImageDownload () | |
Destructor for ImageDownload 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 | ImageDownloadEventSubscribe (const int message, IEventHandler *handler) |
Subscribe a callback function handler to a given ImageDownloadEvents entry. More... | |
void | ImageDownloadEventUnsubscribe (const int message, const IEventHandler *handler) |
Unsubscribe a callback function handler from a given ImageDownloadEvent. More... | |
Provides a mechanism for downloading and verifying Images to a Controller's memory.
Constructor for ImageDownload Object.
The pre-requisites for an ImageDownload object to be created are: (1) - an IMSSystem object, representing the configuration of an iMS target to which the Image is to be downloaded. (2) - a complete Image object to download to the iMS target.
ImageDownload stores const references to both. This means that both must exist before the ImageDownload object, and both must remain valid (not destroyed) until the ImageDownload object itself is destroyed. Because they are stored as references, the IMSSystem and Image objects themselves may be modified after the construction of the ImageDownload object.
Once constructed, the object can neither be copied or assigned to another instance.
[in] | ims | A reference to the iMS System which is the target for downloading the Image |
[in] | img | A const reference to the Image which shall be downloaded to the target |
|
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.
Implements iMS::IBulkTransfer.
void iMS::ImageDownload::ImageDownloadEventSubscribe | ( | const int | message, |
IEventHandler * | handler | ||
) |
Subscribe a callback function handler to a given ImageDownloadEvents entry.
ImageDownload can callback user application code when an event occurs in the download process. Supported events are listed under ImageDownloadEvents. 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 ImageDownloadEvents entry. For the period that a callback is subscribed, each time an event in ImageDownload occurs that would trigger the subscribed ImageDownloadEvents entry, the user function callback will be executed.
[in] | message | Use the ImageDownloadEvents::Event enum to specify an event to subscribe to |
[in] | handler | A function pointer to the user callback function to execute on the event trigger. |
void iMS::ImageDownload::ImageDownloadEventUnsubscribe | ( | const int | message, |
const IEventHandler * | handler | ||
) |
Unsubscribe a callback function handler from a given ImageDownloadEvent.
Removes all links to a user callback function from the Event Trigger map so that any events that occur in the ImageDownload object following the Unsubscribe request will no longer execute that function
[in] | message | Use the ImageDownloadEvent::Event enum to specify an event to unsubscribe from |
[in] | handler | A function pointer to the user callback function that will no longer execute on an event |
|
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.
Implements iMS::IBulkTransfer.
|
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.
Implements iMS::IBulkTransfer.