Isomet Modular Synthesiser (iMS) API
v1.4.2
iMS API
|
Creates iMS Connection Interfaces and scans them to discover available iMS Systems. More...
#include <include/ConnectionList.h>
Classes | |
struct | ConnectionConfig |
Controls the behaviour of a Connection Module during its discovery process. More... | |
Public Types | |
typedef std::map< std::string, ConnectionConfig > | ConnectionConfigMap |
Type of the internal object that links Connection Modules to their Configuration structs. | |
Public Member Functions | |
ConnectionList () | |
Constructor initialises the list with the connection types. | |
~ConnectionList () | |
Destructor. | |
System Discovery | |
ConnectionConfigMap & | config () |
Configure the Connection process to each supported Connection interface. More... | |
const std::list< std::string > & | modules () const |
Returns a list of string identifiers for each of the Connection Modules. More... | |
std::vector< IMSSystem > | scan () |
Probe each of the known connection types for attached iMS Systems. More... | |
Creates iMS Connection Interfaces and scans them to discover available iMS Systems.
For software to interact with an iMS system, it must first discover it on one of the supported connection types, then open a link to it.
The ConnectionList maintains a private list of modules for all the known supported connection types (USB, Ethernet, etc.). Each connection module is stored as a pointer to an object within this list and implements a common interface so that other code within the library can communicate with the iMS using the module and with no knowledge required about what type of connection is used.
The list of supported module types enabled by the ConnectionList is dependent on which platform the host application is operating on. To see which module types are supported, browse the list of modules returned by the call to modules()
:
By default, all modules are enabled to scan for iMS systems and the function call to scan()
will attempt to open a connection on every available port to the module. In this context, a "port" is a term used generically to refer to a unique point of access on which an iMS or multiple iMS's may be discovered. A module may have multiple ports. For example, the CM_ETH connection module will have one port for each network interface on the system with each interface port being recognised by its host IP address.
Application software can choose to limit the range of the ConnectionList::scan mechanism by only enabling the modules on which the application is expecting to find iMS Systems. Within a single module, the scan can be restricted further by adding a PortMask to the connection configuration. If a PortMask is defined, a module will only scan the ports that are present within it. Limiting the scope of the ConnectionList::scan in either of these ways can dramatically improve application startup time.
Once instantiated, ConnectionList can perform a scan
, which starts a discovery algorithm on each of the available enabled modules in turn. When complete, it will return an array (std::vector) of IMSSystem objects, each fully populated with the iMS configuration, model, serial number etc.
ConnectionConfigMap& iMS::ConnectionList::config | ( | ) |
Configure the Connection process to each supported Connection interface.
Returns a reference to the internal configuration map. When ConnectionList is constructed, it loads the map with Keys, one for each Connection Module supported by the platform. The Value associated with each key is a ConnectionConfig struct which by default enables iMS discovery on all available interface ports.
It is up to the user's application to restrict the scope of the scan by modifying the configuration as desired. Applications should not add Keys to or remove Keys from the configuration map.
const std::list<std::string>& iMS::ConnectionList::modules | ( | ) | const |
Returns a list of string identifiers for each of the Connection Modules.
Each Connection Module has a unique string identifier. The string identifier is used as the "Key" in the ConnectionConfigMap. This function returns a list of all the Connection Modules supported by this platform.
std::vector<IMSSystem> iMS::ConnectionList::scan | ( | ) |
Probe each of the known connection types for attached iMS Systems.
The scan()
function iterates through the list of connection types, opening a port on each in an implementation defined manner. On a successful open, it will send a sequence of query messages to identify if an iMS Controller and/or an iMS Synthesiser(s) is present. If any of the query messages results in a valid response without timing out, the function creates an IMSSystem object and begins populating the object with information it can find out about it(them) either by sending further query messages to the device or by cross-referencing a hardware database built into the library.
Once all connection types have been probed and all iMS Systems discovered, the IMSSystem objects are loaded into a vector which is returned for application processing.