Note: This module is not intended to be used by most developers. DeviceControl, the next layer up, is recommended instead.
The DevicePlugin is the lowest-level JavaScript module in the Garmin Communicator Plugin API. DevicePlugin abstracts the underlying Windows or Mac OS X browser plugin in a system independent manner. This module wraps all browser plugin functions and exposes the XML information that the plugin sends to and receives from Garmin devices.
It allows the user to directly:
- Unlock the plugin.
- Discover devices.
- Read from and write to the device asynchronously.
Code Flow For Asynchronous Operations
In general, any plugin operation that has the potential to be time-intensive (read, write, listing, etc) is done asynchronously. DevicePlugin offers “triplet” functions that must be used in a specific order to complete these tasks. To illustrate this pattern, we’ll examine the readFromGps code flow…
This is the triplet sequence used to read data from an attached unit:
- startReadFromGps() – Starts the asynchronous read process.
- finishReadFromGps() – Returns the current completion state of the in-progress read.
- cancelReadFromGps() – Cancels the read process.
The finishXYZ() functions — like finishReadFromGps(), immediately return a completion state that will be one of the following:
0 = idle
1 = working
2 = waiting
3 = finished
Once the read has been initiated, the second step is to check the read operation’s completion state via finishReadFromGps(). You must keep polling with finishReadFromGps() and examining the returned value before you can reliably access the information that the plugin has read.
When the finishReadFromGps() returns a value of ’3′ — ‘finished’, you can safely call getGpsXml() to get the actual data.