com.avaya.deskphoneservices.device

## Class DefaultVantageAudioDeviceHandler

- java.lang.Object
- - com.avaya.deskphoneservices.device.DefaultVantageAudioDeviceHandler

- All Implemented Interfaces:
    com.avaya.clientservices.client.ClientListener, com.avaya.clientservices.media.AudioDeviceListener, AudioDeviceChangeNotifier, AudioDeviceHandler, HandsetHookListener

      public class DefaultVantageAudioDeviceHandler
      extends java.lang.Object
      implements AudioDeviceHandler, com.avaya.clientservices.client.ClientListener, HandsetHookListener

  Default implementation of the audio device switching logic for the Vantage platform.

  This class is designed that it can be used as-is in third-party clients that want to behave identically to Equinox on Vantage.

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAudioDeviceChangeListener(AudioDeviceChangeListener listener)` Add a listener to be notified when the active audio device changes.
    `static DefaultVantageAudioDeviceHandler` | `createDefaultVantageAudioDeviceHandler(android.content.Context applicationContext, com.avaya.clientservices.client.Client client, DeskPhoneService deskPhoneService)` Create an object to provide default audio device handling.
    `java.util.Collection<com.avaya.clientservices.media.AudioDevice>` | `getAvailableAudioDevices()` Get the available audio devices.
    `com.avaya.clientservices.media.AudioDevice` | `getLastUsedHeadsetDevice()`
    `void` | `onAudioDeviceChanged(com.avaya.clientservices.media.AudioDevice newDevice)` Called when the active audio device has changed via the AudioInterface API.
    `void` | `onAudioDeviceError(com.avaya.clientservices.media.AudioDeviceError error)` Audio state error occured.
    `void` | `onAudioDeviceListChanged(java.util.List<com.avaya.clientservices.media.AudioDevice> newDeviceList, boolean activeDeviceChanged)` Audio device(s) have been added or removed by the system.
    `void` | `onClientShutdown(com.avaya.clientservices.client.Client client)` Called when the client has shut down.
    `void` | `onClientUserCreated(com.avaya.clientservices.client.Client client, com.avaya.clientservices.user.User user)` Notifies the listener that the specified user has been created.
    `void` | `onClientUserRemoved(com.avaya.clientservices.client.Client client, com.avaya.clientservices.user.User user)` Notifies the listener that the specified user has been removed.
    `void` | `onHandsetOffHook(HandsetType handset)` Called when a connected handset has gone off-hook (removed from its cradle).
    `void` | `onHandsetOnHook(HandsetType handset)` Called when a connected handset has gone on-hook (returned to its cradle).
    `void` | `onIdentityCertificateEnrollmentFailed(com.avaya.clientservices.client.Client client, int errorCode, java.lang.String errorType, java.lang.String message)` Notifies the listener that the SCEP conection/enrollment failed.
    `com.avaya.clientservices.media.AudioDevice` | `pickAudioDeviceForCallStart(HandsetType handset)` Choose the audio device to use at the beginning of a new VoIP call.
    `void` | `removeAudioDeviceChangeListener(AudioDeviceChangeListener listener)` Remove a listener from being notified when the active audio device changes.
    `void` | `setRJ9HeadsetDefaultAudioDevice(boolean enabled)` Set the flag controlling if the RJ9 jack is the default audio device used for new calls.
    `void` | `setUserRequestedDevice(com.avaya.clientservices.media.AudioDevice device)` Set the currently active audio device to the specified device.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### createDefaultVantageAudioDeviceHandler

          @NonNull
          public static DefaultVantageAudioDeviceHandler createDefaultVantageAudioDeviceHandler(@NonNull
                                                                                                         android.content.Context applicationContext,
                                                                                                         @NonNull
                                                                                                         com.avaya.clientservices.client.Client client,
                                                                                                         @NonNull
                                                                                                         DeskPhoneService deskPhoneService)

      Create an object to provide default audio device handling.

      The returned object is only valid for the lifetime of the `Client` object, and can not be used anymore after that `Client`'s `shutdown()` method has been called.

      There's no need to register the returned object as a listener with the media engine - that's handled by this factory method.

      Parameters:
        `applicationContext` - The application's context.
        `client` - The active Client object from the Communications Package.
        `deskPhoneService` - The Desk Phone Service instance.
      Returns:
        The new `DefaultVantageAudioDeviceHandler` instance to use.

    - #### getAvailableAudioDevices

          @NonNull
          public java.util.Collection<com.avaya.clientservices.media.AudioDevice> getAvailableAudioDevices()

      Description copied from interface: `AudioDeviceHandler`
      Get the available audio devices.

      The advantage of using this over calling `AudioInterface.getDevices()` is that this version will filter out any handset devices that aren't off-hook.

      Specified by:
        `getAvailableAudioDevices` in interface `AudioDeviceHandler`
      Returns:
        A collection of the currently available audio devices.

    - #### addAudioDeviceChangeListener

          public void addAudioDeviceChangeListener(@NonNull
                                                   AudioDeviceChangeListener listener)

      Description copied from interface: `AudioDeviceChangeNotifier`
      Add a listener to be notified when the active audio device changes.
      Specified by:
        `addAudioDeviceChangeListener` in interface `AudioDeviceChangeNotifier`
      Parameters:
        `listener` - The listener for audio device change events.

    - #### removeAudioDeviceChangeListener

          public void removeAudioDeviceChangeListener(@NonNull
                                                      AudioDeviceChangeListener listener)

      Description copied from interface: `AudioDeviceChangeNotifier`
      Remove a listener from being notified when the active audio device changes.
      Specified by:
        `removeAudioDeviceChangeListener` in interface `AudioDeviceChangeNotifier`
      Parameters:
        `listener` - The listener for audio device change events.

    - #### onClientUserCreated

          public void onClientUserCreated(@NonNull
                                          com.avaya.clientservices.client.Client client,
                                          @NonNull
                                          com.avaya.clientservices.user.User user)

      Description copied from interface: `com.avaya.clientservices.client.ClientListener`
      Notifies the listener that the specified user has been created.
      Specified by:
        `onClientUserCreated` in interface `com.avaya.clientservices.client.ClientListener`
      Parameters:
        `client` - The client from which the event came from.
        `user` - The created User.

    - #### onClientUserRemoved

          public void onClientUserRemoved(@NonNull
                                          com.avaya.clientservices.client.Client client,
                                          @NonNull
                                          com.avaya.clientservices.user.User user)

      Description copied from interface: `com.avaya.clientservices.client.ClientListener`
      Notifies the listener that the specified user has been removed.
      Specified by:
        `onClientUserRemoved` in interface `com.avaya.clientservices.client.ClientListener`
      Parameters:
        `client` - The client from which the event came from.
        `user` - The removed User.

    - #### onIdentityCertificateEnrollmentFailed

          public void onIdentityCertificateEnrollmentFailed(com.avaya.clientservices.client.Client client,
                                                            int errorCode,
                                                            java.lang.String errorType,
                                                            java.lang.String message)

      Description copied from interface: `com.avaya.clientservices.client.ClientListener`
      Notifies the listener that the SCEP conection/enrollment failed.
      Specified by:
        `onIdentityCertificateEnrollmentFailed` in interface `com.avaya.clientservices.client.ClientListener`
      Parameters:
        `client` - The client from which the event came from.
        `errorCode` - The error code.
        `errorType` - The type of error.
        `message` - The error description.

    - #### onClientShutdown

          public void onClientShutdown(@Nullable
                                       com.avaya.clientservices.client.Client client)

      Description copied from interface: `com.avaya.clientservices.client.ClientListener`
      Called when the client has shut down.

      At this point the client is idle and all references to it can be removed.

      Specified by:
        `onClientShutdown` in interface `com.avaya.clientservices.client.ClientListener`
      Parameters:
        `client` - The client that has been shut down.

    - #### onHandsetOffHook

          public void onHandsetOffHook(@NonNull
                                       HandsetType handset)

      Description copied from interface: `HandsetHookListener`
      Called when a connected handset has gone off-hook (removed from its cradle).

      This usually means that the user wishes to answer or start a new call.

      Specified by:
        `onHandsetOffHook` in interface `HandsetHookListener`
      Parameters:
        `handset` - Which handset went off-hook.

    - #### onHandsetOnHook

          public void onHandsetOnHook(@NonNull
                                      HandsetType handset)

      Description copied from interface: `HandsetHookListener`
      Called when a connected handset has gone on-hook (returned to its cradle).

      This usually means that the user wishes to end a call.

      Specified by:
        `onHandsetOnHook` in interface `HandsetHookListener`
      Parameters:
        `handset` - Which handset went on-hook.

    - #### setRJ9HeadsetDefaultAudioDevice

          public void setRJ9HeadsetDefaultAudioDevice(boolean enabled)

      Description copied from interface: `AudioDeviceHandler`
      Set the flag controlling if the RJ9 jack is the default audio device used for new calls.

      This is needed because the Vantage hardware is unable to detect when a headset is actually plugged into the RJ9 jack on the back, so the media engine always reports it as available.

      The default is `false`, which means to use the speakerphone as the default audio device.

      Specified by:
        `setRJ9HeadsetDefaultAudioDevice` in interface `AudioDeviceHandler`
      Parameters:
        `enabled` - Set `true` to use the headset plugged into the RJ9 jack as the default audio device, `false` to use the speakerphone as the default audio device.
      See Also:
        `AudioDeviceHandler.pickAudioDeviceForCallStart(HandsetType)`

    - #### pickAudioDeviceForCallStart

          @NonNull
          public com.avaya.clientservices.media.AudioDevice pickAudioDeviceForCallStart(@Nullable
                                                                                                 HandsetType handset)

      Description copied from interface: `AudioDeviceHandler`
      Choose the audio device to use at the beginning of a new VoIP call.
      Specified by:
        `pickAudioDeviceForCallStart` in interface `AudioDeviceHandler`
      Parameters:
        `handset` - If non-`null`, the device that went off-hook to originate this call.
      Returns:
        The audio device to use for the call.

    - #### getLastUsedHeadsetDevice

          public com.avaya.clientservices.media.AudioDevice getLastUsedHeadsetDevice()

    - #### setUserRequestedDevice

          public void setUserRequestedDevice(@NonNull
                                             com.avaya.clientservices.media.AudioDevice device)

      Description copied from interface: `AudioDeviceHandler`
      Set the currently active audio device to the specified device.

      Use this to implement device selection inside your application's logic and user interface, for cases where the user changes the active audio device without a physical action like plugging/unplugging a device or a handset going on or off hook.

      Specified by:
        `setUserRequestedDevice` in interface `AudioDeviceHandler`
      Parameters:
        `device` - The audio device to use.

    - #### onAudioDeviceListChanged

          public void onAudioDeviceListChanged(@NonNull
                                               java.util.List<com.avaya.clientservices.media.AudioDevice> newDeviceList,
                                               boolean activeDeviceChanged)

      Description copied from interface: `com.avaya.clientservices.media.AudioDeviceListener`
      Audio device(s) have been added or removed by the system. This can be due to a Bluetooth device (dis)connecting or a headset being plugged in.
      Specified by:
        `onAudioDeviceListChanged` in interface `com.avaya.clientservices.media.AudioDeviceListener`
      Parameters:
        `newDeviceList` - updated device list with new device(s) added or removed.
        `activeDeviceChanged` - true if the current active device has changed. If this is true then the audio has moved to a safe state and is muted. A calling setUserRequestedDevice will cause the audio to be restored on the new device. gatActiveDevice() can be called to see what is the currently active device.

    - #### onAudioDeviceChanged

          public void onAudioDeviceChanged(com.avaya.clientservices.media.AudioDevice newDevice)

      Description copied from interface: `com.avaya.clientservices.media.AudioDeviceListener`
      Called when the active audio device has changed via the AudioInterface API. The callback occurs after the device becomes active, i.e., for Bluetooth after the SCO connection is established.
      Specified by:
        `onAudioDeviceChanged` in interface `com.avaya.clientservices.media.AudioDeviceListener`
      Parameters:
        `newDevice` - new active device.

    - #### onAudioDeviceError

          public void onAudioDeviceError(@NonNull
                                         com.avaya.clientservices.media.AudioDeviceError error)

      Description copied from interface: `com.avaya.clientservices.media.AudioDeviceListener`
      Audio state error occured.
      Specified by:
        `onAudioDeviceError` in interface `com.avaya.clientservices.media.AudioDeviceListener`
      Parameters:
        `error` - see AudioError enum.