Class AntChannelProvider

java.lang.Object
com.dsi.ant.channel.AntChannelProvider

public final class AntChannelProvider extends 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 Details

    • ACTION_CHANNEL_PROVIDER_STATE_CHANGED

      public static final 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:
    • NUM_CHANNELS_AVAILABLE

      public static final 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:
    • NEW_CHANNELS_AVAILABLE

      public static final 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:
    • LEGACY_INTERFACE_IN_USE

      public static final 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:
  • Constructor Details

  • 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 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.
      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 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.
      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 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.
      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 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.
      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 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(android.content.Context context, NetworkKey privateNetworkKey, Capabilities requiredCapapbilities) throws android.os.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
      requiredCapapbilities - 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.
      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 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(android.content.Context context, NetworkKey privateNetworkKey, Capabilities requiredCapabilities, Capabilities desiredCapabilities) throws android.os.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.
      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 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(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 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.
      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 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.
      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 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.
      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 the ChannelNotAvailableReason
      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 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().
      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 the ChannelNotAvailableReason
      AntCommandFailedException - if continuous scan cannot be assigned. properly.
      Since:
      4.11.1
    • getNumChannelsAvailable

      public int getNumChannelsAvailable(Capabilities caps) throws android.os.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:
      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.RemoteException
      Queries 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.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:
      android.os.RemoteException - if there was an error performing the IPC call to the service
      Since:
      4.1