Package com.avaya.clientservices.client

## Class Client

- java.lang.Object
- - com.avaya.clientservices.client.Client

-     public class Client
      extends java.lang.Object

  A Client is the primary interface for the Avaya Client Services library.

  ### Threading and Callback Handling

  Each Client operates an event loop on an internal thread, and this loop is used for most of the client's work. In order to simplify handling of callbacks from the client on an application thread (typically the UI thread) the client delivers callbacks via a Looper. By default this is the main looper and callbacks are delivered on the main thread, but a different Looper may be specified in the Client's constructor if desired.

  ### Shutdown

  As with most library actions, shutdown is asynchronous. After invoking `shutdown(boolean)` the library will complete any previously scheduled work then begin shutdown of the client. Each User registered with the client will be disconnected from the servers and removed, calling `onClientUserRemoved(Client, User)`. When all users have been removed `onShutdown(Client)` will be called. At this point the engine and any native resources supporting it are idle and it is safe to remove all references to the client.

  The application has the option of performing shutdown gracefully or ungracefully from the signaling perspective. In a graceful shutdown the client will attempt to end all sessions and unregister users before proceeding with cleanup of internal resources. This may take some time as it may require waiting on timeouts if the servers or remote end of sessions are unresponsive. In an ungraceful shutdown only local cleanup of resources is performed.

  Once shut down a Client instance cannot be reused.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `Client.LogLevel` | Log levels used by Avaya Client Services.
    `static interface` | `Client.LogListener` | Log message listener.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Client​(ClientConfiguration clientConfiguration, android.app.Application application, ClientListener listener)` | Constructs a client that delivers callbacks on the main thread.
    `Client​(ClientConfiguration clientConfiguration, android.app.Application application, ClientListener listener, android.os.Looper looper)` | Constructs a client that delivers callbacks on the thread associated with the specified Looper.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addDefaultNetworkListener​(DefaultNetworkListener listener)` | Adds a listener for this client.
    `void` | `addFIPSModeListener​(FIPSModeListener listener)` | Adds a FIPS-mode listener for this client.
    `void` | `addListener​(ClientListener listener)` | Adds a listener for this client.
    `void` | `createUser​(UserConfiguration userConfiguration, CreateUserCompletionHandler completionHandler)` | Start creating a new User using the specified configuration.
    `CertificateManager` | `getCertificateManager()` |
    `java.util.Set<java.lang.String>` | `getConfiguredCipherSuites()` |
    `DownloadService` | `getDownloadService()` |
    `static Client.LogLevel` | `getLogLevel()` |
    `MediaServicesInstance` | `getMediaEngine()` |
    `static java.lang.String` | `getVersion()` | Returns the library version.
    `boolean` | `isFIPSModeEnabled()` |
    `void` | `removeDefaultNetworkListener​(DefaultNetworkListener listener)` | Removes a listener from this client.
    `void` | `removeFIPSModeListener​(FIPSModeListener listener)` | Removes a FIPS-mode listener from this client.
    `void` | `removeListener​(ClientListener listener)` | Removes a listener from this client.
    `void` | `removeUser​(User user, boolean gracefulRemove)` | Starts an asynchronous removal of a user.
    `static void` | `setLogLevel​(Client.LogLevel level)` | Sets the log level for the library.
    `static void` | `setLogListener​(Client.LogListener listener)` | Sets an optional listener to handle log messages at the Java level.
    `void` | `shutdown​(boolean gracefulShutdown)` | Starts an asynchronous shutdown of the client.

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

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

- - ### Constructor Detail

    - #### Client

          public Client​(ClientConfiguration clientConfiguration,
                        android.app.Application application,
                        ClientListener listener)

      Constructs a client that delivers callbacks on the main thread.
      Parameters:
        `clientConfiguration` - the client configuration.
        `application` - The Application to associate this client with.
        `listener` - A listener to register for client events.
      Throws:
        `java.lang.SecurityException` - if the cellular network preference is indicated through `ClientConfiguration.setBindProcessToCellularEnabled(boolean)` but the caller has not acquired either of these permissions: Manifest.permission.CHANGE_NETWORK_STATE, Manifest.permission.WRITE_SETTINGS.

    - #### Client

          public Client​(ClientConfiguration clientConfiguration,
                        android.app.Application application,
                        ClientListener listener,
                        android.os.Looper looper)

      Constructs a client that delivers callbacks on the thread associated with the specified Looper.
      Parameters:
        `clientConfiguration` - the client configuration.
        `application` - The Application to associate this client with.
        `listener` - A listener to register for client events.
        `looper` - The looper to use for callbacks from the client.
      Throws:
        `java.lang.SecurityException` - if the cellular network preference is indicated through `ClientConfiguration.setBindProcessToCellularEnabled(boolean)` but the caller has not acquired Manifest.permission.CHANGE_NETWORK_STATE or Manifest.permission.CHANGE_NETWORK_STATE permission.

  - ### Method Detail

    - #### getLogLevel

          public static Client.LogLevel getLogLevel()

      Returns:
        the current log level for the library.

    - #### setLogLevel

          public static void setLogLevel​(Client.LogLevel level)

      Sets the log level for the library.
      Parameters:
        `level` - the log level for the library to be set.

    - #### setLogListener

          public static void setLogListener​(Client.LogListener listener)

      Sets an optional listener to handle log messages at the Java level. By default the library writes its log output to logcat internally. If desired a log listener can be specified to handle logs in the application. Setting the listener to null restores use of the default logcat logger.
      Parameters:
        `listener` - The new listener or null to use the default logger.

    - #### getCertificateManager

          public CertificateManager getCertificateManager()

      Returns:
        an instance of Client SDK Certificate manager.

    - #### getDownloadService

          public DownloadService getDownloadService()

      Returns:
        an instance of Client SDK Download service.

    - #### getVersion

          public static java.lang.String getVersion()

      Returns the library version.
      Returns:
        the library version.

    - #### addListener

          public void addListener​(ClientListener listener)

      Adds a listener for this client.
      Parameters:
        `listener` - the listener to be added.

    - #### removeListener

          public void removeListener​(ClientListener listener)

      Removes a listener from this client.
      Parameters:
        `listener` - the listener to be removed.

    - #### addDefaultNetworkListener

          public void addDefaultNetworkListener​(DefaultNetworkListener listener)

      Adds a listener for this client.
      Parameters:
        `listener` - the network listener instance to add.

    - #### removeDefaultNetworkListener

          public void removeDefaultNetworkListener​(DefaultNetworkListener listener)

      Removes a listener from this client.
      Parameters:
        `listener` - the network listener instance to remove.

    - #### addFIPSModeListener

          public void addFIPSModeListener​(FIPSModeListener listener)

      Adds a FIPS-mode listener for this client.
      Parameters:
        `listener` - the listener to be added.

    - #### removeFIPSModeListener

          public void removeFIPSModeListener​(FIPSModeListener listener)

      Removes a FIPS-mode listener from this client.
      Parameters:
        `listener` - the listener to be removed.

    - #### getMediaEngine

          public MediaServicesInstance getMediaEngine()

      Returns:
        media engine instance.

    - #### createUser

          public void createUser​(UserConfiguration userConfiguration,
                                 CreateUserCompletionHandler completionHandler)

      Start creating a new User using the specified configuration.

      The result will be reported using the provided completion handler, which will include the new User object on success.

      Parameters:
        `userConfiguration` - Configuration to use for creating the new User.
        `completionHandler` - Completion handler for reporting when the operation has succeeded or failed.
      Throws:
        `java.lang.IllegalArgumentException` - if the Client is in an invalid state.

    - #### removeUser

          public void removeUser​(User user,
                                 boolean gracefulRemove)

      Starts an asynchronous removal of a user.

      A user and associated sessions will be removed, all sockets closed, all services shut down and other internal resources released. When removal is complete, the `onClientUserRemoved(Client, User)` event will be fired. At that point, it is safe to dispose of the user.

      Removal may be graceful or ungraceful from the signaling perspective. In a graceful removal, it will attempt to disconnect all established connections used by the user and to unregister the user with servers if applicable, before proceeding with shutdown and cleanup of internal resources allocated for the user. It will wait to ensure that all the required signaling is exchanged with the servers before the shutdown operation is reported as complete. This graceful shutdown operation may take some time as it may require waiting on timeouts if the server or remote end of sessions are unreachable or unresponsive. In an ungraceful removal, only shutdown of local services and local resource cleanup for the user are performed.

      Parameters:
        `user` - The user to remove.
        `gracefulRemove` - true if an attempt should be made to disconnect user from servers, to wait for signaling completed, before cleanup of local resources (a graceful removal). false if local-only removal should be performed (an ungraceful removal).

    - #### shutdown

          public void shutdown​(boolean gracefulShutdown)

      Starts an asynchronous shutdown of the client.

      All users and associated sessions will be removed, all sockets closed, all services shut down and other internal resources released. When shutdown is complete, onClientShutdown() will be called on the ClientListeners. At that point, it is safe to dispose of the client.

      Shutdown may be graceful or ungraceful from the signaling perspective. In a graceful shutdown, it will attempt to disconnect all established connections with servers and to unregister users with servers if applicable, before proceeding with shutdown and cleanup of internal resources. It will wait to ensure that all the required signaling is exchanged with the servers before the shutdown operation is reported as complete. This graceful shutdown operation may take some time as it may require In an ungraceful shutdown, only shutdown of local services and local resource cleanup are performed.

      Parameters:
        `gracefulShutdown` - true if an attempt should be made to disconnect users from servers, to wait for signaling completed, before cleanup of local resources (a graceful shutdown). false if local-only shutdown should be performed (an ungraceful shutdown).

    - #### isFIPSModeEnabled

          public boolean isFIPSModeEnabled()

      Returns:
        The current state of FIPS (true = FIPS-compliant algorithms are in use.

    - #### getConfiguredCipherSuites

          public java.util.Set<java.lang.String> getConfiguredCipherSuites()

      Returns:
        Set of configured cipher suites excluding the black listed cipher suites in `SecurityPolicyConfiguration`