Package com.avaya.clientservices.presence

## Interface PresenceService

-     public interface PresenceService

  The class encapsulates all of presence related features available to the user.

  The presence service encapsulates such features as publishing presence, subscribing for self-presence update events, and creating presence list subscriptions to watch presence of other users.

  The service is configured with `PresenceConfiguration` object created by the client application as part of the `UserConfiguration`. In order to get the service object and leverage the available presence features `User.getPresenceService()` is used.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addListener​(PresenceServiceListener listener)` | Adds the listener.
    `PresenceListSubscription` | `createPresenceListSubscription()` | Creates a new empty ad-hoc presence subscription object.
    `long` | `getAutoAwayTimeout()` | The user inactivity timeout period in milliseconds.
    `Capability` | `getAutomaticModeCapability()` | Returns Capability object describing whether the Presence service supports automatic mode for self-presence.
    `java.util.Set<PresenceState>` | `getAutomaticPresenceStates()` | Gets a list of supported automatic self-presence states.
    `java.util.Set<PresenceState>` | `getManualPresenceStates()` | Gets a list of supported manual self-presence states.
    `PresenceAccessControlList` | `getPresenceAccessControlList()` | Method to get `PresenceAccessControlList` object.
    `Capability` | `getPresenceAccessControlListCapability()` | Returns Capability object describing whether the Presence service supports Presence Access Control List(ACL).
    `int` | `getPresenceNoteMaxTextLength()` | Get the maximum text length value (in characters) accepted for presence note.
    `Presence` | `getSelfPresence()` | Method to get current self-presence based on the last received presence data from the presence server.
    `boolean` | `getSendAllCallsOnDoNotDisturb()` | Indicates a link between "Do Not Disturb" presence state and "Send All Calls" call service feature.
    `boolean` | `isServiceAvailable()` | Exposes the service availability status.
    `boolean` | `isServiceConfigured()` | Exposes the service configuration status
    `void` | `publishPresence​(Presence presence)` | Publishes presence state, location mode and optional note for the local user.
    `void` | `removeListener​(PresenceServiceListener listener)` | Removes the listener.
    `void` | `removePresenceListSubscription​(PresenceListSubscription subscription)` | Removes the specified presence list subscription.
    `void` | `setAutoAwayTimeout​(long autoAwayTimeout)` | Sets the timeout for the user inactivity timer at runtime.
    `void` | `setSendAllCallsOnDoNotDisturb​(boolean enabled)` | Sets a link between "Do Not Disturb" presence state and "Send All Calls" call service feature at runtime.

- - ### Method Detail

    - #### addListener

          void addListener​(PresenceServiceListener listener)

      Adds the listener.
      Parameters:
        `listener` - Listener instance to be added.

    - #### removeListener

          void removeListener​(PresenceServiceListener listener)

      Removes the listener.
      Parameters:
        `listener` - Listener instance to be removed.

    - #### isServiceAvailable

          boolean isServiceAvailable()

      Exposes the service availability status.

      The service may become unavailable due to a number of reasons such as network issues, presence server issues, and configuration issues.

      Returns:
        true if the service is available, false otherwise.

    - #### isServiceConfigured

          boolean isServiceConfigured()

      Exposes the service configuration status

      Reflects the fact that the service is not provided with a valid `PresenceConfiguration` object or couldn't automatically discover its configuration.

      Returns:
        true if the service is configured, false otherwise.

    - #### publishPresence

          void publishPresence​(Presence presence)

      Publishes presence state, location mode and optional note for the local user.

      The result of the operation is delivered via `PresenceServiceListener` callbacks:

      - If presence information is published successfully `PresenceServiceListener.onPresencePublishSuccessful(PresenceService, Presence)` gets invoked.
      - Otherwise, `PresenceServiceListener.onPresencePublishFailed(PresenceService, Presence, String)` is reported respresenting the specific failure.

      In order to get the result the application must register the listener by calling #addListener(PresenceServiceListener).

      Parameters:
        `presence` - Presence information to publish.

    - #### createPresenceListSubscription

          PresenceListSubscription createPresenceListSubscription()

      Creates a new empty ad-hoc presence subscription object.

      An ad-hoc presence subscription object is used to manipulate the list of users the client application wants to know presence of. A PresenceListSubscription object allows the application to subscribe for presence events of multiple users specified by their presence addresses. Note that the preferred way of getting presence of other users is `Contact.startPresence(com.avaya.clientservices.contact.AccessControlBehavior, com.avaya.clientservices.presence.PresenceCompletionHandler)`.

      Returns:
        An empty `PresenceListSubscription` object.

    - #### removePresenceListSubscription

          void removePresenceListSubscription​(PresenceListSubscription subscription)

      Removes the specified presence list subscription.

      This method is used to stop getting presence updates for all of the users specified by the addresses added to the object.

      Parameters:
        `subscription` - Subscription to be removed.

    - #### setAutoAwayTimeout

          void setAutoAwayTimeout​(long autoAwayTimeout)

      Sets the timeout for the user inactivity timer at runtime.

      Inactivity timer is used to automatically change the user's presence state to 'away' if the user is inactive, i.e. not using the device with the installed application. When the timer fires, the user's presence is set to the 'away' state. If zero value is specified, the inactivity timer is disabled.

      Parameters:
        `autoAwayTimeout` - Timeout in milliseconds.

    - #### getAutoAwayTimeout

          long getAutoAwayTimeout()

      The user inactivity timeout period in milliseconds.
      Returns:
        Away timeout in milliseconds.

    - #### setSendAllCallsOnDoNotDisturb

          void setSendAllCallsOnDoNotDisturb​(boolean enabled)

      Sets a link between "Do Not Disturb" presence state and "Send All Calls" call service feature at runtime.

      If the link is enabled and "Send All Calls" feature is available, the following behavior applies.

      - Once the presence state of the user changes to "Do not Disturb", "Send All Calls" is automatically switched on.
      - If the presence state of the user changes from "Do not Disturb" to any other state, "Send All Calls" is automatically switched off.
      Parameters:
        `enabled` - A boolean value to enable or disable a link between "Do Not Disturb" presence state and "Send All Calls" call service feature.

    - #### getSendAllCallsOnDoNotDisturb

          boolean getSendAllCallsOnDoNotDisturb()

      Indicates a link between "Do Not Disturb" presence state and "Send All Calls" call service feature.
      Returns:
        true if the link between "Do Not Disturb" presence state and "Send All Calls" call service feature is enabled, false otherwise.
      See Also:
        `setSendAllCallsOnDoNotDisturb(boolean)`

    - #### getSelfPresence

          Presence getSelfPresence()

      Method to get current self-presence based on the last received presence data from the presence server.

      Self-presence describes overall presence status of the local user calculated by the presence server based on presence data information collected from various presence sources. The sources are communication devices and applications running on behalf of the user.

      Returns:
        current self-presence based on the last received presence data from the presence server.

    - #### getPresenceNoteMaxTextLength

          int getPresenceNoteMaxTextLength()

      Get the maximum text length value (in characters) accepted for presence note.
      Returns:
        the maximum text length value accepted for presence note.

    - #### getPresenceAccessControlListCapability

          Capability getPresenceAccessControlListCapability()

      Returns Capability object describing whether the Presence service supports Presence Access Control List(ACL).
      Returns:
        `Capability` object describing whether the Presence service supports Presence Access Control List(ACL).

    - #### getAutomaticModeCapability

          Capability getAutomaticModeCapability()

      Returns Capability object describing whether the Presence service supports automatic mode for self-presence.
      Returns:
        `Capability` object describing whether the Presence service supports automatic mode for self-presence.

    - #### getAutomaticPresenceStates

          java.util.Set<PresenceState> getAutomaticPresenceStates()

      Gets a list of supported automatic self-presence states.
      Returns:
        A list of supported automatic self-presence states.

    - #### getManualPresenceStates

          java.util.Set<PresenceState> getManualPresenceStates()

      Gets a list of supported manual self-presence states.
      Returns:
        A list of supported manual self-presence states.

    - #### getPresenceAccessControlList

          PresenceAccessControlList getPresenceAccessControlList()

      Method to get `PresenceAccessControlList` object.
      Returns:
        PresenceAccessControlList object.