|
|||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | ||||||||
See:
Description
| Interface Summary | |
|---|---|
| AddressBookFieldFactory | A factory for creating custom fields that display in the contacts application when the user views a linked contact. |
| LinkableContact | Represents an object that is linkable with a contact in the contacts application. |
| 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. |
| 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 a custom field 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.
To download a sample application that demonstrates how to use the Contact Linking API, visit www.blackberry.com/go/contactlinkingsample.
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 implements AddressBookFieldFactory and register the class with your application.
AddressBookFieldFactory is an interface that defines one method: createAddressBookField(), which defines a field to add to the contacts application when a user displays a contact that is linked to a contact in your application. The method takes one argument, the contact ID (remember that linkable contacts must define an ID).
Here is an example of an implementation of AddressBookFieldFactory:
public final class SampleAddressBookFieldFactory implements AddressBookFieldFactory
{
private String _applicationName;
// Creates a newSampleAddressBookFieldFactory object
// appName is the name of the application to display in the field
public SampleAddressBookFieldFactory(String appName)
{
_applicationName = appName;
}
// Displays the name of the application and the linked contact
// in the contacts application
public Field createAddressBookField(final String contactID)
{
LinkableContact user = ContactListScreen.getUserForID(contactID);
if(user == null)
{
return null;
}
return new BasicEditField(_applicationName + ": ",
user.getString(LinkableContact.NAME),
BasicEditField.DEFAULT_MAXCHARS,
Field.USE_ALL_WIDTH | Field.READONLY);
}
}
|
After creating an AddressBookFieldFactory, you register it with your application using
registerAddressBookFieldFactory().
AddressBookFieldFactory factory = new SampleAddressBookFieldFactory("Sample App");
LinkedContactUtilities.registerAddressBookFieldFactory(factory, APPLICATION_ID);
|
When a user displays a contact in the contacts application that is linked to one of your contacts, the field you defined in createAddressBookField() displays on the contact screen.
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 contact 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 using the LinkedContactConstants interface.
| Application group | Description |
|---|---|
| COMPOSE_SN_MENU_GROUP | Social networking applications |
| COMPOSE_IM_MENU_GROUP | Instant messaging applications |
| COMPOSE_OTHER_MENU_GROUP | Applications that are not social networking or instant messaging applications |
For more information about how menu items are grouped in the contacts application when there are multiple linked contacts, see the BlackBerry Java Application 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.
See the linkContact() method in the sample contact linking application for an example of this approach to linking a contact. To download the sample application, visit www.blackberry.com/go/contactlinkingsample.
|
|||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | ||||||||
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.