Avaya Client Services API Reference (OS X)

- Main Page
- Classes
- Files
- Related Pages

- Class List
- Class Index
- Class Hierarchy
- Class Members

Instance Methods | Properties | List of all members
CSContactService Class Reference

The CSContactService object is accessible from the CSUser object, and providing access to functionality associated with contacts. More...

`#import <CSContactService.h>`

Inherits NSObject.

## Instance Methods
(void) | - retrieveContactsForSource:watcher:
| Retrieves the contact list from the given source. More...
(void) | - retrieveSelfContactWithCompletionHandler:
| Gets the contact information for the currently logged-in user. More...
(void) | - searchContactsWithSearchString:searchScope:searchLocation:maxNumberOfResults:maxChunkSize:watcher:
| Search for the contacts with given request parameters. More...
(void) | - searchTerminalsWithRequest:watcher:
| Search for the terminals with given request parameters. More...
(void) | - searchContactsWithRequest:watcher:
| Extended search for the contacts with given request parameters. More...
(CSMatchedContactsWithMatchLevel *) | - searchCachedContactsWithSearchString:searchScope:
| Search for the contacts in application cache with given search string. More...
(CSContact *) | - getMatchingContactForDirectoryContact:
| Get matching contact (from cache) to the one from search results. More...
(void) | - changeSearchRequestWithSearchString:forWatcher:
| Change the search contacts request with a given new query string. More...
(void) | - addContact:completionHandler:
| Adds a new contact. More...
(void) | - updateContact:completionHandler:
| Update an existing contact. More...
(void) | - deleteContact:completionHandler:
| Delete an existing contact. More...
(CSEditableContact *) | - createEditableContactFromContact:
| Creates a new editable contact object from a given existing contact. More...
(CSEditableContact *) | - createEditableContact
| Creates a new CSEditableContact object with default values. More...
(void) | - resolveContacts:
| Search for the contacts with given request parameters. More...
(void) | - createContactGroupWithName:members:completionHandler:
| Creates a Contact Group with specified group name and group members. More...
(void) | - deleteContactGroup:completionHandler:
| Deletes Contact Group. More...
(void) | - retrieveContactGroupsWithWatcher:
| Retrieves the contact groups. More...

## Properties
id< CSContactServiceDelegate > | delegate
| The delegate responsible for handling contact service related events such as updated, deleted, added, capabilties changed, return results. More...
BOOL | serviceAvailable
| Returns YES if the Contact service is available. More...
NSArray * | availableContactSourceTypes
CSCapability * | deleteContactCapability
| Returns CSCapability object describing whether the Contact service supports deleting contacts. More...
CSCapability * | addContactCapability
| Returns CSCapability object describing whether the Contact service supports adding contacts. More...
CSCapability * | networkSearchContactCapability
| Returns Capability object describing whether the Contact service supports searching contacts. More...
CSCapability * | networkSearchTerminalCapability
| Returns Capability object describing whether the Contact service supports searching terminals. More...
CSCapability * | networkContactSearchByNameCapability
| Returns Capability object describing whether the Contact service supports contact search by name. More...
CSCapability * | networkContactSearchByLocationCapability
| Returns Capability object describing whether the Contact service supports contact search by location. More...
CSCapability * | networkContactSearchByDepartmentCapability
| Returns Capability object describing whether the Contact service supports contact search by department. More...
CSCapability * | updateContactCapability
| Returns CSCapability object describing whether the Contact service supports updating contacts. More...
CSCapability * | favoriteContactsCapability
| Returns CSCapability object describing whether the Contact service supports favorite contacts. More...
CSCapability * | resolveEnterpriseContactsCapability
| Returns CSCapability object describing whether the Contact service supports resolveContacts:. More...
NSSet * | supportedPhoneNumberTypes
| Returns NSSet of supported by current provider phone number types packed as NSNumber. More...
CSContactLimits * | contactLimits
| Provides supported limits for the current enterprise contact provider. More...
CSCapability * | createContactGroupCapability
| Capability describing whether the Contact Service supports Contact Group creation or not. More...
CSCapability * | deleteContactGroupCapability
| Capability describing whether the Contact Service supports Contact Group removal or not. More...
NSUInteger | maxContactGroupNameLength
| Maximum length of contact group name. More...
NSUInteger | maxNumberOfContactGroups
| Maximum number of Contact Groups allowed for usage. More...
NSUInteger | maxNumberOfContactsPerGroup
| Maximum number of Contacts allowed per Group. More...
BOOL | contactGroupsSupported
| Returns YES if Contact service supports Contacts Groups functionality. More...

## Detailed Description

The CSContactService object is accessible from the CSUser object, and providing 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 a delegate that the application adds to the CSContactService 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 -[retrieveContactsForSource:watcher:] selector. This should be done after -[contactServiceAvailable:] was called.

## Method Documentation

- (void) addContact: |  | (CSEditableContact *) | contact
completionHandler: |  | (void(^)(CSContact *contact, BOOL contactWasMerged, NSError *error)) | 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: to populate the editable contact from a directory search result.
  completionHandler | The completion handler for this operation.

See also
  -[addContactCapability]
  -[- updateContact:completionHandler:]
  -[- deleteContact:completionHandler:]

- (void) changeSearchRequestWithSearchString: |  | (NSString *) | searchString
forWatcher: |  | (CSDataRetrievalWatcher *) | watcher

Change the search contacts request with a given new query string.

All other parameters are immutable.

Parameters

  searchString | Search string can be first first name, last name, display name, alias, phone numbers, email address, IM handle, city, department depending on selected scope.
  watcher | The existing data retrieval watcher that was created by the previous searchContactsWithSearchString:searchScope:searchLocation:maxNumberOfResults:maxChunkSize:watcher: selector call.

Deprecated:
  THIS SELECTOR WILL BE REMOVED IN RELEASE VERSION 3.3.

- (void) createContactGroupWithName: |  | (NSString *) | name
members: |  | (NSSet< CSContact * > *) | members
completionHandler: |  | (void(^)(CSContactGroup *contactGroup, NSError *error)) | 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

  name | 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 (&lt; &gt; , ").
  members | Set of contacts to add into a group during creation.
  completionHandler | The completion handler for this operation.

- (CSEditableContact *) createEditableContact |  |  |

Creates a new CSEditableContact object with default values.

This method must be used to create a new CSEditableContact object before calling the addContact:completionHandler: selector.

Returns
  CSEditableContact that has all the editable properties set to default values (source and capability).

See also
  - createEditableContactFromContact:
  - addContact:completionHandler:

- (CSEditableContact *) createEditableContactFromContact: |  | (CSContact *) | 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 searchContactsWithSearchString:searchScope:searchLocation:maxNumberOfResults:maxChunkSize:watcher: selector. After creating an CSEditableContact from one of the search results, call the addContact:completionHandler: selector 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 CSEditableContact is created, and the desired contact fields have been updated, use the updateContact:completionHandler: method to send a request.

Parameters

  contact | The contact whose current values will be used to populate the new CSEditableContact.

Returns
  An CSEditableContact 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:completionHandler:]
  -[- updateContact:completionHandler:]

- (void) deleteContact: |  | (CSContact *) | contact
completionHandler: |  | (void(^)(NSError *error)) | completionHandler

Delete an existing contact.

Note that there can be only one operation in progress for each CSEditableContact 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 contact to be deleted.
  completionHandler | The completion handler for this operation.

See also
  -[deleteContactCapability]

- (void) deleteContactGroup: |  | (CSContactGroup *) | group
completionHandler: |  | (void(^)(NSError *error)) | completionHandler

Deletes Contact Group.

Parameters

  group | Group of contacts for removal
  completionHandler | The completion handler for this operation.

- (CSContact *) getMatchingContactForDirectoryContact: |  | (CSContact *) | searchContact |

Get matching contact (from cache) to the one from search results.

Returns nil if contact is not found.

Parameters

  searchContact | the contact received from search.

Returns
  matching contact (from cache) to the one from search results or nil if contact is not found

- (void) resolveContacts: |  | (CSContactResolveContactsRequest *) | 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 contentsDidChange and didFailWithError callbacks may be triggered multiple times if there are multiple search locations. The search is complete when the dataRetrievalWatcherDidComplete callback is triggered on the watcher.

Parameters

  request | A CSContactResolveContactsRequest object, which encapsulates the resolve contact search request. Contains search strings, searching scope, and source.

See also
  resolveEnterpriseContactsCapability

- (void) retrieveContactGroupsWithWatcher: |  | (CSDataRetrievalWatcher *) | watcher |

Retrieves the contact groups.

Parameters

  watcher | A CSDataRetrievalWatcher object, created by the application, to track the progress of the requested contact groups retrieval. Prior to calling this method, the application should have installed a CSDataRetrievalWatcherDelegate on the watcher object to receive notifications on the progress of the retrieval.

The data items returned to the application via the watcher object will be of type CSContactGroup.

- (void) retrieveContactsForSource: |  | (CSContactSourceType) | contactSourceType
watcher: |  | (CSDataRetrievalWatcher *) | watcher

Retrieves the contact list from the given source.

Parameters

  contactSourceType | The type of contacts to retrieve. Specify CSContactSourceTypeAll to get contacts from all available sources.
  watcher | A CSDataRetrievalWatcher 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 CSDataRetrievalWatcherDelegate on the watcher object to receive notifications on the progress of the retrieval.

The data items returned to the application via the watcher object will be of type CSContact.

- (void) retrieveSelfContactWithCompletionHandler: |  | (void(^)(CSContact *contact, NSError *error)) | 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
  -[contactService:didUpdateSelfContact:]

- (CSMatchedContactsWithMatchLevel *) searchCachedContactsWithSearchString: |  | (NSString *) | searchString
searchScope: |  | (CSContactSearchScope) | searchScope

Search for the contacts in application cache with given search string.

Contact cache is built from all retrieved items regardless of whether the retrieveContactsForSource:watcher: selector was called.

Parameters

  searchString | Search string can be first first name, last name, display name, alias, phone numbers, email address, IM handle, city, department depending on selected scope.
  searchScope | Identifies which field or fields to search in. Specify appropriate CSContactSearchScope

Returns
  CSMatchedContactsWithMatchLevel structure which contains matches with match levels.

Deprecated:
  THIS SELECTOR WILL BE REMOVED IN RELEASE VERSION 3.3. It is recommended to use the resolveContacts: method instead.

- (void) searchContactsWithRequest: |  | (CSContactSearchRequest *) | request
watcher: |  | (CSDataRetrievalWatcher *) | watcher

Extended search for the contacts with given request parameters.

Parameters

  request | A CSContactSearchRequest object containing search 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 CSDataRetrievalWatcherDelegate on the watcher object to receive notifications on the progress of the retrieval. The data items returned to the application via the watcher object will be of type CSContact.

- (void) searchContactsWithSearchString: |  | (NSString *) | searchString
searchScope: |  | (CSContactSearchScope) | searchScope
searchLocation: |  | (CSContactSearchLocation) | searchLocation
maxNumberOfResults: |  | (unsigned int) | maxResults
maxChunkSize: |  | (unsigned int) | maxChunkSize
watcher: |  | (CSDataRetrievalWatcher *) | watcher

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 CSDataRetrievalWatcherDelegate 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 CSContactSearchScope
  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. The data items returned to the application via the watcher object will be of type CSContact.

- (void) searchTerminalsWithRequest: |  | (CSSearchTerminalsRequest *) | request
watcher: |  | (CSDataRetrievalWatcher *) | watcher

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

  request | A CSSearchTerminalsRequest object containing search 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 CSDataRetrievalWatcherDelegate on the watcher object to receive notifications on the progress of the retrieval. The data items returned to the application via the watcher object will be of type CSTerminal.

- (void) updateContact: |  | (CSEditableContact *) | contact
completionHandler: |  | (void(^)(CSContact *contact, NSError *error)) | completionHandler

Update an existing contact.

Note that there can be only one operation in progress for each CSEditableContact 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:
  completionHandler | The completion handler for this operation.

See also
  -[updateContactCapability]
  -[deleteContact:completionHandler]

## Property Documentation

- (CSCapability*) addContactCapability
| read nonatomic assign

Returns CSCapability object describing whether the Contact service supports adding contacts.

Returns
  CSCapability object describing whether the Contact service supports adding contacts.

- (NSArray*) availableContactSourceTypes
| read nonatomic assign

Returns
  The list of available and online CSContactSourceType If there is more than one source, the CSContactSourceTypeAll source will be added into the online list.

- (BOOL) contactGroupsSupported
| read nonatomic assign

Returns YES if Contact service supports Contacts Groups functionality.

Returns
  YES if Contact service supports Contacts Groups functionality.

- (CSContactLimits*) contactLimits
| read nonatomic assign

Provides supported limits for the current enterprise contact provider.

- (CSCapability*) createContactGroupCapability
| read nonatomic assign

Capability describing whether the Contact Service supports Contact Group creation or not.

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

- (id<CSContactServiceDelegate>) delegate
| read write nonatomic weak

The delegate responsible for handling contact service related events such as updated, deleted, added, capabilties changed, return results.

- (CSCapability*) deleteContactCapability
| read nonatomic assign

Returns CSCapability object describing whether the Contact service supports deleting contacts.

Returns
  CSCapability object describing whether the Contact service supports deleting contacts.

- (CSCapability*) deleteContactGroupCapability
| read nonatomic assign

Capability describing whether the Contact Service supports Contact Group removal or not.

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

- (CSCapability*) favoriteContactsCapability
| read nonatomic assign

Returns CSCapability object describing whether the Contact service supports favorite contacts.

Returns
  CSCapability object describing whether the Contact service supports favorite contacts.

- (NSUInteger) maxContactGroupNameLength
| read nonatomic assign

Maximum length of contact group name.

Returns
  Maximum length of contact group name.

- (NSUInteger) maxNumberOfContactGroups
| read nonatomic assign

Maximum number of Contact Groups allowed for usage.

Returns
  Maximum number of allowed Contact Groups.

- (NSUInteger) maxNumberOfContactsPerGroup
| read nonatomic assign

Maximum number of Contacts allowed per Group.

Returns
  Maximum number of Contacts allowed per Group.

- (CSCapability*) networkContactSearchByDepartmentCapability
| read nonatomic assign

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

Returns
  CSCapability object describing whether the Contact service supports contact search by department.

- (CSCapability*) networkContactSearchByLocationCapability
| read nonatomic assign

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

Returns
  CSCapability object describing whether the Contact service supports contact search by location.

- (CSCapability*) networkContactSearchByNameCapability
| read nonatomic assign

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

Returns
  CSCapability object describing whether the Contact service supports contact search by name.

- (CSCapability*) networkSearchContactCapability
| read nonatomic assign

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

Returns
  CSCapability object describing whether the Contact service supports searching contacts.

- (CSCapability*) networkSearchTerminalCapability
| read nonatomic assign

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

Returns
  CSCapability object describing whether the Contact service supports searching terminals.

- (CSCapability*) resolveEnterpriseContactsCapability
| read nonatomic assign

Returns CSCapability object describing whether the Contact service supports resolveContacts:.

Returns
  CSCapability object describing whether the Contact service supports resolveContacts:.

This capability only covers searches where the CSContactResolveContactsRequest.searchLocation property is set to CSContactSearchNetwork.

For searches where the `searchLocation` property is set to CSContactSearchLocalCache, the CSContactServiceDelegate::contactService:loadContactsCompleteForSource:doneLoadingAllSources: callback where the doneLoadingAllSources flag is `YES`, indicates that the user's local contacts have been loaded and local searches should complete successfully.

For searches where the `searchLocation` property is set to CSContactSearchAll, the CSContactSearchLocalCache search is executed first. In case no results are found CSContactSearchNetwork search is triggered.

- (BOOL) serviceAvailable
| read nonatomic assign

Returns YES if the Contact service is available.

Returns
  YES if the Contact service is available.

- (NSSet*) supportedPhoneNumberTypes
| read nonatomic assign

Returns NSSet of supported by current provider phone number types packed as NSNumber.

Returns
  The Set of supported CSContactPhoneNumberType.

Deprecated:
  THIS SELECTOR WILL BE REMOVED IN RELEASE VERSION 3.3. It is recommended to use the contactLimits property instead.

- (CSCapability*) updateContactCapability
| read nonatomic assign

Returns CSCapability object describing whether the Contact service supports updating contacts.

Returns
  CSCapability object describing whether the Contact service supports updating contacts.

The documentation for this class was generated from the following file:

- CSContactService.h