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