Package com.dsi.ant.channel
Class AntChannelProvider
java.lang.Object
com.dsi.ant.channel.AntChannelProvider
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
FieldsModifier and TypeFieldDescriptionstatic final String
Notification that the number of channels available to be acquired has changed.static final String
A key to theACTION_CHANNEL_PROVIDER_STATE_CHANGED
intent bundle pointing to a boolean value which is set to true if the legacy interface is in use.static final String
A key to theACTION_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 final String
A key to theACTION_CHANNEL_PROVIDER_STATE_CHANGED
intent bundle pointing to an integer value which indicates the number of channels available to be acquired. -
Constructor Summary
ConstructorsConstructorDescriptionAntChannelProvider
(android.os.IBinder binder) Creates a newAntChannelProvider
using the binding obtained fromAntService.bindService(android.content.Context, android.content.ServiceConnection)
to communicate with the ANT Radio service internally via IPC. -
Method Summary
Modifier and TypeMethodDescriptionacquireChannel
(android.content.Context context, com.dsi.ant.channel.PredefinedNetwork network) Acquires a free ANT Channel for this application to use.acquireChannel
(android.content.Context context, com.dsi.ant.channel.PredefinedNetwork network, Capabilities requiredCapabilities) Acquires a free ANT Channel for this application to use.acquireChannel
(android.content.Context context, com.dsi.ant.channel.PredefinedNetwork network, Capabilities requiredCapabilities, Capabilities desiredCapabilities) Acquires a free ANT Channel for this application to use.acquireChannelFromAdapter
(android.content.Context context, AdapterInfo adapter, com.dsi.ant.channel.PredefinedNetwork network) Acquires a free ANT Channel for this application to use.acquireChannelOnPrivateNetwork
(android.content.Context context, NetworkKey privateNetworkKey) Acquires channels in much the same way asacquireChannel(Context, PredefinedNetwork, Capabilities, Capabilities)
but acquires a free ANT Channel on the specified private network for this application to use.acquireChannelOnPrivateNetwork
(android.content.Context context, NetworkKey privateNetworkKey, Capabilities requiredCapapbilities) Acquires channels in much the same way asacquireChannel(Context, PredefinedNetwork, Capabilities, Capabilities)
but acquires a free ANT Channel on the specified private network for this application to use.acquireChannelOnPrivateNetwork
(android.content.Context context, NetworkKey privateNetworkKey, Capabilities requiredCapabilities, Capabilities desiredCapabilities) Acquires channels in much the same way asacquireChannel(Context, PredefinedNetwork, Capabilities, Capabilities)
but acquires a free ANT Channel on the specified private network for this application to use.acquireChannelOnPrivateNetworkFromAdapter
(android.content.Context context, AdapterInfo adapter, NetworkKey privateNetworkKey) Acquires a free ANT Channel for this application to use.acquireContinuousScanController
(android.content.Context context, AdapterInfo adapter, NetworkKey networkKey, boolean disableRxOnlyMode) Acquires an ANT continuous scan controller that is in assigned state for this application to use.acquireContinuousScanController
(android.content.Context context, AdapterInfo adapter, com.dsi.ant.channel.PredefinedNetwork network, boolean disableRxOnlyMode) Acquires an ANT continuous scan controller that is in assigned state for this application to use.int
Queries the number of channels available to be acquired.int
Queries the number of channels with the specified capabilities available to be acquired.boolean
Queries if the whole chip interface is in use.
-
Field Details
-
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
andNEW_CHANNELS_AVAILABLE
.- Since:
- 4.0
- See Also:
-
NUM_CHANNELS_AVAILABLE
A key to theACTION_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:
-
NEW_CHANNELS_AVAILABLE
A key to theACTION_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:
-
LEGACY_INTERFACE_IN_USE
A key to theACTION_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:
-
-
Constructor Details
-
AntChannelProvider
public AntChannelProvider(android.os.IBinder binder) Creates a newAntChannelProvider
using the binding obtained fromAntService.bindService(android.content.Context, android.content.ServiceConnection)
to communicate with the ANT Radio service internally via IPC. This binding should be acquired by usingAntService.ACTION_BIND_ANT_RADIO_SERVICE
. Apps should useAntService.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 Details
-
acquireChannel
public AntChannel acquireChannel(android.content.Context context, com.dsi.ant.channel.PredefinedNetwork network) throws ChannelNotAvailableException, android.os.RemoteException Acquires a free ANT Channel for this application to use. When you are done with this channel it should be released usingAntChannel.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, withChannelNotAvailableException.reasonCode
indicating the reason a channel could not be acquired. If the reason code isChannelNotAvailableReason.NETWORK_NOT_AVAILABLE
, applications should attempt to acquire a channel again when receiving aACTION_CHANNEL_PROVIDER_STATE_CHANGED
withNEW_CHANNELS_AVAILABLE
being true as a network slot may have become available as well.android.os.RemoteException
- If there was an error performing the IPC call to the service.- Since:
- 4.0
-
acquireChannel
public AntChannel acquireChannel(android.content.Context context, com.dsi.ant.channel.PredefinedNetwork network, Capabilities requiredCapabilities) throws ChannelNotAvailableException, android.os.RemoteException Acquires a free ANT Channel for this application to use. When you are done with this channel it should be released usingAntChannel.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, withChannelNotAvailableException.reasonCode
indicating the reason a channel could not be acquired. If the reason code isChannelNotAvailableReason.NETWORK_NOT_AVAILABLE
, applications should attempt to acquire a channel again when receiving aACTION_CHANNEL_PROVIDER_STATE_CHANGED
withNEW_CHANNELS_AVAILABLE
being true as a network slot may have become available as well.android.os.RemoteException
- If there was an error performing the IPC call to the service.- Since:
- 4.0
-
acquireChannel
public AntChannel acquireChannel(android.content.Context context, com.dsi.ant.channel.PredefinedNetwork network, Capabilities requiredCapabilities, Capabilities desiredCapabilities) throws ChannelNotAvailableException, android.os.RemoteException Acquires a free ANT Channel for this application to use. When you are done with this channel it should be released usingAntChannel.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, withChannelNotAvailableException.reasonCode
indicating the reason a channel could not be acquired. If the reason code isChannelNotAvailableReason.NETWORK_NOT_AVAILABLE
, applications should attempt to acquire a channel again when receiving aACTION_CHANNEL_PROVIDER_STATE_CHANGED
withNEW_CHANNELS_AVAILABLE
being true as a network slot may have become available as well.android.os.RemoteException
- If there was an error performing the IPC call to the service.- Since:
- 4.0
-
acquireChannelOnPrivateNetwork
public AntChannel acquireChannelOnPrivateNetwork(android.content.Context context, NetworkKey privateNetworkKey) throws android.os.RemoteException, ChannelNotAvailableException, UnsupportedFeatureException Acquires channels in much the same way asacquireChannel(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, withChannelNotAvailableException.reasonCode
indicating the reason a channel could not be acquired. If the reason code isChannelNotAvailableReason.NETWORK_NOT_AVAILABLE
, applications should attempt to acquire a channel again when receiving aACTION_CHANNEL_PROVIDER_STATE_CHANGED
withNEW_CHANNELS_AVAILABLE
being true as a network slot may have become available as well.android.os.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.IllegalArgumentException
- If the providedNetworkKey
contains a key whose length is notSetLongNetworkKeyMessage.LENGTH_NETWORK_KEY_BYTES
or if the key is the raw key for a network inPredefinedNetwork
.- Since:
- 4.3
-
acquireChannelOnPrivateNetwork
public AntChannel acquireChannelOnPrivateNetwork(android.content.Context context, NetworkKey privateNetworkKey, Capabilities requiredCapapbilities) throws android.os.RemoteException, ChannelNotAvailableException, UnsupportedFeatureException Acquires channels in much the same way asacquireChannel(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 channelrequiredCapapbilities
- 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, withChannelNotAvailableException.reasonCode
indicating the reason a channel could not be acquired. If the reason code isChannelNotAvailableReason.NETWORK_NOT_AVAILABLE
, applications should attempt to acquire a channel again when receiving aACTION_CHANNEL_PROVIDER_STATE_CHANGED
withNEW_CHANNELS_AVAILABLE
being true as a network slot may have become available as well.android.os.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.IllegalArgumentException
- If the providedNetworkKey
contains a key whose length is notSetLongNetworkKeyMessage.LENGTH_NETWORK_KEY_BYTES
or if the key is the raw key for a network inPredefinedNetwork
.- Since:
- 4.3
-
acquireChannelOnPrivateNetwork
public AntChannel acquireChannelOnPrivateNetwork(android.content.Context context, NetworkKey privateNetworkKey, Capabilities requiredCapabilities, Capabilities desiredCapabilities) throws android.os.RemoteException, ChannelNotAvailableException, UnsupportedFeatureException Acquires channels in much the same way asacquireChannel(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 channelrequiredCapabilities
- 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, withChannelNotAvailableException.reasonCode
indicating the reason a channel could not be acquired. If the reason code isChannelNotAvailableReason.NETWORK_NOT_AVAILABLE
, applications should attempt to acquire a channel again when receiving aACTION_CHANNEL_PROVIDER_STATE_CHANGED
withNEW_CHANNELS_AVAILABLE
being true as a network slot may have become available as well.android.os.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.IllegalArgumentException
- If the providedNetworkKey
contains a key whose length is notSetLongNetworkKeyMessage.LENGTH_NETWORK_KEY_BYTES
or if the key is the raw key for a network inPredefinedNetwork
.- Since:
- 4.3
-
acquireChannelFromAdapter
public AntChannel acquireChannelFromAdapter(android.content.Context context, AdapterInfo adapter, com.dsi.ant.channel.PredefinedNetwork network) throws ChannelNotAvailableException, android.os.RemoteException, UnsupportedFeatureException Acquires a free ANT Channel for this application to use. When you are done with this channel it should be released usingAntChannel.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 theAdapterInfo
object needed by this method. Whereas, handle to theAntAdapterProvider
object is returned byAntService.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, withChannelNotAvailableException.reasonCode
indicating the reason a channel could not be acquired. If the reason code isChannelNotAvailableReason.NETWORK_NOT_AVAILABLE
, applications should attempt to acquire a channel again when receiving aACTION_CHANNEL_PROVIDER_STATE_CHANGED
withNEW_CHANNELS_AVAILABLE
being true as a network slot may have become available as well.android.os.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- Since:
- 4.7.2
-
acquireChannelOnPrivateNetworkFromAdapter
public AntChannel acquireChannelOnPrivateNetworkFromAdapter(android.content.Context context, AdapterInfo adapter, NetworkKey privateNetworkKey) throws ChannelNotAvailableException, android.os.RemoteException, UnsupportedFeatureException Acquires a free ANT Channel for this application to use. When you are done with this channel it should be released usingAntChannel.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 theAdapterInfo
object needed by this method. Whereas, handle to theAntAdapterProvider
object is returned byAntService.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, withChannelNotAvailableException.reasonCode
indicating the reason a channel could not be acquired. If the reason code isChannelNotAvailableReason.NETWORK_NOT_AVAILABLE
, applications should attempt to acquire a channel again when receiving aACTION_CHANNEL_PROVIDER_STATE_CHANGED
withNEW_CHANNELS_AVAILABLE
being true as a network slot may have become available as well.android.os.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- Since:
- 4.7.2
-
acquireContinuousScanController
public AntContinuousScanController acquireContinuousScanController(android.content.Context context, AdapterInfo adapter, com.dsi.ant.channel.PredefinedNetwork network, boolean disableRxOnlyMode) throws android.os.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 usingAntContinuousScanController.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 theAdapterInfo
object needed by this method. Whereas, handle to theAntAdapterProvider
object is returned byAntService.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 usingAdapterInfo.isContinuousScanSupported()
.network
- The ANT network to use for this controller.disableRxOnlyMode
- 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:
android.os.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 theChannelNotAvailableReason
AntCommandFailedException
- if continuous scan cannot be assigned. properly.- Since:
- 4.11.1
-
acquireContinuousScanController
public AntContinuousScanController acquireContinuousScanController(android.content.Context context, AdapterInfo adapter, NetworkKey networkKey, boolean disableRxOnlyMode) throws android.os.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 usingAntContinuousScanController.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 theAdapterInfo
object needed by this method. Whereas, handle to theAntAdapterProvider
object is returned byAntService.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 usingAdapterInfo.isContinuousScanSupported()
.networkKey
- The ANT network to use for this controller.disableRxOnlyMode
- 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:
android.os.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 theChannelNotAvailableReason
AntCommandFailedException
- if continuous scan cannot be assigned. properly.- Since:
- 4.11.1
-
getNumChannelsAvailable
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:
android.os.RemoteException
- if there was an error performing the IPC call to the service- Since:
- 4.0
-
getNumChannelsAvailable
public int getNumChannelsAvailable() throws android.os.RemoteExceptionQueries the number of channels available to be acquired.- Returns:
- The number of channels available at the time of the query.
- Throws:
android.os.RemoteException
- if there was an error performing the IPC call to the service- Since:
- 4.0
-
isLegacyInterfaceInUse
public boolean isLegacyInterfaceInUse() throws android.os.RemoteExceptionQueries 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:
android.os.RemoteException
- if there was an error performing the IPC call to the service- Since:
- 4.1
-