|
|||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | ||||||||
See:
Description
| Interface Summary | |
|---|---|
| AddressBookFieldFactory | Deprecated. use LinkedContactUtilities.registerLinkedContactInfoProvider(LinkedContactInfoProvider, long, int) |
| LinkableContact | Represents an object that is linkable with a contact in the contacts application. |
| LinkedContactCallback | An interface allowing access to linked contact information to be set. |
| LinkedContactConstants | Constants useful for linking application contacts to contacts in the contacts application. |
| Class Summary | |
|---|---|
| AbstractLinkableContact | Provides default implementations for some of the methods
in the LinkableContact interface. |
| DefaultLinkableContact | A simple implementation of LinkableContact. |
| LinkedContactInfoProvider | A provider to supply requested linked contact information. |
| LinkedContactUtilities | Provides utility methods for manipulating the contact list from other applications. |
Provides classes and interfaces for linking contacts in applications with contacts in the Contacts application.
You can link contact data in your application with contacts in the Contacts application on the BlackBerry® device by using the Contact Linking API in this package. A particular contact in the Contacts application can be linked with one contact in your application, though a contact in the Contacts application can be linked with contacts in multiple applications.
When linking to a contact in the Contacts application, you can use the Contact Linking API to perform some tasks automatically, such as searching for a matching contact in the Contacts application and checking to see whether a contact in the Contacts application is already linked to one of your contacts.
You can define the information to display in the Contacts application when the user is viewing a contact that is linked to one of your contacts. You can also create menu items that display in the Contacts application when a user views a linked contact.
The Contact Linking Demo sample application is included in the BlackBerry® Java® SDK. The application demonstrates how to use the Contact Linking API.
To link contacts in your application with contacts in the Contacts application:
Objects in your application that you want to link to a contact in the Contacts application must implement the LinkableContact
interface.
LinkableContact contains fields you can use to store information about your contact, such as
NAME,
EMAIL, and
HOME_PHONE.
A LinkableContact must have at least an application ID, returned from the interface's
getApplicationID()
method, and a contact ID, returned from
getContactID().
Your contact class can directly implement LinkableContact, or it can extend one of the helper classes in the Contact Linking API,
AbstractLinkableContact or
DefaultLinkableContact.
Here is a LinkableContact that extends AbstractLinkableContact:
public final class SampleContact extends AbstractLinkableContact
{
String _contactID;
// Creates a new SampleContact object
// contactId is the login ID for a new SampleContact
public SampleContact(String contactId)
{
_contactID = contactId;
}
// Displays the contact's name
public String toString()
{
return getString(LinkableContact.NAME);
}
// LinkableContact method
public long getApplicationID()
{
return ContactLinkingDemo.APPLICATION_ID;
}
// LinkableContact method
public String getContactID()
{
return _contactID;
}
} |
Before linking contacts from your application, you must define a class that extends LinkedContactInfoProvider and register the class with your application.
LinkedContactInfoProvider supplies the information about a linked contact that is displayed in the Contacts application when the user views a contact in the Contacts application.
The underlying framework determines how the information is displayed in the Contacts application.
To define the information provider for your linkable contact:
LinkedContactInfoProvider.getAppImage() and specify the icon that represents your application. The method must return an image in order for any information to be displayed for your linked contact when a user views a contact in the Contacts application.getAppName() and specify the name of your application. The method must return a name in order for information about the linked contact to display when a user edits a contact in the Contacts application. isSupported() to indicate which LinkedContactInfoProvider fields (user name, availability, and/or status) your application supports. By default, a field is not supported. You only need to implement isSupported() if your application supports any of the fields.requestFields() to specify the information to display for the contact in the Contacts application. This method is called by the framework when it needs to display information for the linked contact in the Contacts application. Specify the contact's name, status, and current availability, depending on which fields you defined as supported in isSupported().Here is the implementation of LinkedContactInfoProvider in the Contact Linking Demo sample application. The image and application name are set when the information provider is constructed. The information provider supports all the fields defined in LinkedContactInfoProvider.
public class SampleLinkedContactInfoProvider extends LinkedContactInfoProvider
{
private Image _image;
private String _appName;
public SampleLinkedContactInfoProvider(Image image, String appName)
{
_image = image;
_appName = appName;
}
public Image getAppImage()
{
return _image;
}
public String getAppName()
{
return _appName;
}
public boolean isSupported(int capability)
{
switch(capability)
{
case LinkedContactInfoProvider.STATUS:
case LinkedContactInfoProvider.AVAILABILITY:
case LinkedContactInfoProvider.USER_NAME:
return true;
default:
return false;
}
}
public void requestFields(String contactID, final LinkedContactCallback callback, int fields)
{
LinkableContact contact = ContactListScreen.getUserForID(contactID);
if((fields & LinkedContactInfoProvider.AVAILABILITY) != 0)
{
callback.setAvailability(LinkedContactInfoProvider.AVAILABILITY_ONLINE);
}
if((fields & LinkedContactInfoProvider.STATUS) != 0)
{
callback.setStatusString("<Sample contact status>");
}
if((fields & LinkedContactInfoProvider.USER_NAME) != 0)
{
callback.setUserName(contact.toString());
}
}
}
|
After creating a LinkedContactInfoProvider, you register it with your application using
registerLinkedContactInfoProvider() The method takes the information provider, the application ID, and the application group for your application, using the LinkedContactConstants interface.
The following code sample registers an application as a social networking application.
LinkedContactUtilities.registerLinkedContactInfoProvider(
new SampleLinkedContactInfoProvider(imageBlue, "Demo App 1"),
APPLICATION_ID,
LinkedContactConstants.COMPOSE_SN_MENU_GROUP);
|
When a user displays a contact in the Contacts application that is linked to one of your contacts, the information that you defined in your information provider displays on the contact screen. The framework determines the layout of the information. In this example, because the application was defined as a social networking application, the information displays in the Social Networks section of the contact.
Though not required in contact linking, you can create menu items that are available in the Contacts application when a user views a contact that is linked with a contact in your application. For example, you might want menu items that invoke your application or that allow users to add notes to the Contacts application about the contact in your application.
You use registerMenuItems() to register menu items with your application. When using this method, you must assign a menu item to an application group.
For more information about how menu items are grouped in the Contacts application when there are multiple linked contacts, see the BlackBerry Java SDK Integration Development Guide.
To create menu items:
ApplicationMenuItem.The following code sample illustrates these steps.
public static final long APPLICATION_ID = 0x1eredfe71d34760fdL;
ApplicationDescriptor appdesc = new
ApplicationDescriptor(ApplicationDescriptor.currentApplicationDescriptor(),
"Linking Application", null);
public class LinkedMenuItem extends ApplicationMenuItem {...}
ApplicationMenuItem[] items = new ApplicationMenuItem[1];
items[0] = new LinkedMenuItem();
LinkedContactUtilities.registerMenuItems(items, APPLICATION_ID,
LinkedContactConstants.COMPOSE_SN_MENU_GROUP, appdesc);
|
You use linkContact() to link a contact in the Contacts application with a LinkableContact. You can use methods in LinkedContactUtilities to help automate the process.
It is up to you to decide how to interact with the user before linking a contact. Here is a simple approach, which involves no user interaction:
getContactLinkCandidate() to see whether there is a contact in the Contacts application with the same email address or phone number as your linkable contact.isContactLinked() to see whether the matching candidate is already linked to a contact in your application.linkContact() to do the linking.
private static void simpleLink(LinkableContact linkableContact)
{
BlackBerryContact bbContact =
LinkedContactUtilities.getContactLinkCandidate(linkableContact);
if(bbContact != null)
{
if(!LinkedContactUtilities.isContactLinked(bbContact,
linkableContact.getApplicationID()))
{
bbContact =
LinkedContactUtilities.linkContact(bbContact, linkableContact);
{
}
}
|
You can also allow the user to decide whether to link to a contact in the Contacts application. For example, if you find a matching contact, you could ask the user whether the user wants to link to the matching contact. If not, you could open the contact list and allow the user to select a contact to link to.
For an example of this approach to linking a contact, see the linkContact() method in the Contact Linking Demo sample application that is included in the BlackBerry Java SDK.
|
|||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | ||||||||
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal