Class Garmin.DevicePlugin

Object
   |
   +--Garmin.DevicePlugin

class Garmin.DevicePlugin

This api provides a set of functions to accomplish the following tasks with a Gps Device:

1) Unlocking devices allowing them to be found and accessed.
2) Finding avaliable devices plugged into this machine.
3) Reading from the device.
4) Writing gpx files to the device.
5) Downloading data to the device.
6) Geting messages, getting transfer status/progress and version information from the device.

Note that the GarminPluginAPIV1.xsd is referenced throughout this API. Please find more information about the GarminPluginAPIV1.xsd from http://
Defined in GarminDevicePlugin.js

Field Detail

plugin

Object plugin

Garmin.DevicePlugin

Garmin.DevicePlugin(pluginElement)

Parameters:
gpsPluginElement - element that references the Garmin GPS Control Web Plugin that should be installed.

Returns:
a new GarminDevicePlugin

cancelDownloadData

void cancelDownloadData()

Cancel the asynchrous Download Data operation

cancelFindDevices

void cancelFindDevices()

Cancels the current find devices interaction.

cancelReadFitnessData

void cancelReadFitnessData()

Cancel the asynchronous ReadFitnessData operation

cancelReadFromGps

void cancelReadFromGps()

Cancels the current read from the device.

cancelWriteToGps

void cancelWriteToGps()

Cancels the current write operation to the gps device.

finishDownloadData

Number finishDownloadData()

This is used to indicate the status of the download process. It will return an integer know as the completion state. The purpose is to show the user information about what is happening to the plugin while it is servicing your request.

Returns:
Completion state - The completion state can be one of the following: Garmin.DevicePlugin.prototype.0 = idle;* Garmin.DevicePlugin.prototype.1 = working;* Garmin.DevicePlugin.prototype.2 = waiting;* Garmin.DevicePlugin.prototype.3 = finished;

finishFindDevices

Boolean finishFindDevices()

Poll - with this function to determine completion of startFindGpsDevices.

Returns:
Returns true if completed finding devices otherwise false. Used after the call to startFindGpsDevices().

finishReadFitnessData

Number finishReadFitnessData()

Poll for completion of the asynchronous ReadFitnessData operation. If the CompletionState is eMessageWaiting, call MessageBoxXml to get a description of the message box to be displayed to the user, and then call RespondToMessageBox with the value of the selected button to resume operation.

Returns:
Completion state - The completion state can be one of the following: Garmin.DevicePlugin.prototype.0 = idle;* Garmin.DevicePlugin.prototype.1 = working;* Garmin.DevicePlugin.prototype.2 = waiting;* Garmin.DevicePlugin.prototype.3 = finished;

finishReadFromGps

Number finishReadFromGps()

This is used to indicate the status of the read process. It will return an integer know as the completion state. The purpose is to show the user information about what is happening to the plugin while it is servicing your request. Used after startReadFromGps().

Returns:
Completion state - The completion state can be one of the following: Garmin.DevicePlugin.prototype.0 = idle;* Garmin.DevicePlugin.prototype.1 = working;* Garmin.DevicePlugin.prototype.2 = waiting;* Garmin.DevicePlugin.prototype.3 = finished;

finishWriteToGps

Number finishWriteToGps()

This is used to indicate the status of the write process. It will return an integer know as the completion state. The purpose is to show the user information about what is happening to the plugin while it is servicing your request.

Returns:
Completion state - The completion state can be one of the following: Garmin.DevicePlugin.prototype.0 = idle;* Garmin.DevicePlugin.prototype.1 = working;* Garmin.DevicePlugin.prototype.2 = waiting;* Garmin.DevicePlugin.prototype.3 = finished;

fitnessTransferSucceeded

Boolean fitnessTransferSucceeded()

Returns:
True if the last ReadFitnessData or WriteFitnessData operation succeeded

getDeviceDescriptionXml

String getDeviceDescriptionXml(deviceNumber)

Returns information about the specified Device indicated by the device Number. See getDevicesXmlString to get the actual deviceNumber assigned. See the GarminPluginAPIV1.xsd/ Devices/ Devices_t

Parameters:
Number - } - deviceNumber assigned by the plugin, see getDevicesXmlString for assignment of that number.

Returns:
Xml string with detailed device info

getDevicesXml

String getDevicesXml()

Returns information about the number of devices connected to this machine as well as the names of those devices. See the GarminPluginAPIV1.xsd/ Devices/ Devices_t The xml returned should contain a 'Device' element with 'DisplayName' and 'Number' if there is a device actually conneted.

Returns:
Xml string with detailed device info

getGpsXml

Object getGpsXml()

This is the GpsXml information from the device. Typically called after a read operation.

getMessageBoxXml

String getMessageBoxXml()

Returns:
The xml describing the message when the plug-in is waiting for input from the user.

getProgressXml

String getProgressXml()

Get the status/progress of the current state or transfer

Returns:
The xml describing the current progress state of the plug-in.

getTcdXml

Object getTcdXml()

This is the fitness data Xml information from the device. Typically called after a ReadFitnessData operation. Schemas for the TrainingCenterDatabase format are available at http://www.garmin.com/xmlschemas/TrainingCenterDatabasev2.xsd

getVersionXml

String getVersionXml()

Returns metadata information about the plugin version.

Returns:
The xml describing the user's version of the plug-in.

gpsTransferSucceeded

Boolean gpsTransferSucceeded()

Returns:
True if the last ReadFromGps or WriteToGps operation was successful

respondToMessageBox

void respondToMessageBox(response)

Responds to a message box on the device.

Parameters:
response - should be an int which corresponds to a button value from this.plugin.MessageBoxXml

startDownloadData

void startDownloadData(gpsDataString, filename, deviceNumber)

Initates downloading the gpsDataString to the device specified by deviceNumber. The gpsDataString is typically in GPI fomat and the filename is only the name without the extension. The plugin will append the .gpx extension automatically. Use finishWriteToGps to poll when the write operation/plugin is complete. Uses the helper functions to set the xml info and the filename.

Parameters:
gpsDataString - - the gpi information that should be transferred to the device.
deviceNumber - - the device number assigned by the plugin. This is necessary for the download of this .GPI files according to the GarminAxControl.idl.

startFindDevices

void startFindDevices()

Initiates a find Gps devices action on the plugin. Poll with finishFindDevices to determine when the plugin has completed this action. Use getDeviceXmlString to inspect xml contents for and array of Device nodes.

startReadFitnessData

void startReadFitnessData(deviceNumber, dataTypeName)

Start the asynchronous ReadFitnessData operation.

Parameters:
Number - } - deviceNumber assigned by the plugin, see getDevicesXmlString for assignment of that number.
String - } - a Fitness DataType from the GarminDevice.xml retrieved with DeviceDescription

startReadFromGps

void startReadFromGps(deviceNumber)

Initiates the read from the gps device conneted. Use finishReadFromGps and getGpsProgressXml to determine when the plugin is done with this operation. Also, use getGpsXml to extract the actual data from the device.

Parameters:
Number - } - deviceNumber assigned by the plugin, see getDevicesXmlString for assignment of that number.

startWriteToGps

void startWriteToGps(gpsXml, filename, deviceNumber)

Initates writing the gpsXml to the device specified by deviceNumber with a filename set by filename. The gpsXml is typically in GPX fomat and the filename is only the name without the extension. The plugin will append the .gpx extension automatically. Use finishWriteToGps to poll when the write operation/plugin is complete. Uses the helper functions to set the xml info and the filename.

Parameters:
gpsXml - - the gps/gpx information that should be transferred to the device.
filename - - the desired filename for the gpsXml that shall end up on the device.
deviceNumber - - the device number assigned by the plugin.

unlock

Boolean unlock(<String> web_path, <String> unlock_code)

Unlocks the GpsControl object to be used at the given web adress. Also takes a unlock_code that was created at the Site Key page. See documentation site for more info on getting a unlock_code.

Parameters:
web_path -
unlock_code -

Returns:
true if successfully unlocked or undefined otherwise