com.dsi.ant.channel

Class AntChannelProvider

java.lang.Object

com.dsi.ant.channel.AntChannelProvider

public final class AntChannelProvider
extends java.lang.Object

This class provides the interface that applications use to acquire ANT channels to use for ANT communication. To receive an instance of this class, use AntService.getChannelProvider()

Since:

4.0

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ACTION_CHANNEL_PROVIDER_STATE_CHANGED Notification that the number of channels available to be acquired has changed.
static java.lang.String	LEGACY_INTERFACE_IN_USE A key to the ACTION_CHANNEL_PROVIDER_STATE_CHANGED intent bundle pointing to a boolean value which is set to true if the legacy interface is in use.
static java.lang.String	NEW_CHANNELS_AVAILABLE A key to the ACTION_CHANNEL_PROVIDER_STATE_CHANGED intent bundle pointing to a boolean value which is set to true if there are new channels available to be acquired that were not available at the time of the last state change.
static java.lang.String	NUM_CHANNELS_AVAILABLE A key to the ACTION_CHANNEL_PROVIDER_STATE_CHANGED intent bundle pointing to an integer value which indicates the number of channels available to be acquired.

Constructor Summary

Constructors

Constructor and Description
AntChannelProvider(IBinder binder) Creates a new AntChannelProvider using the binding obtained from AntService.bindService(Context, ServiceConnection) to communicate with the ANT Radio service internally via IPC.

Method Summary

Methods

Modifier and Type	Method and Description
AntChannel	acquireChannel(Context context, PredefinedNetwork network) Acquires a free ANT Channel for this application to use.
AntChannel	acquireChannel(Context context, PredefinedNetwork network, Capabilities requiredCapabilities) Acquires a free ANT Channel for this application to use.
AntChannel	acquireChannel(Context context, PredefinedNetwork network, Capabilities requiredCapabilities, Capabilities desiredCapabilities) Acquires a free ANT Channel for this application to use.
AntChannel	acquireChannelFromAdapter(Context context, AdapterInfo adapter, PredefinedNetwork network) Acquires a free ANT Channel for this application to use.
AntChannel	acquireChannelOnPrivateNetwork(Context context, NetworkKey privateNetworkKey) Acquires channels in much the same way as acquireChannel(Context, PredefinedNetwork, Capabilities, Capabilities) but acquires a free ANT Channel on the specified private network for this application to use.
AntChannel	acquireChannelOnPrivateNetwork(Context context, NetworkKey privateNetworkKey, Capabilities requiredCapapbilities) Acquires channels in much the same way as acquireChannel(Context, PredefinedNetwork, Capabilities, Capabilities) but acquires a free ANT Channel on the specified private network for this application to use.
AntChannel	acquireChannelOnPrivateNetwork(Context context, NetworkKey privateNetworkKey, Capabilities requiredCapabilities, Capabilities desiredCapabilities) Acquires channels in much the same way as acquireChannel(Context, PredefinedNetwork, Capabilities, Capabilities) but acquires a free ANT Channel on the specified private network for this application to use.
AntChannel	acquireChannelOnPrivateNetworkFromAdapter(Context context, AdapterInfo adapter, NetworkKey privateNetworkKey) Acquires a free ANT Channel for this application to use.
AntContinuousScanController	acquireContinuousScanController(Context context, AdapterInfo adapter, NetworkKey networkKey, boolean disableRxOnlyMode) Acquires an ANT continuous scan controller that is in assigned state for this application to use.
AntContinuousScanController	acquireContinuousScanController(Context context, AdapterInfo adapter, PredefinedNetwork network, boolean disableRxOnlyMode) Acquires an ANT continuous scan controller that is in assigned state for this application to use.
int	getNumChannelsAvailable() Queries the number of channels available to be acquired.
int	getNumChannelsAvailable(Capabilities caps) Queries the number of channels with the specified capabilities available to be acquired.
boolean	isLegacyInterfaceInUse() Queries if the whole chip interface is in use.

Methods inherited from class java.lang.Object

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

Field Detail

ACTION_CHANNEL_PROVIDER_STATE_CHANGED

public static final java.lang.String ACTION_CHANNEL_PROVIDER_STATE_CHANGED

Notification that the number of channels available to be acquired has changed. The intent will have two extras: NUM_CHANNELS_AVAILABLE and NEW_CHANNELS_AVAILABLE.

Since:

4.0

See Also:

Constant Field Values

NUM_CHANNELS_AVAILABLE

public static final java.lang.String NUM_CHANNELS_AVAILABLE

A key to the ACTION_CHANNEL_PROVIDER_STATE_CHANGED intent bundle pointing to an integer value which indicates the number of channels available to be acquired.

Since:

4.0

See Also:

Constant Field Values

NEW_CHANNELS_AVAILABLE

public static final java.lang.String NEW_CHANNELS_AVAILABLE

A key to the ACTION_CHANNEL_PROVIDER_STATE_CHANGED intent bundle pointing to a boolean value which is set to true if there are new channels available to be acquired that were not available at the time of the last state change.

Since:

4.0

See Also:

Constant Field Values

LEGACY_INTERFACE_IN_USE

public static final java.lang.String LEGACY_INTERFACE_IN_USE

A key to the ACTION_CHANNEL_PROVIDER_STATE_CHANGED intent bundle pointing to a boolean value which is set to true if the legacy interface is in use. If true and there are no channels available, applications can attempt to force claim the interface away from the legacy application by attempting to acquire a channel.

Since:

4.1

See Also:

Constant Field Values

Constructor Detail

AntChannelProvider

public AntChannelProvider(IBinder binder)

Creates a new AntChannelProvider using the binding obtained from AntService.bindService(Context, ServiceConnection) to communicate with the ANT Radio service internally via IPC. This binding should be acquired by using AntService.ACTION_BIND_ANT_RADIO_SERVICE. Apps should use AntService.getChannelProvider() to obtain a reference to this object.

Parameters:

binder - The service binding used to talk to the ANT Radio service.

Since:

4.0

Method Detail

acquireChannel

public AntChannel acquireChannel(Context context,
                        PredefinedNetwork network)
                          throws ChannelNotAvailableException,
                                 RemoteException

Acquires a free ANT Channel for this application to use. When you are done with this channel it should be released using AntChannel.release() which will clean up its resources and allow the underlying channel resource to be acquired somewhere else. If the legacy interface is in use, this method can be used to attempt to force claim the interface away from the legacy application. A dialog will then ask the user to free the ANT radio, after which an attempt to acquire a channel will be successful.

Parameters:

context - the context the ANT Channel will be used in.

network - The ANT network to use for this channel.

Returns:

The acquired channel object. The channel will be in an unassigned state when received.

Throws:

ChannelNotAvailableException - If a channel could not be acquired this will be thrown, with ChannelNotAvailableException.reasonCode indicating the reason a channel could not be acquired. If the reason code is ChannelNotAvailableReason.NETWORK_NOT_AVAILABLE, applications should attempt to acquire a channel again when receiving a ACTION_CHANNEL_PROVIDER_STATE_CHANGED with NEW_CHANNELS_AVAILABLE being true as a network slot may have become available as well.

RemoteException - If there was an error performing the IPC call to the service.

Since:

4.0

acquireChannel

public AntChannel acquireChannel(Context context,
                        PredefinedNetwork network,
                        Capabilities requiredCapabilities)
                          throws ChannelNotAvailableException,
                                 RemoteException

Acquires a free ANT Channel for this application to use. When you are done with this channel it should be released using AntChannel.release() which will clean up its resources and allow the underlying channel resource to be acquired somewhere else. If the legacy interface is in use, this method can be used to attempt to force claim the interface away from the legacy application. A dialog will then ask the user to free the ANT radio, after which an attempt to acquire a channel will be successful.

Parameters:

context - the context the ANT Channel will be used in.

network - The ANT network to use for this channel.

requiredCapabilities - The capabilities that the received channel object must provide.

Returns:

The acquired channel object. The channel will be in an unassigned state when received.

Throws:

ChannelNotAvailableException - If a channel could not be acquired this will be thrown, with ChannelNotAvailableException.reasonCode indicating the reason a channel could not be acquired. If the reason code is ChannelNotAvailableReason.NETWORK_NOT_AVAILABLE, applications should attempt to acquire a channel again when receiving a ACTION_CHANNEL_PROVIDER_STATE_CHANGED with NEW_CHANNELS_AVAILABLE being true as a network slot may have become available as well.

RemoteException - If there was an error performing the IPC call to the service.

Since:

4.0

acquireChannel

public AntChannel acquireChannel(Context context,
                        PredefinedNetwork network,
                        Capabilities requiredCapabilities,
                        Capabilities desiredCapabilities)
                          throws ChannelNotAvailableException,
                                 RemoteException

Acquires a free ANT Channel for this application to use. When you are done with this channel it should be released using AntChannel.release() which will clean up its resources and allow the underlying channel resource to be acquired somewhere else. If the legacy interface is in use, this method can be used to attempt to force claim the interface away from the legacy application. A dialog will then ask the user to free the ANT radio, after which an attempt to acquire a channel will be successful.

Parameters:

context - the context the ANT Channel will be used in.

network - The ANT network to use for this channel.

requiredCapabilities - The capabilities that the received channel object must provide.

desiredCapabilities - The capabilities that it would be preferred the received channel object provides. This is used as a hint to the ANT Radio service that allows it to better distribute channels from multiple types of hardware.

Returns:

The acquired channel object. The channel will be in an unassigned state when received.

Throws:

ChannelNotAvailableException - If a channel could not be acquired this will be thrown, with ChannelNotAvailableException.reasonCode indicating the reason a channel could not be acquired. If the reason code is ChannelNotAvailableReason.NETWORK_NOT_AVAILABLE, applications should attempt to acquire a channel again when receiving a ACTION_CHANNEL_PROVIDER_STATE_CHANGED with NEW_CHANNELS_AVAILABLE being true as a network slot may have become available as well.

RemoteException - If there was an error performing the IPC call to the service.

Since:

4.0

acquireChannelOnPrivateNetwork

public AntChannel acquireChannelOnPrivateNetwork(Context context,
                                        NetworkKey privateNetworkKey)
                                          throws RemoteException,
                                                 ChannelNotAvailableException,
                                                 UnsupportedFeatureException

Acquires channels in much the same way as acquireChannel(Context, PredefinedNetwork, Capabilities, Capabilities) but acquires a free ANT Channel on the specified private network for this application to use.

Parameters:

context - the context the ANT Channel will be used in.

privateNetworkKey - The key for the private network to use for this channel

Returns:

The acquired channel object on the desired network. The channel will be in an unassigned state when received.

Throws:

ChannelNotAvailableException - If a channel could not be acquired this will be thrown, with ChannelNotAvailableException.reasonCode indicating the reason a channel could not be acquired. If the reason code is ChannelNotAvailableReason.NETWORK_NOT_AVAILABLE, applications should attempt to acquire a channel again when receiving a ACTION_CHANNEL_PROVIDER_STATE_CHANGED with NEW_CHANNELS_AVAILABLE being true as a network slot may have become available as well.

RemoteException - If there was an error performing the IPC call to the service.

UnsupportedFeatureException - If this feature is not supported by the version of ANT Radio Service installed.

java.lang.IllegalArgumentException - If the provided NetworkKey contains a key whose length is not SetLongNetworkKeyMessage.LENGTH_NETWORK_KEY_BYTES or if the key is the raw key for a network in PredefinedNetwork.

Since:

4.3

acquireChannelOnPrivateNetwork

public AntChannel acquireChannelOnPrivateNetwork(Context context,
                                        NetworkKey privateNetworkKey,
                                        Capabilities requiredCapapbilities)
                                          throws RemoteException,
                                                 ChannelNotAvailableException,
                                                 UnsupportedFeatureException

Acquires channels in much the same way as acquireChannel(Context, PredefinedNetwork, Capabilities, Capabilities) but acquires a free ANT Channel on the specified private network for this application to use.

Parameters:

context - the context the ANT Channel will be used in.

privateNetworkKey - The key for the private network to use for this channel

requiredCapabilities - The capabilities that the received channel object must provide.

Returns:

The acquired channel object on the desired network. The channel will be in an unassigned state when received.

Throws:

ChannelNotAvailableException - If a channel could not be acquired this will be thrown, with ChannelNotAvailableException.reasonCode indicating the reason a channel could not be acquired. If the reason code is ChannelNotAvailableReason.NETWORK_NOT_AVAILABLE, applications should attempt to acquire a channel again when receiving a ACTION_CHANNEL_PROVIDER_STATE_CHANGED with NEW_CHANNELS_AVAILABLE being true as a network slot may have become available as well.

RemoteException - If there was an error performing the IPC call to the service.

UnsupportedFeatureException - If this feature is not supported by the version of ANT Radio Service installed.

java.lang.IllegalArgumentException - If the provided NetworkKey contains a key whose length is not SetLongNetworkKeyMessage.LENGTH_NETWORK_KEY_BYTES or if the key is the raw key for a network in PredefinedNetwork.

Since:

4.3

acquireChannelOnPrivateNetwork

public AntChannel acquireChannelOnPrivateNetwork(Context context,
                                        NetworkKey privateNetworkKey,
                                        Capabilities requiredCapabilities,
                                        Capabilities desiredCapabilities)
                                          throws RemoteException,
                                                 ChannelNotAvailableException,
                                                 UnsupportedFeatureException

Acquires channels in much the same way as acquireChannel(Context, PredefinedNetwork, Capabilities, Capabilities) but acquires a free ANT Channel on the specified private network for this application to use.

Parameters:

context - the context the ANT Channel will be used in.

privateNetworkKey - The key for the private network to use for this channel

requiredCapabilities - The capabilities that the received channel object must provide.

desiredCapabilities - The capabilities that it would be preferred the received channel object provides. This is used as a hint to the ANT Radio service that allows it to better distribute channels from multiple types of hardware.

Returns:

The acquired channel object on the desired network. The channel will be in an unassigned state when received.

Throws:

ChannelNotAvailableException - If a channel could not be acquired this will be thrown, with ChannelNotAvailableException.reasonCode indicating the reason a channel could not be acquired. If the reason code is ChannelNotAvailableReason.NETWORK_NOT_AVAILABLE, applications should attempt to acquire a channel again when receiving a ACTION_CHANNEL_PROVIDER_STATE_CHANGED with NEW_CHANNELS_AVAILABLE being true as a network slot may have become available as well.

RemoteException - If there was an error performing the IPC call to the service.

UnsupportedFeatureException - If this feature is not supported by the version of ANT Radio Service installed.

java.lang.IllegalArgumentException - If the provided NetworkKey contains a key whose length is not SetLongNetworkKeyMessage.LENGTH_NETWORK_KEY_BYTES or if the key is the raw key for a network in PredefinedNetwork.

Since:

4.3

acquireChannelFromAdapter

public AntChannel acquireChannelFromAdapter(Context context,
                                   AdapterInfo adapter,
                                   PredefinedNetwork network)
                                     throws ChannelNotAvailableException,
                                            RemoteException,
                                            UnsupportedFeatureException

Acquires a free ANT Channel for this application to use. When you are done with this channel it should be released using AntChannel.release() which will clean up its resources and allow the underlying channel resource to be acquired somewhere else. If the legacy interface is in use, this method can be used to attempt to force claim the interface away from the legacy application. A dialog will then ask the user to free the ANT radio, after which an attempt to acquire a channel will be successful. AntAdapterProvider.getAdaptersInfo(Context) returns the AdapterInfo object needed by this method. Whereas, handle to the AntAdapterProvider object is returned by AntService.getAdapterProvider()

Parameters:

context - the context the ANT Channel will be used in.

adapter - the adapter to acquire the channel from.

network - The ANT network to use for this channel.

Returns:

The acquired channel object. The channel will be in an unassigned state when received.

Throws:

ChannelNotAvailableException - If a channel could not be acquired this will be thrown, with ChannelNotAvailableException.reasonCode indicating the reason a channel could not be acquired. If the reason code is ChannelNotAvailableReason.NETWORK_NOT_AVAILABLE, applications should attempt to acquire a channel again when receiving a ACTION_CHANNEL_PROVIDER_STATE_CHANGED with NEW_CHANNELS_AVAILABLE being true as a network slot may have become available as well.

RemoteException - If there was an error performing the IPC call to the service.

UnsupportedFeatureException

Since:

4.7.2

acquireChannelOnPrivateNetworkFromAdapter

public AntChannel acquireChannelOnPrivateNetworkFromAdapter(Context context,
                                                   AdapterInfo adapter,
                                                   NetworkKey privateNetworkKey)
                                                     throws ChannelNotAvailableException,
                                                            RemoteException,
                                                            UnsupportedFeatureException

Acquires a free ANT Channel for this application to use. When you are done with this channel it should be released using AntChannel.release() which will clean up its resources and allow the underlying channel resource to be acquired somewhere else. If the legacy interface is in use, this method can be used to attempt to force claim the interface away from the legacy application. A dialog will then ask the user to free the ANT radio, after which an attempt to acquire a channel will be successful. AntAdapterProvider.getAdaptersInfo(Context) returns the AdapterInfo object needed by this method. Whereas, handle to the AntAdapterProvider object is returned by AntService.getAdapterProvider()

Parameters:

context - the context the ANT Channel will be used in.

adapter - the adapter to acquire the channel from.

privateNetworkKey - The key for the private network to use for this channel

Returns:

The acquired channel object. The channel will be in an unassigned state when received.

Throws:

ChannelNotAvailableException - If a channel could not be acquired this will be thrown, with ChannelNotAvailableException.reasonCode indicating the reason a channel could not be acquired. If the reason code is ChannelNotAvailableReason.NETWORK_NOT_AVAILABLE, applications should attempt to acquire a channel again when receiving a ACTION_CHANNEL_PROVIDER_STATE_CHANGED with NEW_CHANNELS_AVAILABLE being true as a network slot may have become available as well.

RemoteException - If there was an error performing the IPC call to the service.

UnsupportedFeatureException

Since:

4.7.2

acquireContinuousScanController

public AntContinuousScanController acquireContinuousScanController(Context context,
                                                          AdapterInfo adapter,
                                                          PredefinedNetwork network,
                                                          boolean disableRxOnlyMode)
                                                            throws RemoteException,
                                                                   UnsupportedFeatureException,
                                                                   ChannelNotAvailableException,
                                                                   AntCommandFailedException

Acquires an ANT continuous scan controller that is in assigned state for this application to use. When you are done with this controller it should be released using AntContinuousScanController.release() which will clean up its resources and allow the underlying channel resource to be acquired somewhere else. Warning: Continuous scan mode will keep the radio open constantly and can affect battery life and performance. Additionally, continuous scan mode consumes the entire adapter and will not allow other apps to access it. For these reasons, ensure you close your scan controller whenever you do not need data, and ensure you release the controller when you no longer need it. You may also consider using background scan mode on a normal channel instead if you do not require the low latency, high reception performance of continuous scan and want to be compatible with more adapters. If the legacy interface is in use, this method can be used to attempt to force claim the interface away from the legacy application. A dialog will then ask the user to free the ANT radio, after which an attempt to acquire a controller will be successful. AntAdapterProvider.getAdaptersInfo(Context) returns the AdapterInfo object needed by this method. Whereas, handle to the AntAdapterProvider object is returned by AntService.getAdapterProvider()

Parameters:

context - the context the ANT controller will be used in.

adapter - the adapter you wish to acquire the controller from or null to acquire any available controller supporting that feature. Adapters that support continuous scan can be determined using AdapterInfo.isContinuousScanSupported().

network - The ANT network to use for this controller.

disableRxOnMode - Default is false. Setting this to true will disable rxOnlyMode and allow the scan channel to acknowledge reception of acknowledged and burst messages which may decrease scan performance and interfere with other slave channels receiving ack and burst messages.

Returns:

the AntContinuousScanController object. The object will be in the assigned state when received.

Throws:

RemoteException - If there was an error performing the IPC call to the service.

UnsupportedFeatureException - if continuous scan is not supported by the installed version of the ANT Radio Service (i.e. an updated version of the ARS is required).

ChannelNotAvailableException - if the ANT Radio Service encounters an error reserving and setting up the channel. In this case refer to the ChannelNotAvailableException.ChannelNotAvailableReason

AntCommandFailedException - if continuous scan cannot be assigned. properly.

Since:

4.11.1

acquireContinuousScanController

public AntContinuousScanController acquireContinuousScanController(Context context,
                                                          AdapterInfo adapter,
                                                          NetworkKey networkKey,
                                                          boolean disableRxOnlyMode)
                                                            throws RemoteException,
                                                                   UnsupportedFeatureException,
                                                                   ChannelNotAvailableException,
                                                                   AntCommandFailedException

Acquires an ANT continuous scan controller that is in assigned state for this application to use. When you are done with this controller it should be released using AntContinuousScanController.release() which will clean up its resources and allow the underlying channel resource to be acquired somewhere else. Warning: Continuous scan mode will keep the radio open constantly and can affect battery life and performance. Additionally, continuous scan mode consumes the entire adapter and will not allow other apps to access it. For these reasons, ensure you close your scan controller whenever you do not need data, and ensure you release the controller when you no longer need it. You may also consider using background scan mode on a normal channel instead if you do not require the low latency, high reception performance of continuous scan and want to be compatible with more adapters. If the legacy interface is in use, this method can be used to attempt to force claim the interface away from the legacy application. A dialog will then ask the user to free the ANT radio, after which an attempt to acquire a controller will be successful. AntAdapterProvider.getAdaptersInfo(Context) returns the AdapterInfo object needed by this method. Whereas, handle to the AntAdapterProvider object is returned by AntService.getAdapterProvider()

Parameters:

context - the context the ANT controller will be used in.

adapter - the adapter you wish to acquire the controller from or null to acquire any available controller supporting that feature. Adapters that support continuous scan can be determined using AdapterInfo.isContinuousScanSupported().

network - The ANT network to use for this controller.

disableRxOnMode - Default is false. Setting this to true will disable rxOnlyMode and allow the scan channel to acknowledge reception of acknowledged and burst messages which may decrease scan performance and interfere with other slave channels receiving ack and burst messages.

Returns:

the AntContinuousScanController object. The object will be in the assigned state when received.

Throws:

RemoteException - If there was an error performing the IPC call to the service.

UnsupportedFeatureException - if continuous scan is not supported by the installed version of the ANT Radio Service (i.e. an updated version of the ARS is required).

ChannelNotAvailableException - if the ANT Radio Service encounters an error reserving and setting up the channel. In this case refer to the ChannelNotAvailableException.ChannelNotAvailableReason

AntCommandFailedException - if continuous scan cannot be assigned. properly.

Since:

4.11.1

getNumChannelsAvailable

public int getNumChannelsAvailable(Capabilities caps)
                            throws RemoteException

Queries the number of channels with the specified capabilities available to be acquired.

Parameters:

caps - Specifies the capabilities that the channels must have

Returns:

The number of channels with the specified capabilities available at the time of the query.

Throws:

RemoteException - if there was an error performing the IPC call to the service

Since:

4.0

getNumChannelsAvailable

public int getNumChannelsAvailable()
                            throws RemoteException

Queries the number of channels available to be acquired.

Returns:

The number of channels available at the time of the query.

Throws:

RemoteException - if there was an error performing the IPC call to the service

Since:

4.0

isLegacyInterfaceInUse

public boolean isLegacyInterfaceInUse()
                               throws RemoteException

Queries if the whole chip interface is in use. If there are no channels available, applications can use this check to determine if the legacy interface is using all the channels. In this case, applications can attempt to acquire a channel to force claim the interface.

Returns:

true if the whole chip interface is in use. If true, applications can attempt to acquire channels anyway and force claim the adapter.

Throws:

RemoteException

Since:

4.1