Class Garmin.DeviceControl

Object
   |
   +--Garmin.DeviceControl

class Garmin.DeviceControl

Garmin.DeviceControl A controller object that can retrieve and send data to a Garmin device.

The controller must be unlocked before anything can be done with it. Then you'll have to find a device before you can start to read data from and write data to the device.

We use the observer pattern (http://en.wikipedia.org/wiki/Observer_pattern) to handle the asynchronous nature of device communication. You must register your class as a listener to this Object and then implement methods that will get called on certain events.

Events:

onStartFindDevices called when starting to search for devices. the object returned is {controller: this}

onCancelFindDevices is called when the controller is told to cancel finding devices {controller: this}

onFinishFindDevices called when the devices are found. the object returned is {controller: this}

onException is called when an exception occurs in a method object passed back is {msg: exception}

onInteractionWithNoDevice is called when the device is lazy loaded, but finds no devices, yet still attempts a read/write action {controller: this}

onStartReadFromDevice is called when the controller is about to start reading from the device {controller: this}

onFinishReadFromDevice is called when the controller is done reading the device. the read is either a success or failure, which is communicated via json. object passed back contains {success:this.garminPlugin.GpsTransferSucceeded, controller: this}

onWaitingReadFromDevice is called when the controller is waiting for input from the user about the device. object passed back contains: {message: this.garminPlugin.MessageBoxXml, controller: this}

onProgressReadFromDevice is called when the controller is still reading information from the device. in this case the message is a percent complete/ {progress: this.getDeviceStatus(), controller: this}

onCancelReadFromDevice is called when the controller is told to cancel reading from the device {controller: this}

onFinishWriteToDevice is called when the controller is done writing to the device. the write is either a success or failure, which is communicated via json. object passed back contains {success:this.garminPlugin.GpsTransferSucceeded, controller: this}

onWaitingWriteToDevice is called when the controller is waiting for input from the user about the device. object passed back contains: {message: this.garminPlugin.MessageBoxXml, controller: this}

onProgressWriteToDevice is called when the controller is still writing information to the device. in this case the message is a percent complete/ {progress: this.getDeviceStatus(), controller: this}

onCancelWriteToDevice is called when the controller is told to cancel writing to the device {controller: this}


Defined in GarminDeviceControl.js

Requires:

- Prototype
- BrowserDetect
- Garmin.DevicePlugin
- Garmin.Broadcaster
- Garmin.XmlConverter

Constructor Detail

Garmin.DeviceControl

Garmin.DeviceControl()

Requires:
- Prototype
- BrowserDetect
- Garmin.DevicePlugin
- Garmin.Broadcaster
- Garmin.XmlConverter

__Garmin.DeviceControl._finishInteraction

void __Garmin.DeviceControl._finishInteraction(type)

Parameters:
type - determines if we are ReadFrom or WriteTo the device

__Garmin.DeviceControl.cancelFindDevices

void __Garmin.DeviceControl.cancelFindDevices()

Cancels the current find devices interaction

__Garmin.DeviceControl.cancelReadFromDevice

void __Garmin.DeviceControl.cancelReadFromDevice()

Cancels the current read from the device

__Garmin.DeviceControl.cancelWriteToDevice

void __Garmin.DeviceControl.cancelWriteToDevice()

Cancels the current write transfer to the device

__Garmin.DeviceControl.downlaodToDevice

void __Garmin.DeviceControl.downlaodToDevice(gpiDataString, filename)

Writes GPI info to the device selected in this.deviceNumber.

Parameters:
xmlString - to be written to the device. This doesn't check validity
fileName - to write it to. Validity is not checked here

__Garmin.DeviceControl.findDevices

void __Garmin.DeviceControl.findDevices()

Finds any connected Garmin Devices. When it's done finding the devices, onFinishFindDevices is dispatched this.numDevices = the number of devices found this.deviceNumber is the device that we'll use to communicate with Use this.getDevices() to get an array of the found devices and this.setDeviceNumber({Number}) to change the device

__Garmin.DeviceControl.getDevices

Array __Garmin.DeviceControl.getDevices()

Get a list of the devices found

__Garmin.DeviceControl.getDeviceStatus

Garmin.TransferProgress __Garmin.DeviceControl.getDeviceStatus()

Get the status/progress of the current state or transfer

__Garmin.DeviceControl.getPluginVersion

Array __Garmin.DeviceControl.getPluginVersion()

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

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

__Garmin.DeviceControl.getPluginVersionString

String __Garmin.DeviceControl.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.DeviceControl.prototype.ex = "2.0.0.4";*

__Garmin.DeviceControl.initialize

void __Garmin.DeviceControl.initialize()

Instantiates a Garmin.DeviceControl object

__Garmin.DeviceControl.isBrowserSupported

Boolean __Garmin.DeviceControl.isBrowserSupported()

Determines if the users browser is currently supported by the plugin

__Garmin.DeviceControl.isPluginInitialized

Boolean __Garmin.DeviceControl.isPluginInitialized()

Determines if the plugin is initialized

__Garmin.DeviceControl.isPluginInstalled

Boolean __Garmin.DeviceControl.isPluginInstalled()

Determines if the plugin is installed on the user's machine

__Garmin.DeviceControl.isPluginOutOfDate

Boolean __Garmin.DeviceControl.isPluginOutOfDate()

Determines if the Garmin agent is the current version. See RequiredVersion object below to see the current required version.

__Garmin.DeviceControl.readFromDevice

void __Garmin.DeviceControl.readFromDevice()

Asynchronously reads data from the connected device. Only handles reading from the device in this.deviceNumber When the data has been gathered, the onFinishedReadFromDevice is fired, and the data is stored in this.gpsDataString and this.gpsData

__Garmin.DeviceControl.register

void __Garmin.DeviceControl.register(listener)

Register to be an event listener. An object that is registered will be dispatched a method if they have a function with the same dispatch name. So if you register a listener with an onFinishFindDevices, and the onFinishFindDevices message is called, you'll get that message. See class comments for event types

Parameters:
Object - that will listen for events coming from this object

See:
- {Garmin.Broadcaster}

__Garmin.DeviceControl.respondToMessageBox

void __Garmin.DeviceControl.respondToMessageBox(<Number> response)

Responds to a message box on the device.

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

__Garmin.DeviceControl.setDeviceNumber

void __Garmin.DeviceControl.setDeviceNumber(deviceNumber)

Sets the deviceNumber variable which determines which connected device to talk to.

Parameters:
The - device number

__Garmin.DeviceControl.toString

String __Garmin.DeviceControl.toString()

__Garmin.DeviceControl.unlock

Boolean __Garmin.DeviceControl.unlock(<String> web_path, <String> unlock_code)

Unlocks the GpsControl object to be used at the given web adress.

Parameters:
web_path -
unlock_code -

Returns:
True if the plug-in was unlocked successfully

__Garmin.DeviceControl.writeAddressToDevice

void __Garmin.DeviceControl.writeAddressToDevice(<Address> address, <String> fileName)

Writes an address to the currently selected device.

Parameters:
address - to be written to the device. This doesn't check validity
fileName - to write it to. Defaults to 'address.gpx'.

__Garmin.DeviceControl.writeToDevice

void __Garmin.DeviceControl.writeToDevice(<String> xmlString, <String> fileName)

Writes the given xml to the device selected in this.deviceNumber

Parameters:
xmlString - to be written to the device. This doesn't check validity
fileName - to write it to. Validity is not checked here

_finishInteraction

void _finishInteraction(type)

Parameters:
type - determines if we are ReadFrom or WriteTo the device

cancelFindDevices

void cancelFindDevices()

Cancels the current find devices interaction

cancelReadFromDevice

void cancelReadFromDevice()

Cancels the current read from the device

cancelWriteToDevice

void cancelWriteToDevice()

Cancels the current write transfer to the device

downlaodToDevice

void downlaodToDevice(gpiDataString, filename)

Writes GPI info to the device selected in this.deviceNumber.

Parameters:
xmlString - to be written to the device. This doesn't check validity
fileName - to write it to. Validity is not checked here

findDevices

void findDevices()

Finds any connected Garmin Devices. When it's done finding the devices, onFinishFindDevices is dispatched this.numDevices = the number of devices found this.deviceNumber is the device that we'll use to communicate with Use this.getDevices() to get an array of the found devices and this.setDeviceNumber({Number}) to change the device

getDevices

Array getDevices()

Get a list of the devices found

getDeviceStatus

Garmin.TransferProgress getDeviceStatus()

Get the status/progress of the current state or transfer

getPluginVersion

Array getPluginVersion()

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

Returns:
An array of the Garmin.DeviceControl.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.DeviceControl.prototype.ex = "2.0.0.4";*

initialize

void initialize()

Instantiates a Garmin.DeviceControl object

isBrowserSupported

Boolean isBrowserSupported()

Determines if the users browser is currently supported by the plugin

isPluginInitialized

Boolean isPluginInitialized()

Determines if the plugin is initialized

isPluginInstalled

Boolean isPluginInstalled()

Determines if the plugin is installed on the user's machine

isPluginOutOfDate

Boolean isPluginOutOfDate()

Determines if the Garmin agent is the current version. See RequiredVersion object below to see the current required version.

readFromDevice

void readFromDevice()

Asynchronously reads data from the connected device. Only handles reading from the device in this.deviceNumber When the data has been gathered, the onFinishedReadFromDevice is fired, and the data is stored in this.gpsDataString and this.gpsData

register

void register(listener)

Register to be an event listener. An object that is registered will be dispatched a method if they have a function with the same dispatch name. So if you register a listener with an onFinishFindDevices, and the onFinishFindDevices message is called, you'll get that message. See class comments for event types

Parameters:
Object - that will listen for events coming from this object

See:
- {Garmin.Broadcaster}

respondToMessageBox

void respondToMessageBox(<Number> response)

Responds to a message box on the device.

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

setDeviceNumber

void setDeviceNumber(deviceNumber)

Sets the deviceNumber variable which determines which connected device to talk to.

Parameters:
The - device number

toString

String toString()

unlock

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

Unlocks the GpsControl object to be used at the given web adress.

Parameters:
web_path -
unlock_code -

Returns:
True if the plug-in was unlocked successfully

writeAddressToDevice

void writeAddressToDevice(<Address> address, <String> fileName)

Writes an address to the currently selected device.

Parameters:
address - to be written to the device. This doesn't check validity
fileName - to write it to. Defaults to 'address.gpx'.

writeToDevice

void writeToDevice(<String> xmlString, <String> fileName)

Writes the given xml to the device selected in this.deviceNumber

Parameters:
xmlString - to be written to the device. This doesn't check validity
fileName - to write it to. Validity is not checked here