< Back to Package Overview
Displaying Local Contacts
Using the Avaya Client SDK, you can easily access and use the database of local address book contacts users managed through the contacts app.
As you become more comfortable working with the Avaya Client SDK, the benefits of using the contacts API's and object definitions discussed in this article, rather than using the platform API's directly, will become clearer. This will be especially evident when working with enterprise shared contacts and accessing enterprise directory providers like Microsoft Active Directory which are additional capabilities that are exposed by the Avaya Client SDK and discussed in future articles.
To display contacts from your device, you must complete the following activities.
- Request User Permissions
- Enable local contacts service
- Implement the data retrieval watcher and contact delegate protocols
- Request local contacts
Request User Permissions
You do not need to request user permissions to access the local contacts on the device. Client SDK will do it for you.
You can enable local contacts service using the CSLocalContactConfiguration object and set it into the CSUserConfiguration object using localContactConfiguration property.
CSLocalContactConfiguration* localContactConfiguration =
[[CSLocalContactConfiguration alloc] init];
localContactConfiguration.enabled = YES;
userConfiguration.localContactConfiguration = localContactConfiguration;
This configuration step should be done before the User object is created.
In order to monitor the progress of retrieving the contacts, your application needs to create a CSDataRetrievalWatcher object and define an object that implements the <CSDataRetrievalWatcherDelegate> protocol. In addition, your application also needs to implement the <CSContactDelegate> protocol to handle local contact updates. The key functions for this objects are as follows:
- When the dataRetrievalWatcherDidComplete: method of the <CSDataRetrievalWatcherDelegate> is called (ie, data retrieval process is finished), get the snapshot property of the CSDataRetrievalWatcher object which contains the local contacts.
- Iterate over the snapshot array to get contacts and display these contacts on the user interface as appropriate.
- Implement the dataRetrievalWatcher:contentsDidChange:changedItems: of the <CSDataRetrievalWatcherDelegate> to handle adding, updating and deleting local contacts on the device after the initial retrieval is completed.
- Optionally register as a <CSContactDelegate> for each <CSContact> object in the snapshot array to handle their updates individually.
@interface AppContactHandler()
@property (nonatomic, strong) CSDataRetrievalWatcher *watcher;
...
@end
@implementation AppContactHandler
- (void) startWithContactService: (CSContactService*) contactService {
self.watcher = [[CSDataRetrievalWatcher alloc] init];
[self.watcher addDelegate: self];
[contactService retrieveContactsForSource: CSContactSourceTypeLocal
watcher: self.watcher];
}
- (void) dataRetrievalWatcherDidComplete:
(CSDataRetrievalWatcher*) dataRetrievalWatcher {
// Initialize your contact array from the CSDataRetrievalWatcher object
NSArray *contactsSnapshot = dataRetrievalWatcher.snapshot;
// Add all retrieved contacts for display
[self.displayNames removeAllObjects];
for (CSContact *contact in contactsSnapshot) {
// For example, get the name and add to the internal list
NSString* displayName = [contact.displayName fieldValue];
[self.displayNames addObject: displayName];
// Add delegate in order to handle contact updates
contact.delegate = self;
}
// Add code to refresh the UI with the internal list
}
- (void)dataRetrievalWatcher: (CSDataRetrievalWatcher*) dataRetrievalWatcher
contentsDidChange: (CSDataCollectionChangeType) changeType
changedItems: (NSArray*) changedItems {
if (dataRetrievalWatcher.completed) {
// Add code to update application UI
// for added, updated and deleted local contacts
// after the initial retrieval is completed.
}
}
- (void)contactUpdated: (CSContact*) contact {
// Add code to update application UI for updated contact individually.
}
...
@end
You can use the CSContactService object to access the contacts on your local device and instantiate the AppContactHandler to handle the contact retrieval progress.
CSContactService* contactService = user.contactService;
// Create an application contact handler (AppContactHandler) object
// that receives contacts
AppContactHandler* appContactHandler = [[AppContactHandler alloc] init];
// Start receiving of the contact list and handling its updates
[appContactHandler startWithContactService: contactService];
