Package com.avaya.clientservices.contact

## Interface ContactService

-     public interface ContactService

  The ContactService object is accessible from the User object, and it provides access to functionality associated with contacts.

  The ContactService object provides a set of APIs that allow application developers to manage a user's contacts and perform searches for other users. In general, the capabilities and the set of allowed operations are dependent on the state of the contact related servers and services.

  The client application is notified about status updates reported by the contact services through listener that the application has added to the ContactService object. These updates may be the result of local operations on the ContactService object as well as remote changes initiated by either the service/server or other users.

  In order to retrieve a list of contacts, call `getContacts(DataRetrievalWatcher, ContactSourceType)` method. This should be done after `ContactServiceListener.onContactServiceAvailable(ContactService)` was called.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addContact​(EditableContact contact, AddContactCompletionHandler completionHandler)` | Adds a new contact.
    `void` | `addListener​(ContactServiceListener listener)` | Add a listener.
    `void` | `changeSearchContactsRequest​(DataRetrievalWatcher<Contact> watcher, java.lang.String newSearchString)` | Deprecated. THIS METHOD WILL BE REMOVED IN RELEASE VERSION 3.3.
    `void` | `createContactGroup​(java.lang.String groupName, java.util.Collection<Contact> groupMembers, CreateContactGroupCompletionHandler completionHandler)` | Creates a Contact Group with specified group name and group members.
    `EditableContact` | `createEditableContact()` | Creates a new `EditableContact` object with default values.
    `EditableContact` | `createEditableContactFromContact​(Contact contact)` | Creates a new editable contact object from a given existing contact.
    `void` | `deleteContact​(Contact contact, ContactCompletionHandler completionHandler)` | Deletes an existing contact.
    `void` | `deleteContactGroup​(ContactGroup group, ContactCompletionHandler completionHandler)` | Deletes Contact Group.
    `Capability` | `getAddContactCapability()` | Returns Capability object describing whether the Contact service supports adding contacts.
    `void` | `getContactGroups​(DataRetrievalWatcher<ContactGroup> watcher)` |
    `ContactLimits` | `getContactLimits()` | Provides supported limits for the current enterprise contact provider.
    `void` | `getContacts​(DataRetrievalWatcher<Contact> watcher, ContactSourceType contactSourceType)` | Get the contact list from the given source.
    `Capability` | `getCreateContactGroupCapability()` | Returns Capability object describing whether the Contact service supports contact groups creation.
    `Capability` | `getDeleteContactGroupCapability()` | Returns Capability object describing whether the Contact service supports contact groups removal.
    `Capability` | `getFavoriteContactsCapability()` | Returns Capability object describing whether the Contact service supports favorite contacts.
    `Contact` | `getMatchingContactForDirectoryContact​(Contact contact)` | Get matching contact (from cache) to the one from search results.
    `long` | `getMaxContactGroupNameLength()` | Returns maximum contact group name length
    `long` | `getMaxNumberOfContactGroups()` | Returns maximum number of contact groups
    `long` | `getMaxNumberOfContactsPerGroup()` | Returns maximum number of contacts per group
    `Capability` | `getNetworkContactSearchByDepartmentCapability()` | Returns Capability object describing whether the Contact service supports contact search by department.
    `Capability` | `getNetworkContactSearchByLocationCapability()` | Returns Capability object describing whether the Contact service supports contact search by location.
    `Capability` | `getNetworkContactSearchByNameCapability()` | Returns Capability object describing whether the Contact service supports contact search by name.
    `Capability` | `getNetworkSearchContactCapability()` | Returns Capability object describing whether the Contact service supports searching contacts.
    `Capability` | `getNetworkSearchTerminalCapability()` | Returns Capability object describing whether the Contact service supports searching terminals.
    `java.util.List<ContactSourceType>` | `getOnlineContactProviderSourceTypes()` |
    `Capability` | `getResolveEnterpriseContactsCapability()` | Returns Capability object describing whether the Contact service supports `resolveContacts` functionality.
    `void` | `getSelfContact​(GetSelfContactCompletionHandler completionHandler)` | Gets the contact information for the currently logged-in user.
    `java.util.Set<ContactPhoneNumberType>` | `getSupportedPhoneNumberTypes()` | Deprecated. THIS METHOD WILL BE REMOVED IN RELEASE VERSION 3.3.
    `boolean` | `isContactGroupsSupported()` | Returns true if the Contact service supports Contacts Groups functionality.
    `boolean` | `isExtendedContactDetailsAvailable()` | Returns true if provider with ExtendedDetailsCapability is configured.
    `boolean` | `isExtendedContactDetailsAvailableForContact​(BaseContact baseContact)` | Returns true if `BaseContact` has extended details available.
    `boolean` | `isServiceAvailable()` | Returns true if the Contact service is available.
    `void` | `removeListener​(ContactServiceListener listener)` | Remove a listener.
    `void` | `resolveContacts​(ResolveContactsRequest request)` | Search for the contacts with given request parameters.
    `MatchedContactsWithMatchLevel` | `searchCachedContacts​(java.lang.String searchString, ContactSearchScopeType searchScope)` | Deprecated. THIS METHOD WILL BE REMOVED IN RELEASE VERSION 3.3.
    `void` | `searchContacts​(DataRetrievalWatcher<Contact> watcher, ContactSearchRequest request)` | Extended search for the contacts with given request parameters.
    `void` | `searchContacts​(DataRetrievalWatcher<Contact> watcher, java.lang.String searchString, ContactSearchScopeType searchScope, ContactSearchLocationType searchLocation, int maxResults, int maxChunkSize)` | Search for the contacts with given request parameters.
    `void` | `searchTerminals​(DataRetrievalWatcher<Terminal> watcher, SearchTerminalsRequest request)` | Search for the terminals with given request parameters.
    `void` | `updateContact​(EditableContact contact, UpdateContactCompletionHandler completionHandler)` | Updates an existing contact.

- - ### Method Detail

    - #### addListener

          void addListener​(ContactServiceListener listener)

      Add a listener.
      Parameters:
        `listener` - `ContactServiceListener` instance to be added.

    - #### removeListener

          void removeListener​(ContactServiceListener listener)

      Remove a listener.
      Parameters:
        `listener` - `ContactServiceListener` instance to be removed.

    - #### isServiceAvailable

          boolean isServiceAvailable()

      Returns true if the Contact service is available.
      Returns:
        true if the Contact service is available.

    - #### getContacts

          void getContacts​(DataRetrievalWatcher<Contact> watcher,
                           ContactSourceType contactSourceType)

      Get the contact list from the given source.
      Parameters:
        `watcher` - A `DataRetrievalWatcher` object, created by the application, to track the progress of the requested contact retrieval. Prior to calling this method, the application should have installed a `DataRetrievalWatcherListener` on the watcher object to receive notifications on the progress of the retrieval.
        `contactSourceType` - The type of contacts to retrieve.
      Throws:
        `java.lang.IllegalArgumentException` - The watcher argument was null.

    - #### createEditableContactFromContact

          EditableContact createEditableContactFromContact​(Contact contact)

      Creates a new editable contact object from a given existing contact.

      This function can be used to create a new local contact from the results of a directory search performed by the `searchContacts(DataRetrievalWatcher, String, ContactSearchScopeType, ContactSearchLocationType, int, int)` method. After creating an EditableContact from one of the search results, call the addContact method to create and save the new contact. Creating an enterprise contact from a local contact can be done using the same approach.

      This method must be used to update an existing contact as well. After the new `EditableContact` is created, and the desired contact fields have been updated, use the `updateContact(EditableContact, UpdateContactCompletionHandler)` method to send a request.

      Parameters:
        `contact` - The contact whose current values will be used to populate the new `EditableContact`.
      Returns:
        An `EditableContact` that has all the editable properties set based on the specified input contact. Note that fields not supported by the enterprise source will not be used.
      See Also:
        `createEditableContact()`, `addContact(EditableContact, AddContactCompletionHandler)`, `updateContact(EditableContact, UpdateContactCompletionHandler)`

    - #### createEditableContact

          EditableContact createEditableContact()

      Creates a new `EditableContact` object with default values.

      This method must be used to create a new `EditableContact` object before calling the `addContact(EditableContact, AddContactCompletionHandler)` method.

      Returns:
        `EditableContact` that has all the editable properties set to default values (source and capability).
      See Also:
        `createEditableContactFromContact(Contact)`, `addContact(EditableContact, AddContactCompletionHandler)`

    - #### addContact

          void addContact​(EditableContact contact,
                          AddContactCompletionHandler completionHandler)

      Adds a new contact.
      Parameters:
        `contact` - The editable contact used to create the new contact. This editable contact can be created using one of the following methods:
        - by calling `createEditableContact()` and then filling in the fields appropriately.
        - by calling `createEditableContactFromContact(Contact)` to populate the editable contact from a directory search result.
        `completionHandler` - The completion handler for this operation.
      See Also:
        `getAddContactCapability()`, `updateContact(EditableContact, UpdateContactCompletionHandler)`, `deleteContact(Contact, ContactCompletionHandler)`

    - #### updateContact

          void updateContact​(EditableContact contact,
                             UpdateContactCompletionHandler completionHandler)

      Updates an existing contact.

      Note that there can be only one request for each EditableContact at the same time. Before the operation will return a result, all subsequent attempts to update or add same contact will result in instant failure and according error code.

      Parameters:
        `contact` - The editable contact object used to update this record on the enterprise source. This object must be created from a regular immutable contact by calling `createEditableContactFromContact(Contact)`
        `completionHandler` - The completion handler for this operation.
      See Also:
        `Contact.getUpdateContactCapability()`, `deleteContact(Contact, ContactCompletionHandler)`

    - #### deleteContact

          void deleteContact​(Contact contact,
                             ContactCompletionHandler completionHandler)

      Deletes an existing contact.

      Note that there can be only one request for each EditableContact at the same time. Before the operation will return a result, all subsequent attempts ro remove or retrieve picture for this contact will result in instant failure and according error code.

      Parameters:
        `contact` - The contact to be deleted.
        `completionHandler` - The completion handler for this operation.
      See Also:
        `Contact.getDeleteContactCapability()`

    - #### searchContacts

          void searchContacts​(DataRetrievalWatcher<Contact> watcher,
                              java.lang.String searchString,
                              ContactSearchScopeType searchScope,
                              ContactSearchLocationType searchLocation,
                              int maxResults,
                              int maxChunkSize)

      Search for the contacts with given request parameters. There can be only one search in progress with a particular string. If such a search already exists, a new one won't be started.
      Parameters:
        `watcher` - A DataRetrievalWatcher object, created by the application, to track the progress of the requested operation. Prior to calling this method, the application should have installed a `DataRetrievalWatcherListener` on the watcher object to receive notifications on the progress of the retrieval.
        `searchString` - The search string, can be first name, last name, phone number.
        `searchScope` - Identifies which field or fields to search in. Specify appropriate `ContactSearchScopeType`
        `searchLocation` - Determines which contacts will be searched.
        `maxResults` - The maximum number of results to return.
        `maxChunkSize` - The number of results to return in each update from the server.
      Throws:
        `java.lang.IllegalArgumentException` - The watcher argument was null.
      See Also:
        `getNetworkSearchContactCapability()`

    - #### searchCachedContacts

          @Deprecated
          MatchedContactsWithMatchLevel searchCachedContacts​(java.lang.String searchString,
                                                             ContactSearchScopeType searchScope)

      Deprecated.
      THIS METHOD WILL BE REMOVED IN RELEASE VERSION 3.3. Use `resolveContacts(ResolveContactsRequest)` instead.
      Search for the contacts in application cache with given search string. Contact cache is built from all retrieved items regardless of whether the `getContacts(DataRetrievalWatcher, ContactSourceType)` method was called.
      Parameters:
        `searchString` - The search string, can be first name, last name, phone number.
        `searchScope` - Identifies which field or fields to search in. Specify appropriate `ContactSearchScopeType`
      Returns:
        Contacts with match type.

    - #### changeSearchContactsRequest

          @Deprecated
          void changeSearchContactsRequest​(DataRetrievalWatcher<Contact> watcher,
                                           java.lang.String newSearchString)

      Deprecated.
      THIS METHOD WILL BE REMOVED IN RELEASE VERSION 3.3.
      Change the search contacts request with given new query string. All other parameters are immutable.
      Parameters:
        `watcher` - The existing data retrieval watcher that was created by the previous `searchContacts(DataRetrievalWatcher, String, ContactSearchScopeType, ContactSearchLocationType, int, int)` method call.
        `newSearchString` - The new search string.
      Throws:
        `java.lang.IllegalArgumentException` - The watcher argument was null.
      See Also:
        `getNetworkSearchContactCapability()`

    - #### getAddContactCapability

          Capability getAddContactCapability()

      Returns Capability object describing whether the Contact service supports adding contacts.
      Returns:
        `Capability` object describing whether the Contact service supports adding contacts.

    - #### getNetworkSearchContactCapability

          Capability getNetworkSearchContactCapability()

      Returns Capability object describing whether the Contact service supports searching contacts.
      Returns:
        `Capability` object describing whether the Contact service supports searching contacts.

    - #### getResolveEnterpriseContactsCapability

          Capability getResolveEnterpriseContactsCapability()

      Returns Capability object describing whether the Contact service supports `resolveContacts` functionality.
      Returns:
        Capability object describing whether the Contact service supports `resolveContacts` functionality. This capability only covers searches where the `ContactSearchLocationType` argument is set to NETWORK. For searches where the `ContactSearchLocationType` argument is LOCAL_CACHE, the `ContactServiceListener.onContactServiceLoadingComplete(ContactService, ContactSourceType, boolean)` callback where the contactLoadingComplete flag is true, indicates that the user's local contacts have been loaded and local searches should complete successfully. For searches where the `ContactSearchLocationType` argument is ALL, the LOCAL_CACHE search is executed first. In case no results are found NETWORK search is triggered.

    - #### getNetworkSearchTerminalCapability

          Capability getNetworkSearchTerminalCapability()

      Returns Capability object describing whether the Contact service supports searching terminals.
      Returns:
        `Capability` object describing whether the Contact service supports searching terminals.

    - #### getNetworkContactSearchByNameCapability

          Capability getNetworkContactSearchByNameCapability()

      Returns Capability object describing whether the Contact service supports contact search by name.
      Returns:
        `Capability` object describing whether the Contact service supports contact search by name.

    - #### getNetworkContactSearchByLocationCapability

          Capability getNetworkContactSearchByLocationCapability()

      Returns Capability object describing whether the Contact service supports contact search by location.
      Returns:
        `Capability` object describing whether the Contact service supports contact search by location.

    - #### getNetworkContactSearchByDepartmentCapability

          Capability getNetworkContactSearchByDepartmentCapability()

      Returns Capability object describing whether the Contact service supports contact search by department.
      Returns:
        `Capability` object describing whether the Contact service supports contact search by department.

    - #### getFavoriteContactsCapability

          Capability getFavoriteContactsCapability()

      Returns Capability object describing whether the Contact service supports favorite contacts.
      Returns:
        Capability object describing whether the Contact service supports favorite contacts.

    - #### getCreateContactGroupCapability

          Capability getCreateContactGroupCapability()

      Returns Capability object describing whether the Contact service supports contact groups creation.
      Returns:
        Capability object describing whether the Contact service supports contact groups creation.

    - #### getDeleteContactGroupCapability

          Capability getDeleteContactGroupCapability()

      Returns Capability object describing whether the Contact service supports contact groups removal.
      Returns:
        Capability object describing whether the Contact service supports contact groups removal.

    - #### getMaxContactGroupNameLength

          long getMaxContactGroupNameLength()

      Returns maximum contact group name length
      Returns:
        maximum contact group name length

    - #### getMaxNumberOfContactGroups

          long getMaxNumberOfContactGroups()

      Returns maximum number of contact groups
      Returns:
        maximum number of contact groups

    - #### getMaxNumberOfContactsPerGroup

          long getMaxNumberOfContactsPerGroup()

      Returns maximum number of contacts per group
      Returns:
        maximum number of contacts per group

    - #### isContactGroupsSupported

          boolean isContactGroupsSupported()

      Returns true if the Contact service supports Contacts Groups functionality.
      Returns:
        true if the Contact service supports Contacts Groups functionality.

    - #### getOnlineContactProviderSourceTypes

          java.util.List<ContactSourceType> getOnlineContactProviderSourceTypes()

      Returns:
        The list of available and online `ContactSourceType` If there is more than one source, the `ContactSourceType.ALL` source will be added into the online list.

    - #### isExtendedContactDetailsAvailable

          boolean isExtendedContactDetailsAvailable()

      Returns true if provider with ExtendedDetailsCapability is configured. Provider with this capability supports more fields for contacts.
      Returns:
        true if provider with ExtendedDetailsCapability is configured. Provider with this capability supports more fields for contacts.

    - #### isExtendedContactDetailsAvailableForContact

          boolean isExtendedContactDetailsAvailableForContact​(BaseContact baseContact)

      Returns true if `BaseContact` has extended details available. This means contact supports more fields.
      Parameters:
        `baseContact` - The contact to check for.
      Returns:
        True if contact has extended details available.

    - #### getSupportedPhoneNumberTypes

          @Deprecated
          java.util.Set<ContactPhoneNumberType> getSupportedPhoneNumberTypes()

      Deprecated.
      THIS METHOD WILL BE REMOVED IN RELEASE VERSION 3.3. it is recommended to use `getContactLimits()`.
      Returns Set of supported by current provider phone number types
      Returns:
        The Set of supported `ContactPhoneNumberType`

    - #### getSelfContact

          void getSelfContact​(GetSelfContactCompletionHandler completionHandler)

      Gets the contact information for the currently logged-in user.

      It is possible for no contact record to be found for the current user. In this case the application should fall back to other methods for retrieving or displaying contact information for the current user.

      Parameters:
        `completionHandler` - The completion handler for this operation. Operation success or failure is reported through this handler.
      See Also:
        `ContactServiceListener.onContactServiceSelfContactUpdated(ContactService, Contact)`

    - #### getMatchingContactForDirectoryContact

          Contact getMatchingContactForDirectoryContact​(Contact contact)

      Get matching contact (from cache) to the one from search results. Returns null if contact is not found.
      Parameters:
        `contact` - the contact received from search.
      Returns:
        matching contact (from cache) to the one from search results or null if contact is not found

    - #### getContactLimits

          ContactLimits getContactLimits()

      Provides supported limits for the current enterprise contact provider.
      Returns:
        supported limits for the current enterprise contact provider.

    - #### resolveContacts

          void resolveContacts​(ResolveContactsRequest request)

      Search for the contacts with given request parameters. There can be only one search in progress with a particular string. If such a search already exists, a new one won't be started. During the search onCollectionChanged and onRetrievalFailed callbacks may be triggered multiple times if there are multiple search locations. The search is complete when the onRetrievalCompleted callback is triggered on watcher.
      Parameters:
        `request` - object, encapsulates Resolve Contacts search request. Contains search strings, searching scope and source.
      See Also:
        `getResolveEnterpriseContactsCapability()`

    - #### searchTerminals

          void searchTerminals​(DataRetrievalWatcher<Terminal> watcher,
                               SearchTerminalsRequest request)

      Search for the terminals with given request parameters. There can be only one search in progress with a particular request. If such a search already exists, a new one won't be started.
      Parameters:
        `watcher` - A DataRetrievalWatcher object, created by the application, to track the progress of the requested operation. Prior to calling this method, the application should have installed a `DataRetrievalWatcherListener` on the watcher object to receive notifications on the progress of the retrieval.
        `request` - A `SearchTerminalsRequest` object containing search parameters.
      Throws:
        `java.lang.IllegalArgumentException` - The watcher argument was null.
      See Also:
        `getNetworkSearchTerminalCapability()`

    - #### searchContacts

          void searchContacts​(DataRetrievalWatcher<Contact> watcher,
                              ContactSearchRequest request)

      Extended search for the contacts with given request parameters.
      Parameters:
        `watcher` - A DataRetrievalWatcher object, created by the application, to track the progress of the requested operation. Prior to calling this method, the application should have installed a `DataRetrievalWatcherListener` on the watcher object to receive notifications on the progress of the retrieval.
        `request` - A `ContactSearchRequest` object containing search parameters. A `onRetrievalFailed(INVALID_SEARCH_REQUEST)` will be notified for null request.
      Throws:
        `java.lang.IllegalArgumentException` - The watcher argument was null.

    - #### createContactGroup

          void createContactGroup​(java.lang.String groupName,
                                  java.util.Collection<Contact> groupMembers,
                                  CreateContactGroupCompletionHandler completionHandler)

      Creates a Contact Group with specified group name and group members. Group members can be ommited. In this case Contact Service creates Contact Group with empty list of contacts.
      Parameters:
        `groupName` - Unique name of the group. Group name length is limited by the server. There are some characters not allowed to be present in group name (< > , ").
        `groupMembers` - Collection of contacts to add into a group during creation.
        `completionHandler` - The completion handler for this operation.

    - #### deleteContactGroup

          void deleteContactGroup​(ContactGroup group,
                                  ContactCompletionHandler completionHandler)

      Deletes Contact Group.
      Parameters:
        `group` - Group of contacts for removal.
        `completionHandler` - The completion handler for this operation.

    - #### getContactGroups

          void getContactGroups​(DataRetrievalWatcher<ContactGroup> watcher)

      Parameters:
        `watcher` - A DataRetrievalWatcher object, created by the application, to track the progress of the requested operation. Prior to calling this method, the application should have installed a `DataRetrievalWatcherListener` on the watcher object to receive notifications on the progress of the retrieval.