Class Garmin.DevicePlugin

Object
   |
   +--Garmin.DevicePlugin

class Garmin.DevicePlugin

requires Prototype
Defined in GarminDevicePlugin.js

Constructor Detail

Garmin.DevicePlugin

Garmin.DevicePlugin(pluginElement)

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://

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

Returns:
a new GarminDevicePlugin

cancelDownloadData

void cancelDownloadData()

Cancel the asynchronous Download Data operation.

Minimum plugin version 2.0.0.4

See:
- startDownloadData()
- finishDownloadData()

cancelFindDevices

void cancelFindDevices()

Cancels the current find devices interaction.

Minimum plugin version 2.0.0.4

See:
- startFindDevices()
- finishFindDevices()

cancelReadFitnessData

void cancelReadFitnessData()

Cancel the asynchronous ReadFitnessData operation.

Minimum plugin version 2.1.0.3 for FitnessHistory type
Minimum plugin version 2.2.0.1 for FitnessWorkouts, FitnessUserProfile, FitnessCourses

See:
- startReadFitnessData()
- finishReadFitnessData()

cancelReadFitnessDetail

void cancelReadFitnessDetail()

Cancel the asynchronous ReadFitnessDirectory operation.

Minimum version 2.2.0.2

See:
- startReadFitnessDetail()
- finishReadFitnessDetail()

cancelReadFitnessDirectory

void cancelReadFitnessDirectory()

Cancel the asynchronous ReadFitnessDirectory operation.

Minimum plugin version 2.2.0.2

See:
- startReadFitnessDirectory()
- finishReadFitnessDirectory()

cancelReadFromGps

void cancelReadFromGps()

Cancels the current read from the device.

Minimum plugin version 2.0.0.4

See:
- startReadFromGps()
- finishReadFromGps()

cancelWriteFitnessData

void cancelWriteFitnessData()

Cancel the asynchronous ReadFitnessData operation.

Minimum plugin version 2.2.0.1

See:
- startWriteFitnessData()
- finishWriteFitnessData()

cancelWriteToGps

void cancelWriteToGps()

Cancels the current write operation to the gps device.

Minimum plugin version 2.0.0.4
Minimum plugin version 2.2.0.1 for writes of GPX to SD Card

See:
- startWriteToGps()
- finishWriteToGps()

downloadDataSucceeded

Boolean downloadDataSucceeded()

Indicates success of StartDownloadData operation.

Minimum plugin version 2.0.0.4

Returns:
True if the last StartDownloadData operation was successful

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.

Minimum plugin version 2.0.0.4

Returns:
Completion state - The completion state can be one of the following:

0 = idle
1 = working
2 = waiting
3 = finished

See:
- startDownloadData()
- cancelDownloadData()

finishFindDevices

Boolean finishFindDevices()

Poll - with this function to determine completion of startFindDevices. Used after the call to startFindDevices().

Minimum plugin version 2.0.0.4

Returns:
Returns true if completed finding devices otherwise false.

See:
- startFindDevices()
- cancelFindDevices()

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.

Minimum plugin version 2.1.0.3 for FitnessHistory type
Minimum plugin version 2.2.0.1 for FitnessWorkouts, FitnessUserProfile, FitnessCourses

Returns:
Completion state - The completion state can be one of the following:

0 = idle
1 = working
2 = waiting
3 = finished

See:
- startReadFitnessData()
- cancelReadFitnessData()

finishReadFitnessDetail

Number finishReadFitnessDetail()

Poll for completion of the asynchronous ReadFitnessDetail 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.

Minimum plugin version 2.2.0.2

Returns:
Completion state - The completion state can be one of the following:

0 = idle
1 = working
2 = waiting
3 = finished

finishReadFitnessDirectory

Number finishReadFitnessDirectory()

Poll for completion of the asynchronous ReadFitnessDirectory operation.

If the CompletionState is eMessageWaiting, call getMessageBoxXml 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.

Minimum plugin version 2.2.0.2

Returns:
Completion state - The completion state can be one of the following:

0 = idle
1 = working
2 = waiting
3 = finished

See:
- startReadFitnessDirectory()
- cancelReadFitnessDirectory()
- getMessageBoxXml()
- respondToMessageBox()

finishReadFromGps

Number finishReadFromGps()

Indicates 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().

Minimum plugin version 2.0.0.4

Returns:
Completion state - The completion state can be one of the following:

0 = idle
1 = working
2 = waiting
3 = finished

See:
- startReadFromGps()
- cancelReadFromGps()

finishWriteFitnessData

Number finishWriteFitnessData()

This is used to indicate the status of the write process for fitness data. 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.

Minimum plugin version 2.2.0.1

Returns:
Completion state - The completion state can be one of the following:

0 = idle
1 = working
2 = waiting
3 = finished

See:
- startWriteFitnessData()
- cancelWriteFitnessData()

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.

Minimum plugin version 2.0.0.4
Minimum plugin version 2.2.0.1 for writes of GPX to SD Card

Returns:
Completion state - The completion state can be one of the following:

0 = idle
1 = working
2 = waiting
3 = finished

See:
- startWriteToGps()
- cancelWriteToGps()

fitnessTransferSucceeded

Boolean fitnessTransferSucceeded()

Indicates success of ReadFitnessData or WriteFitnessData operation.

Minimum plugin version 2.1.0.3

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 the getDevicesXml function to get the actual deviceNumber assigned. Refer to the Devices_t element in the Device XML schema for what is included in the XML.

Minimum plugin version 2.0.0.4

Parameters:
deviceNumber - {Number} Assigned by the plugin, see getDevicesXml for assignment of that number.

Returns:
Xml string with detailed device info

See:
- getDevicesXml()

getDevicesXml

String getDevicesXml()

Returns information about the number of devices connected to this machine as well as the names of those devices. Refer to the Devices_t element in the Device XML schema for what is included. The xml returned should contain a 'Device' element with 'DisplayName' and 'Number' if there is a device actually connected.

Minimum plugin version 2.0.0.4

Returns:
Xml string with detailed device info

See:
- getDeviceDescriptionXml()

getGpsXml

Object getGpsXml()

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

See:
- finishReadFromGps()

getMessageBoxXml

String getMessageBoxXml()

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

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

getPluginVersion

Array getPluginVersion()

Gets the version number for the plugin the user has currently installed.

Returns:
An array of the Garmin.DevicePlugin.prototype.format = [versionMajor, versionMinor, buildMajor, buildMinor];.

getPluginVersionString

String getPluginVersionString()

Gets a string of the version number for the plugin the user has currently installed.

Returns:
A string of the format "versionMajor.versionMinor.buildMajor.buildMinor", Garmin.DevicePlugin.prototype.ex = "2.0.0.4";

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.

getSupportsFitnessDirectoryRead

Object getSupportsFitnessDirectoryRead()

Lazy-logic accessor to fitness write support var. This is used to detect whether the user's installed plugin supports fitness directory reading, which has a minimum requirement of plugin version 2.2.0.2. This should NOT be called until the plug-in has been unlocked.

getSupportsFitnessReadCompressed

Object getSupportsFitnessReadCompressed()

Lazy-logic accessor to fitness read compressed support var. This is used to detect whether the user's installed plugin supports fitness reading in compressed format, which has a minimum requirement of plugin version 2.2.0.2. This should NOT be called until the plug-in has been unlocked.

getSupportsFitnessWrite

Object getSupportsFitnessWrite()

Lazy-logic accessor to fitness write support var. This is used to detect whether the user's installed plugin supports fitness writing. Fitness writing capability has a minimum requirement of plugin version 2.2.0.1. This should NOT be called until the plug-in has been unlocked.

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://developer.garmin.com/schemas/tcx/v2/

Minimum plugin version 2.1.0.3

See:
- finishReadFitnessData()
- finishReadFitnessDirectory()
- finishReadFitnessDetail()

getTcdXmlz

Object getTcdXmlz()

Returns last read fitness xml data in compressed format. The xml is compressed as gzp and base64 expanded.

Minimum plugin version 2.2.0.2

Returns:
The read xml data in compressed gzp and base64 expanded format.

See:
- finishReadFitnessData()
- finishReadFitnessDirectory()
- finishReadFitnessDetail()

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()

Indicates success of WriteToGps operation.

Minimum plugin version 2.0.0.4

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

isUnlocked

Object isUnlocked()

Returns true if the plug-in is unlocked.

respondToMessageBox

void respondToMessageBox(response)

Responds to a message box on the device.

Minimum plugin version 2.0.0.4

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.

Minimum plugin version 2.0.0.4

Parameters:
gpsDataString - {String} the gpi information that should be transferred to the device.
filename - {String} the filename to write to on the device.
deviceNumber - {Number} the device number assigned by the plugin.

See:
- finishDownloadData()
- cancelDownloadData()

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.

Minimum plugin version 2.0.0.4

See:
- finishFindDevices()
- cancelFindDevices()

startReadFitnessData

void startReadFitnessData(deviceNumber, dataTypeName)

Start the asynchronous ReadFitnessData operation.

Minimum plugin version 2.1.0.3 for FitnessHistory type
Minimum plugin version 2.2.0.1 for FitnessWorkouts, FitnessUserProfile, FitnessCourses

Parameters:
deviceNumber - {Number} assigned by the plugin, see getDevicesXmlString for assignment of that number.
dataTypeName - {String} a fitness datatype from the Garmin Device XML retrieved with getDeviceDescriptionXml

See:
- finishReadFitnessData()
- cancelReadFitnessData()
- getDeviceDescriptionXml()
- Garmin.DeviceControl.FILE_TYPES

startReadFitnessDetail

void startReadFitnessDetail(deviceNumber, dataTypeName, dataId)

Start the asynchronous ReadFitnessDetail operation.

Minimum plugin version 2.2.0.2

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

See:
- finishReadFitnessDetail()
- cancelReadFitnessDetail()
- Garmin.DeviceControl.FILE_TYPES

startReadFitnessDirectory

void startReadFitnessDirectory(deviceNumber, dataTypeName)

Start the asynchronous ReadFitnessDirectory operation.

Minimum plugin version 2.2.0.2

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

See:
- finishReadFitnessDirectory()
- cancelReadFitnessDirectory()
- Garmin.DeviceControl.FILE_TYPES

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.

Minimum plugin version 2.0.0.4

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

See:
- finishReadFromGps()
- cancelReadFromGps()
- getDevicesXml()

startWriteFitnessData

void startWriteFitnessData(tcdXml, deviceNumber, filename, dataTypeName)

Start the asynchronous StartWriteFitnessData operation.

Minimum plugin version 2.2.0.1

Parameters:
tcdXml - {String} XML of TCD data
deviceNumber - {Number} the device number, assigned by the plugin. See getDevicesXmlString for assignment of that number.
filename - {String} the filename to write to on the device.
dataTypeName - {String} a Fitness DataType from the GarminDevice.xml retrieved with DeviceDescription

See:
- finishWriteFitnessData()
- cancelWriteFitnessData()
- Garmin.DeviceControl.FILE_TYPES

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.

Minimum plugin version 2.0.0.4
Minimum plugin version 2.2.0.1 for writes of GPX to SD Card

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

See:
- finishWriteToGps()
- cancelWriteToGps()

unlock

Boolean unlock(pathKeyPairsArray)

Unlocks the GpsControl object to be used at the given web address. More than one set of path-key pairs my be passed in, for example: ['http://myDomain.com/', 'xxx','http://www.myDomain.com/', 'yyy'] See documentation site for more info on getting a key.

Minimum plugin version 2.0.0.4

Parameters:
pathKeyPairsArray - {Array}- baseURL and key pairs.

Returns:
true if successfully unlocked or undefined otherwise