com.dsi.ant.plugins.antplus.pcc

Class AntPlusGeocachePcc

java.lang.Object

com.dsi.ant.plugins.antplus.pccbase.AntPluginPcc

com.dsi.ant.plugins.antplus.pcc.AntPlusGeocachePcc

public class AntPlusGeocachePcc
extends AntPluginPcc

Enables communication between a client and the Geocache plugin service.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AntPlusGeocachePcc.DeviceChangingCode Defines the codes explaining the changes occurring to the device list received by the AntPlusGeocachePcc.IAvailableDeviceListReceiver.
static class	AntPlusGeocachePcc.GeocacheDeviceData Represents the data contained on a Geocache device.
static class	AntPlusGeocachePcc.GeocacheRequestStatus Defines the status code results sent on the result receiver for requests to the plugin.
static interface	AntPlusGeocachePcc.IAuthTokenRequestFinishedReceiver Receiver for the AuthTokenRequestFinished event, which is: Receives the result of a finished authentication token request.
static interface	AntPlusGeocachePcc.IAvailableDeviceListReceiver Receiver for the AvailableDeviceList event, which is: Broadcasts the current list of devices available to connect to along with information identifying any change since the last update, if applicable.
static interface	AntPlusGeocachePcc.IDataDownloadFinishedReceiver Receiver for the DataDownloadFinished event, which is: Receives the result of a finished data download.
class	AntPlusGeocachePcc.IpcDefines Defines the keys and values used to communicate between the PCC and plugin.
static interface	AntPlusGeocachePcc.IProgrammingFinishedReceiver Receiver for the ProgrammingFinished event, which is: Receives the result of a finished programming task.
static interface	AntPlusGeocachePcc.ISimpleProgressUpdateReceiver Receiver for the SimpleProgressUpdate event, which is: Communicates the work done.
static class	AntPlusGeocachePcc.ProgrammableGeocacheDeviceData Represents the programmable data contained on a geocache device.

Nested classes/interfaces inherited from class com.dsi.ant.plugins.antplus.pccbase.AntPluginPcc

AntPluginPcc.IDeviceStateChangeReceiver, AntPluginPcc.IPluginAccessResultReceiver<T extends AntPluginPcc>

Field Summary

Fields inherited from class com.dsi.ant.plugins.antplus.pccbase.AntPluginPcc

PATH_ANTPLUS_PLUGINS_PKG

Method Summary

Methods

Modifier and Type	Method and Description
boolean	requestAuthToken(int targetDeviceID, int nonce, long serialNumber, AntPlusGeocachePcc.IAuthTokenRequestFinishedReceiver resultReceiver, AntPlusGeocachePcc.ISimpleProgressUpdateReceiver progressReceiver) Requests the specified device to generate an auth token.
boolean	requestCurrentDeviceList() Requests the current device list.
boolean	requestDeviceData(int targetDeviceID, boolean updateVisitCount, AntPlusGeocachePcc.IDataDownloadFinishedReceiver resultReceiver, AntPlusGeocachePcc.ISimpleProgressUpdateReceiver progressReceiver) Requests the data available from the specified device.
boolean	requestDeviceProgramming(int targetDeviceID, long programmingPIN, boolean clearAllExistingData, AntPlusGeocachePcc.ProgrammableGeocacheDeviceData programmingData, AntPlusGeocachePcc.IProgrammingFinishedReceiver resultReceiver, AntPlusGeocachePcc.ISimpleProgressUpdateReceiver progressReceiver) Requests the plugin to program the specified device with the provided data.
static PccReleaseHandle<AntPlusGeocachePcc>	requestListAndRequestAccess(Context bindToContext, AntPluginPcc.IPluginAccessResultReceiver<AntPlusGeocachePcc> resultReceiver, AntPluginPcc.IDeviceStateChangeReceiver stateReceiver, AntPlusGeocachePcc.IAvailableDeviceListReceiver availableDeviceListRecevier) Send a request to the plugin for access to receive device list updates and make requests.

Methods inherited from class com.dsi.ant.plugins.antplus.pccbase.AntPluginPcc

getAntDeviceNumber, getCurrentDeviceState, getDeviceName, getInstalledPluginsVersionNumber, getInstalledPluginsVersionString, getMissingDependencyName, getMissingDependencyPackageName, isUserPreferredDeviceForPlugin, isUserRecognizedDevice, releaseAccess, startPluginManagerActivity

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

requestListAndRequestAccess

public static PccReleaseHandle<AntPlusGeocachePcc> requestListAndRequestAccess(Context bindToContext,
                                                               AntPluginPcc.IPluginAccessResultReceiver<AntPlusGeocachePcc> resultReceiver,
                                                               AntPluginPcc.IDeviceStateChangeReceiver stateReceiver,
                                                               AntPlusGeocachePcc.IAvailableDeviceListReceiver availableDeviceListRecevier)

Send a request to the plugin for access to receive device list updates and make requests.

Parameters:

bindToContext - The context to which the plugin will be bound. Used for plugin lifecycle management.

resultReceiver - The receiver to receive the results of the request. Possible returns include:

• RequestAccessResult.SUCCESS
• RequestAccessResult.USER_CANCELLED
• RequestAccessResult.CHANNEL_NOT_AVAILABLE
• RequestAccessResult.BAD_PARAMS
• RequestAccessResult.ADAPTER_NOT_DETECTED
• RequestAccessResult.DEPENDENCY_NOT_INSTALLED
• RequestAccessResult.OTHER_FAILURE

stateReceiver - The receiver to receive the state updates of the accessed device, if successful. This receiver will receive notifications of all state changes to the device that occur subsequent to the initial state returned in the result receiver.

availableDeviceListRecevier - Receives the available device list and updates to that list. Call requestCurrentDeviceList() after receiving access to get the current list.

Returns:

A release handle for the device. This can be used to guarantee the device is properly shutdown and cleaned up, even before the device is actually received through the result receiver.

requestCurrentDeviceList

public boolean requestCurrentDeviceList()

Requests the current device list. The list will come in on the receiver passed to #requestListAndRequestAccess(Context, IPluginAccessResultReceiver, IDeviceStateChangeReceiver, IAvailableDeviceListReceiver).

Returns:

True if request was submitted successfully and you are guaranteed a result on the result receiver. False if the PCC is dead and the request will not be processed.

requestDeviceData

public boolean requestDeviceData(int targetDeviceID,
                        boolean updateVisitCount,
                        AntPlusGeocachePcc.IDataDownloadFinishedReceiver resultReceiver,
                        AntPlusGeocachePcc.ISimpleProgressUpdateReceiver progressReceiver)

Requests the data available from the specified device. The data will be returned on the supplied result receiver.

Parameters:

targetDeviceID - The deviceID of the target device to make the request on.

updateVisitCount - If true, notifies the plugin to update the logged visits data to include this 'visit'. Devices will only be auto-updated once during any period the plugin detects it is within range regardless of how many times this flag is set, so always setting this flag to true is recommended.

resultReceiver - Receives the result of the request when it is finished.

progressReceiver - Optional. Receives updates on the progress of the download. This can be used to display a status bar to the user for example. Set to null if not needed.

Returns:

True if request was submitted successfully and you are guaranteed a result on the result receiver. False if the PCC is dead and the request will not be processed.

requestAuthToken

public boolean requestAuthToken(int targetDeviceID,
                       int nonce,
                       long serialNumber,
                       AntPlusGeocachePcc.IAuthTokenRequestFinishedReceiver resultReceiver,
                       AntPlusGeocachePcc.ISimpleProgressUpdateReceiver progressReceiver)

Requests the specified device to generate an auth token. The token will be returned on the supplied result receiver.

Parameters:

targetDeviceID - The deviceID of the target device to make the request on.

nonce - Random or pseudo-random number from 0-65535 that will be hashed by the geocache to produce an authentication token.

serialNumber - Serial number of the GPS receiver.

resultReceiver - Receives the result of the request when it is finished.

progressReceiver - Optional. Receives updates on the progress of the download. This can be used to display a status bar to the user for example. Set to null if not needed.

Returns:

True if request was submitted successfully and you are guaranteed a result on the result receiver. False if the PCC is dead and the request will not be processed.

requestDeviceProgramming

public boolean requestDeviceProgramming(int targetDeviceID,
                               long programmingPIN,
                               boolean clearAllExistingData,
                               AntPlusGeocachePcc.ProgrammableGeocacheDeviceData programmingData,
                               AntPlusGeocachePcc.IProgrammingFinishedReceiver resultReceiver,
                               AntPlusGeocachePcc.ISimpleProgressUpdateReceiver progressReceiver)

Requests the plugin to program the specified device with the provided data. If the device is not programmed, the minimum required data must be sent in the programmingData bundle. But, if the device is already programmed, the existing data will be overwritten according to the behaviour defined by the clearAllExistingData parameter. Note: The minimum required data is an identification string and a PIN.

Parameters:

targetDeviceID - The deviceID of the target device to make the request on.

programmingPIN - This PIN must match the current PIN on the device if it is set. If the device's PIN is not set, the value of this parameter is not used. (The PIN is supposed to prevent foreign devices reprogramming caches, but since the PIN info is publicly broadcast it is up to the client to respect this profile convention: Do not program a geocache device unless the existing PIN matches 'your' geocache receiver PIN or is not set (0xFFFFFFFF, unprogrammed). Note: This PIN is used to verify programming permission only and the PIN value specified in the programmingData will still be the one saved to the device.

clearAllExistingData - If true, all current data on the device will be erased, and the device will be programmed with only the data provided in programmingData (which therefore must include the minimum required data). If false, allows for partial data update where all existing non-provided data fields will be maintained on the device and only provided data fields are overwritten. If the device is not programmed this parameter is ignored.

programmingData - The data to be programmed to the device.

resultReceiver - Receives the result of the request when it is finished.

progressReceiver - Optional. Receives updates on the progress of the programming. This can be used to display a status bar to the user for example. Set to null if not needed.

Returns:

True if request was submitted successfully and you are guaranteed a result on the result receiver. False if the PCC is dead and the request will not be processed.